> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Timbr 集成

> 使用 LangChain Python 集成 Timbr 图。

> [Timbr](https://docs.timbr.ai/doc/docs/integration/langchain-sdk/)将自然语言输入与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](https://github.com/WPSemantix/Timbr-GenAI/tree/main/LangChain/LangChain_Timbr_Demo.ipynb)。

## 设置

### 安装

#### 安装包

```bash theme={null}
pip install langchain-timbr
```

#### 可选：使用选定的LLM提供者安装

选择一个：`openai, anthropic, google, azure_openai, snowflake, databricks, vertex_ai (or 'all')`

```bash theme={null}
pip install 'langchain-timbr[<your selected providers, separated by comma without spaces>]'
```

在本指南中，我们默认使用OpenAI模型。

```python theme={null}
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`与环境配置。

示例环境设置：

```bash theme={null}
# 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的语义层集成。

```python theme={null}
from langchain_timbr import ExecuteTimbrQueryChain
from langchain_openai import ChatOpenAI
```

```python theme={null}
# 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示例

```python theme={null}
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
```

```python theme={null}
{'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链组合起来创建更复杂的工作流程。

```python theme={null}
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?"})
```

```python theme={null}
{'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并从自然语言提示运行查询

```python theme={null}
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](https://pypi.org/project/langchain-timbr)
* [GitHub](https://github.com/WPSemantix/langchain-timbr)
* [LangChain Timbr文档](https://docs.timbr.ai/doc/docs/integration/langchain-sdk/)
* [LangGraph Timbr文档](https://docs.timbr.ai/doc/docs/integration/langgraph-sdk)

***

> 官方原文：[src/oss/python/integrations/graphs/timbr.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/graphs/timbr.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.