Timbr 集成 - 以编程方式使用文档

>Timbr 将自然语言输入与 Timbr 的本体驱动语义层相集成。利用 Timbr 强大的本体功能，SDK 与 Timbr 数据模型集成，并利用语义关系和注解，使用户能够使用业务友好的语言查询数据。

>Timbr 提供了一个预构建的 SQL 代理， TimbrSqlAgent，可用于从用户提示、语义 SQL 查询生成和验证、到查询执行和结果分析的端到端目的。

>对于自定义和部分使用，您可以将 LangChain chains 和 LangGraph 节点与我们的 5 个主要工具结合使用：

>- IdentifyTimbrConceptChain & IdentifyConceptNode - 从用户提示中识别相关概念 >- GenerateTimbrSqlChain & GenerateTimbrSqlNode - 从自然语言提示生成 SQL 查询 >- ValidateTimbrSqlChain & ValidateSemanticSqlNode - 根据 Timbr 知识图谱模式验证 SQL 查询 >- ExecuteTimbrQueryChain & ExecuteSemanticQueryNode - 针对 Timbr 知识图谱数据库执行（语义和常规）SQL 查询 >- GenerateAnswerChain & GenerateResponseNode - 根据给定的提示和数据行生成人类可读的答案

>此外， langchain-timbr 提供了 TimbrLlmConnector 用于使用 LLM 提供商手动集成 Timbr 的语义层。

有关 langchain-timbr 集成的完整示例，请参阅演示笔记本.

设置

安装

安装该包

pip install langchain-timbr

可选：安装选定的 LLM 提供商

选择其中之一： openai, anthropic, google, azure_openai, snowflake, databricks, vertex_ai (or 'all')

pip install 'langchain-timbr[<your selected providers, separated by comma without spaces>]'

本指南默认使用 OpenAI 模型。

if "OPENAI_API_KEY" not in os.environ:
    os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI API Key:")

配置

从 langchain-timbr v2.0.0 开始，所有 chains、agents 和 nodes 都支持可选的基于环境的配置。您可以设置以下环境变量来提供默认值并简化提供的工具的设置：

Timbr 连接参数

- TIMBR_URL: 默认 Timbr 服务器 URL
- TIMBR_TOKEN: 默认 Timbr 身份验证令牌
- TIMBR_ONTOLOGY: Default ontology/knowledge graph name

设置这些环境变量后，相应的参数 (url, token, ontology) 在所有 chain 和 agent 构造函数中变为可选，并将使用环境值作为默认值。

LLM 配置参数

LLM_TYPE: LLM 提供商类型（langchain 之一_timbr LlmTypes 枚举：'openai-chat'、'anthropic-chat'、'chat-google-generative-ai'、'azure-openai-chat'、'snowflake-cortex'、'chat-databricks'）
LLM_API_KEY: 用于向 LLM 提供商进行身份验证的 API 密钥
LLM_MODEL: 要使用的模型名称或部署
LLM_TEMPERATURE: LLM 的温度设置
LLM_ADDITIONAL_PARAMS: 作为字典或 JSON 字符串的附加参数

设置 LLM 环境变量后， llm 参数变为可选，并将使用 LlmWrapper 与环境配置一起使用。

环境设置示例：

# Timbr connection




# LLM configuration

查询语义层

We can now use Timbr's chains to query the semantic layer. Import and utilize your intended chain/node, or use TimbrLlmConnector to manually integrate with Timbr's semantic layer.

from langchain_timbr import ExecuteTimbrQueryChain
from langchain_openai import ChatOpenAI

# You can use the standard LangChain ChatOpenAI/ChatAnthropic models
# or any other LLM model based on langchain_core.language_models.chat.BaseChatModel
llm = ChatOpenAI(model="gpt-5.5", temperature=0, openai_api_key="open-ai-api-key")

# Optional alternative: Use Timbr's LlmWrapper, which provides generic connections to different LLM providers
from langchain_timbr import LlmWrapper, LlmTypes
llm = LlmWrapper(llm_type=LlmTypes.OpenAI, api_key="open-ai-api-key", model="gpt-5.5")

ExecuteTimbrQueryChain 示例

execute_timbr_query_chain = ExecuteTimbrQueryChain(
    llm=llm,
    url="https://your-timbr-app.com/",
    token="tk_XXXXXXXXXXXXXXXXXXXXXXXX",
    ontology="timbr_knowledge_graph",
    schema="dtimbr",              # optional
    concept="Sales",              # optional
    concepts_list=["Sales","Orders"],  # optional
    views_list=["sales_view"],         # optional
    note="We only need sums",     # optional
    retries=3,                    # optional
    should_validate_sql=True      # optional
)

result = execute_timbr_query_chain.invoke({"prompt": "What are the total sales for last month?"})
rows = result["rows"]
sql = result["sql"]
concept = result["concept"]
schema = result["schema"]
error = result.get("error", None)

usage_metadata = result.get("execute_timbr_usage_metadata", {})
determine_concept_usage = usage_metadata.get('determine_concept', {})
generate_sql_usage = usage_metadata.get('generate_sql', {})
# Each usage_metadata item contains:
# * 'approximate': Estimated token count calculated before invoking the LLM
# * 'input_tokens'/'output_tokens'/'total_tokens'/etc.: Actual token usage metrics returned by the LLM

{'rows': [{'total_sales': 150000}], 'sql': 'SELECT SUM(amount) as total_sales FROM sales WHERE date >= DATEADD(month, -1, GETDATE())', 'concept': 'Sales', 'schema': 'dtimbr'}

使用 SequentialChain 处理多条链

您可以组合多条 Timbr 链来创建更复杂的工作流程。

from langchain_classic.chains import SequentialChain
from langchain_timbr import ExecuteTimbrQueryChain, GenerateAnswerChain

execute_timbr_query_chain = ExecuteTimbrQueryChain(
    llm=llm,
    url='https://your-timbr-app.com/',
    token='tk_XXXXXXXXXXXXXXXXXXXXXXXX',
    ontology='timbr_knowledge_graph',
)

generate_answer_chain = GenerateAnswerChain(
    llm=llm,
    url='https://your-timbr-app.com/',
    token='tk_XXXXXXXXXXXXXXXXXXXXXXXX',
)

pipeline = SequentialChain(
    chains=[execute_timbr_query_chain, generate_answer_chain],
    input_variables=["prompt"],
    output_variables=["answer", "sql"]
)

result = pipeline.invoke({"prompt": "What are the total sales for last month?"})

{'prompt': 'What are the total sales for last month?', 'answer': 'Based on the query results, the total sales for last month amount to $150,000.', 'sql': 'SELECT SUM(amount) as total_sales FROM sales WHERE date >= DATEADD(month, -1, GETDATE())'}

使用 TimbrLlmConnector

对于与 Timbr 语义层的手动集成，您可以使用 TimbrLlmConnector 它包含以下方法：

- get_ontologies - 列出 Timbr 的语义知识图谱
- get_concepts - 列出所选知识图谱本体表示概念
- get_views - 列出所选知识图谱本体表示视图
- determine_concept - 从用户提示中识别相关概念
- generate_sql - 从自然语言提示生成 SQL 查询
- validate_sql - 根据 Timbr 知识图谱架构验证 SQL 查询
- run_timbr_query - 对 Timbr 知识图谱数据库执行（语义和常规）SQL 查询
- run_llm_query - 执行代理管道以确定概念、生成 SQL 并从自然语言提示运行查询

from langchain_timbr import TimbrLlmConnector

connector = TimbrLlmConnector(
    llm=llm,
    url="https://your-timbr-app.com/",
    token="tk_XXXXXXXXXXXXXXXXXXXXXXXX",
    ontology="timbr_knowledge_graph"
)

# Get available concepts
concepts = connector.get_concepts()
print("Available concepts:", concepts)

# Run a complete query pipeline
result = connector.run_llm_query("What are the top 5 customers by revenue?")
print("Query result:", result)

设置

安装

安装该包

可选：安装选定的 LLM 提供商

配置

Timbr 连接参数

LLM 配置参数

查询语义层

ExecuteTimbrQueryChain 示例

使用 SequentialChain 处理多条链

使用 TimbrLlmConnector

其他资源