4.4 · 多提供方插件架构（Multi-Provider Plugin Architecture）

多提供方插件架构

多提供商插件架构

相关源文件

本章引用的主要源码文件：

• 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/driver/driver.py
• graphiti_core/driver/falkordb_driver.py
• graphiti_core/driver/neo4j_driver.py
• graphiti_core/embedder/client.py
• graphiti_core/embedder/openai.py
• graphiti_core/embedder/voyage.py
• graphiti_core/helpers.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 中的四个可插拔提供商子系统：大语言模型（LLM）客户端、嵌入向量（Embedder）客户端、交叉编码器/重排序器（Cross-Encoder/Reranker）客户端和图数据库驱动（Graph Database Driver）。每个子系统都由一个抽象基类（ABC）定义，具体实现可以在构造时进行替换，而无需修改任何核心管线逻辑。

关于图数据库驱动实现的详细文档，请参见数据库抽象层。关于完整的 AI 服务实现列表，请参见大语言模型客户端架构和嵌入向量与重排序服务。

设计总览

Graphiti 将*做什么*（知识图谱操作）与*怎么做*（由哪个服务执行每个步骤）分离开来。Graphiti 类通过构造函数参数接受四个可插拔组件：

每个抽象基类定义了一个最小接口。所有内部管线函数都通过这些接口进行调用，不直接依赖任何提供商 SDK。

整体组合图——Graphiti 及其四个可插拔组件：

来源：graphiti_core/llm_client/client.py:71-84, graphiti_core/embedder/client.py:30-38, graphiti_core/cross_encoder/client.py:20-40, graphiti_core/driver/driver.py:90-115

大语言模型客户端

抽象基类：LLMClient

定义在 graphiti_core/llm_client/client.py 中。每个大语言模型提供商实现都必须继承 LLMClient 并实现 _generate_response 方法 graphiti_core/llm_client/client.py:139-147。

公共接口是 generate_response，它负责处理以下事项：

• 通过 get_extraction_language_instruction 追加多语言提取指令 graphiti_core/llm_client/client.py:176-176。
• 通过可插拔的 Tracer 发出追踪跨度 graphiti_core/llm_client/client.py:182-192。
• 检查可选的 LLMCache graphiti_core/llm_client/client.py:194-203。
• 在 TokenUsageTracker 中记录 Token 使用量 graphiti_core/llm_client/client.py:214-214。
• 调用内部抽象方法 _generate_response_with_retry graphiti_core/llm_client/client.py:127-137。

LLMConfig

所有大语言模型客户端都接受一个 LLMConfig 实例，该实例定义在 graphiti_core/llm_client/config.py:28-68：

ModelSize 枚举（small、medium）控制运行时选择哪个模型名称——small 映射到 small_model，medium 映射到 model graphiti_core/llm_client/config.py:23-25。

具体的大语言模型实现

大语言模型客户端类层次结构：

来源：graphiti_core/llm_client/client.py:71-248, graphiti_core/llm_client/openai_base_client.py:40-296, graphiti_core/llm_client/openai_client.py:27-126, graphiti_core/llm_client/openai_generic_client.py:37-214, graphiti_core/llm_client/anthropic_client.py:103-448, graphiti_core/llm_client/groq_client.py:48-86

提供商对比

OpenAIGenericClient 是推荐用于 Ollama 和其他兼容 OpenAI 的本地端点的客户端。它默认使用 16K Token 限制，而不是标准的 8K，以支持复杂的本地模型提示 graphiti_core/llm_client/openai_generic_client.py:75-75。

嵌入向量客户端

抽象基类：EmbedderClient

定义在 graphiti_core/embedder/client.py:30-38 中。包含两个相关方法：

• create(input_data)——生成单个嵌入向量。
• create_batch(input_data_list)——在单个 API 调用中生成多个嵌入向量。

EmbedderConfig Pydantic 模型 graphiti_core/embedder/client.py:26-27 携带一个字段 embedding_dim。所有嵌入向量配置都继承自 EmbedderConfig。

具体的嵌入向量实现

嵌入向量客户端类层次结构：

来源：graphiti_core/embedder/client.py:26-38, graphiti_core/embedder/openai.py:27-66, graphiti_core/embedder/voyage.py:38-76

交叉编码器/重排序器客户端

抽象基类：CrossEncoderClient

定义在 graphiti_core/cross_encoder/client.py:20-40 中。包含一个抽象方法：

rank(query: str, passages: list[str]) -> list[tuple[str, float]]

返回按相关性分数降序排列的段落。搜索系统使用此方法来优化向量搜索结果。

具体的重排序器实现

交叉编码器客户端类层次结构：

来源：graphiti_core/cross_encoder/client.py:20-40, graphiti_core/cross_encoder/openai_reranker_client.py:34-123, graphiti_core/cross_encoder/bge_reranker_client.py:34-54

图数据库驱动

GraphDriver 抽象基类是 Graphiti 数据库可移植性的基础。它提供了对专用操作集（例如 entity_node_ops、episode_node_ops）的抽象访问，这些操作集按提供商实现。

高层驱动层次结构：

来源：graphiti_core/driver/driver.py:59-63, graphiti_core/driver/driver.py:90-210

具体的驱动实现

具体的驱动实现了 GraphDriver 接口，并提供面向不同提供方的操作。

• Neo4jDriver：使用 AsyncGraphDatabase 驱动实现与 Neo4j 的连接 graphiti_core/driver/neo4j_driver.py:60-75。它通过 session.begin_transaction() 支持原生事务 graphiti_core/driver/neo4j_driver.py:151-161。
• FalkorDriver：使用 FalkorDB 异步客户端实现与 FalkorDB 的连接 graphiti_core/driver/falkordb_driver.py:110-146。它使用自定义的 FalkorDriverSession graphiti_core/driver/falkordb_driver.py:75-108 来包装查询执行。

可选依赖模式

依赖第三方 SDK 的提供商实现使用 TYPE_CHECKING 守卫配合惰性导入，如果未安装相应的额外依赖，则在运行时抛出描述性的 ImportError。

if TYPE_CHECKING:
    import anthropic
else:
    try:
        import anthropic
    except ImportError:
        raise ImportError(
            'anthropic is required for AnthropicClient. '
            'Install it with: pip install graphiti-core[anthropic]'
        ) from None

来源：graphiti_core/llm_client/anthropic_client.py:31-44, graphiti_core/llm_client/groq_client.py:22-34, graphiti_core/embedder/voyage.py:20-29, graphiti_core/driver/falkordb_driver.py:22-34