6 · AI 服务集成

AI 服务集成

AI 服务集成

相关源文件

以下文件为本维基页面的生成提供了上下文：

• graphiti_core/cross_encoder/__init__.py
• graphiti_core/cross_encoder/bge_reranker_client.py
• graphiti_core/cross_encoder/client.py
• graphiti_core/cross_encoder/openai_reranker_client.py
• graphiti_core/driver/__init__.py
• graphiti_core/embedder/client.py
• graphiti_core/embedder/openai.py
• graphiti_core/embedder/voyage.py
• graphiti_core/llm_client/anthropic_client.py
• graphiti_core/llm_client/client.py
• graphiti_core/llm_client/config.py
• graphiti_core/llm_client/groq_client.py
• graphiti_core/llm_client/openai_base_client.py
• graphiti_core/llm_client/openai_client.py
• graphiti_core/llm_client/openai_generic_client.py
• graphiti_core/llm_client/utils.py

目的与范围

本文档概述了 Graphiti 与外部 AI 服务的集成方式。Graphiti 依赖三种 AI 服务协同工作，以支撑知识图谱的构建和检索：

1. 大语言模型（LLM）——从文本中提取实体和关系、执行去重决策以及生成内容摘要。
2. 嵌入向量模型——生成向量表示，用于语义搜索和节点/边解析。
3. 交叉编码器重排序模型——通过重新评分提升搜索结果的相关性。

系统采用与提供商无关的抽象接口，允许在不修改应用代码的情况下，在多个服务提供商（OpenAI、Anthropic、Google Gemini、Azure OpenAI、Groq、Voyage AI）之间切换。每个提供商实现都扩展了抽象基类：LLMClient graphiti_core/llm_client/client.py:71、EmbedderClient graphiti_core/embedder/client.py:30 和 CrossEncoderClient graphiti_core/cross_encoder/client.py:27。

相关页面：

• LLM 客户端架构——记录 LLMClient 接口、重试逻辑、错误处理、缓存、Token 追踪以及各提供商的具体实现（OpenAI、Anthropic、Gemini、Groq、Azure、GLiNER2）。
• 嵌入向量与重排序服务——解释 EmbedderClient 和 CrossEncoderClient 的实现，包括批处理和各提供商的注意事项。
• 提示词库与模板——记录提示词系统，包括所有提取、去重和摘要提示词及其预期的输入和输出。

AI 服务类型与角色

Graphiti 的知识图谱管线使用三种不同的 AI 服务类型：

大语言模型（LLM）

LLM 在事件入库和图维护期间被调用。LLMClient graphiti_core/llm_client/client.py:71 管理这些调用。关键操作包括：

• 节点提取：从原始文本或消息中识别实体。
• 节点解析：判断提取的节点是否与图中已有实体匹配。
• 边提取：识别实体之间的时间关系和语义关系。
• 摘要生成：为节点和社区生成摘要。

嵌入向量模型

嵌入向量模型生成向量表示并存储在图数据库中。EmbedderClient graphiti_core/embedder/client.py:30 处理这些转换。

• 节点名称嵌入向量：存储在 EntityNode.name_embedding 中。
• 边事实嵌入向量：存储在 EntityEdge.fact_embedding 中。

交叉编码器重排序模型

交叉编码器通过成对相关性评分提升搜索精度。OpenAIRerankerClient graphiti_core/cross_encoder/openai_reranker_client.py:34 使用布尔分类器提示词的对数概率，通过检查查询与段落之间的相关性来对段落进行排序 graphiti_core/cross_encoder/openai_reranker_client.py:70-78。

来源：graphiti_core/llm_client/client.py:71-163、graphiti_core/embedder/client.py:30-38、graphiti_core/cross_encoder/openai_reranker_client.py:34-118

提供商抽象架构

Graphiti 采用多提供商插件架构来支持各种 AI 服务。

自然语言到代码实体空间：LLM 客户端

核心抽象方法

LLMClient 基类提供了共享基础设施：

• 重试逻辑：最多 4 次尝试，采用指数退避策略 graphiti_core/llm_client/client.py:116-119。
• 输入清理：对字符串中的无效 Unicode 和控制字符进行消毒 graphiti_core/llm_client/client.py:94-114。
• 缓存：通过 LLMCache 提供可选的磁盘缓存 graphiti_core/llm_client/client.py:86-89。
• Token 追踪：通过 TokenUsageTracker 监控使用情况 graphiti_core/llm_client/client.py:84。

来源：graphiti_core/llm_client/client.py:71-154、graphiti_core/llm_client/openai_base_client.py:40-78、graphiti_core/embedder/client.py:30-38

代码库中的集成点

AI 服务深度集成在入库和搜索管线中。

自然语言到代码实体空间：管线集成

关键服务使用

• 多语言支持：get_extraction_language_instruction 函数 graphiti_core/llm_client/client.py:38-56 通过向系统消息追加指令 graphiti_core/llm_client/client.py:176，确保提取的信息保留原始语言上下文。
• 结构化补全：OpenAIClient 利用 _create_structured_completion graphiti_core/llm_client/openai_client.py:65-74 实现原生模式解析。AnthropicClient 使用工具调用（通过 _create_tool）实现结构化输出 graphiti_core/llm_client/anthropic_client.py:177-188。
• 批量嵌入向量：EmbedderClient 支持 create_batch graphiti_core/embedder/client.py:37，用于批量入库时的高效处理，由 OpenAIEmbedder graphiti_core/embedder/openai.py:62 和 VoyageAIEmbedder graphiti_core/embedder/voyage.py:71 等提供商实现。

来源：graphiti_core/llm_client/client.py:38-56、graphiti_core/llm_client/openai_client.py:65-101、graphiti_core/embedder/client.py:30-38、graphiti_core/embedder/openai.py:62-67、graphiti_core/embedder/voyage.py:71-77

提供商支持矩阵

LLM 提供商

嵌入向量提供商

来源：graphiti_core/llm_client/anthropic_client.py:49-101、graphiti_core/llm_client/groq_client.py:44-46、graphiti_core/embedder/openai.py:24-32、graphiti_core/embedder/voyage.py:35-43

配置

AI 服务通过 LLMConfig graphiti_core/llm_client/config.py:28 和各提供商特定的嵌入向量配置（如 VoyageAIEmbedderConfig graphiti_core/embedder/voyage.py:38）进行配置。

# 示例 LLM 配置
llm_config = LLMConfig(
    api_key="your-key",
    model="gpt-4o",
    temperature=1.0, # 默认值 [graphiti_core/llm_client/config.py:20]
    max_tokens=16384
)

关于每种服务类型的详细实现和配置，请参考子页面。

来源：graphiti_core/llm_client/config.py:28-69、graphiti_core/embedder/voyage.py:38-41