Timbr 集成

使用 LangChain Python 集成 Timbr 图。

Timbr将自然语言输入与Timbr的基于本体（Ontology）的语义层集成。利用Timbr强大的本体能力，SDK与Timbr数据模型集成，并利用语义关系和注释，使用户能够使用业务友好的语言查询数据。

Timbr提供了一个预构建的SQL智能体，TimbrSqlAgent，可用于从用户提示、通过语义SQL查询生成和验证，到查询执行和结果分析的全流程。

对于定制化和部分使用，您可以使用我们的5个主要工具与LangChain链和LangGraph节点进行操作：

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

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

有关langchain-timbr集成的完整示例，请参阅demo notebook。

设置

安装

安装包

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模型。

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-5.5"
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-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 - 列出选定知识图谱的本体（Ontology）表示概念
• get_views - 列出选定知识图谱的本体表示视图
• determine_concept - 从用户提示中识别相关概念
• generate_sql - 从自然语言提示生成SQL查询
• validate_sql - 针对Timbr知识图谱模式验证SQL查询
• run_timbr_query - 针对Timbr知识图谱数据库执行（语义和常规）SQL查询
• run_llm_query - 执行智能体（Agent）管道，以确定概念、生成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)

其他资源

• PyPI
• GitHub
• LangChain Timbr文档
• LangGraph Timbr文档

---

官方原文：src/oss/python/integrations/graphs/timbr.mdx · 非官方翻译，译文由 AI 生成，以英文原文为准。