Skip to main content
Timbr 将自然语言输入与 Timbr 的本体驱动语义层相结合。利用 Timbr 强大的本体能力，SDK 与 Timbr 数据模型集成，并利用语义关系和注释，使用户能够使用业务友好型语言查询数据。
Timbr 提供了一个预构建的 SQL 智能体 TimbrSqlAgent，可用于端到端目的：从用户提示，通过语义 SQL 查询生成与验证，到查询执行和结果分析。
对于自定义和部分使用，你可以将 LangChain 链和 LangGraph 节点与我们的 5 个主要工具结合使用：
  • IdentifyTimbrConceptChain 和 IdentifyConceptNode - 从用户提示中识别相关概念
  • GenerateTimbrSqlChain 和 GenerateTimbrSqlNode - 从自然语言提示生成 SQL 查询
  • ValidateTimbrSqlChain 和 ValidateSemanticSqlNode - 针对 Timbr 知识图谱 schema 验证 SQL 查询
  • ExecuteTimbrQueryChain 和 ExecuteSemanticQueryNode - 在 Timbr 知识图谱数据库上执行（语义和常规）SQL 查询
  • GenerateAnswerChain 和 GenerateResponseNode - 根据给定提示和数据行生成人类可读的答案
此外，langchain-timbr 提供 TimbrLlmConnector，用于使用 LLM 提供商与 Timbr 语义层进行手动集成。
有关 langchain-timbr 集成的完整示例，请参阅演示 notebook。

​
配置

​
安装

​
安装包

pip install langchain-timbr

​
可选：安装时选择 LLM 提供商

从以下选项中选择：openai, anthropic, google, azure_openai, snowflake, databricks, vertex_ai（或 'all'） 
pip install 'langchain-timbr[<your selected providers, separated by comma without spaces>]'
本指南默认使用 OpenAI 模型。 
import getpass
import os

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

​
配置参数

从 langchain-timbr v2.0.0 开始，所有链、智能体和节点都支持可选的基于环境变量的配置。你可以设置以下环境变量来提供默认值，简化所提供工具的配置：

​
Timbr 连接参数

  • TIMBR_URL：默认 Timbr 服务器 URL
  • TIMBR_TOKEN：默认 Timbr 认证令牌
  • TIMBR_ONTOLOGY：默认本体/知识图谱名称
设置这些环境变量后，所有链和智能体构造函数中对应的参数（url、token、ontology）将变为可选，并使用环境变量值作为默认值。

​
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
export TIMBR_URL="https://your-timbr-app.com/"
export TIMBR_TOKEN="tk_XXXXXXXXXXXXXXXXXXXXXXXX"
export TIMBR_ONTOLOGY="timbr_knowledge_graph"

# LLM configuration
export LLM_TYPE="openai-chat"
export LLM_API_KEY="your-openai-api-key"
export LLM_MODEL="gpt-4.1"
export LLM_TEMPERATURE="0.1"
export LLM_ADDITIONAL_PARAMS='{"max_tokens": 1000}'

​
查询语义层

现在可以使用 Timbr 的链来查询语义层。导入并使用你所需的链/节点，或使用 TimbrLlmConnector 手动与 Timbr 的语义层集成。 
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-4.1", 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-4.1")

​
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 知识图谱 schema 验证 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)

​
其他资源

在 GitHub 上编辑此页面 或提交问题。
将这些文档连接到 Claude、VSCode 等工具，通过 MCP 获取实时答案。