agentic_huge_data_base / wiki
页面 Graphiti · 6.2 嵌入与重排序服务·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 6.2

6.2 · 嵌入与重排序服务（Embedding and Reranking Services）

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节6.2 状态全文译文 模块模型调用与提供方适配、检索、召回与索引、系统架构、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节Embedding and Reranking Services 上一章6.1 下一章6.3
源码线索
  • graphiti_core/cross_encoder/__init__.py
  • graphiti_core/cross_encoder/bge_reranker_client.py
  • graphiti_core/cross_encoder/client.py
  • graphiti_core/cross_encoder/gemini_reranker_client.py
  • graphiti_core/cross_encoder/openai_reranker_client.py
  • graphiti_core/driver/__init__.py
  • graphiti_core/embedder/client.py
  • graphiti_core/embedder/gemini.py
  • graphiti_core/embedder/openai.py
  • graphiti_core/embedder/voyage.py
模块标签
  • 模型调用与提供方适配
  • 检索、召回与索引
  • 系统架构
  • 测试、发布与运维
  • 界面与交互

章节正文

嵌入与重排序服务

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/6.2-embedding-and-reranking-services

嵌入向量与重排序服务

相关源文件

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

  • graphiti_core/cross_encoder/__init__.py
  • graphiti_core/cross_encoder/bge_reranker_client.py
  • graphiti_core/cross_encoder/client.py
  • graphiti_core/cross_encoder/gemini_reranker_client.py
  • graphiti_core/cross_encoder/openai_reranker_client.py
  • graphiti_core/driver/__init__.py
  • graphiti_core/embedder/client.py
  • graphiti_core/embedder/gemini.py
  • graphiti_core/embedder/openai.py
  • graphiti_core/embedder/voyage.py
  • graphiti_core/llm_client/gemini_client.py
  • graphiti_core/llm_client/utils.py
  • tests/cross_encoder/test_gemini_reranker_client.py
  • tests/embedder/embedder_fixtures.py
  • tests/embedder/test_gemini.py
  • tests/embedder/test_openai.py
  • tests/embedder/test_voyage.py
  • tests/llm_client/test_gemini_client.py

目的与范围

本文档介绍 Graphiti 中的嵌入向量与重排序服务抽象。嵌入向量通过将文本转换为向量表示来实现语义相似性搜索，而重排序器则通过计算相关性分数来优化搜索结果。这两种服务都采用了提供者抽象模式，允许在不同的人工智能服务提供者之间切换。

关于知识提取中使用的大语言模型（LLM）服务，请参阅 LLM 客户端架构（6.1）。关于嵌入向量和重排序如何集成到搜索管线中，请参阅 搜索与检索系统（4.3）。关于使用这些服务的提示词模板，请参阅 提示词库与模板（6.3）。

系统架构

嵌入向量与重排序服务遵循 Graphiti 的多提供者插件架构，通过提供者特定的客户端实现抽象接口。

自然语言到代码实体空间：服务架构
Graphiti · 自然语言到代码实体空间：服务架构 · 图 1
Graphiti · 自然语言到代码实体空间：服务架构 · 图 1

来源： graphiti_core/embedder/client.py:30-39、graphiti_core/cross_encoder/client.py:1-23、graphiti_core/embedder/gemini.py:50-184、graphiti_core/cross_encoder/gemini_reranker_client.py:43-162

EmbedderClient 接口

基础抽象

EmbedderClient 抽象类定义了生成嵌入向量的核心方法。它允许输入数据为字符串、字符串列表或 Token 化表示 graphiti_core/embedder/client.py:33-34。

方法参数返回值用途
create()input_data: str | list[str] | Iterable[int] | Iterable[Iterable[int]]list[float]生成单个嵌入向量 graphiti_core/embedder/client.py:32-35
create_batch()input_data_list: list[str]list[list[float]]高效生成多个嵌入向量 graphiti_core/embedder/client.py:37-38

EmbedderConfig 基类存储与提供者无关的配置，具体为嵌入向量维度，默认使用环境变量 EMBEDDING_DIM graphiti_core/embedder/client.py:23-27。

来源： graphiti_core/embedder/client.py:23-39

数据流：嵌入向量生成工具

generate_embedding 工具函数负责文本预处理（移除换行符）并记录执行时间用于日志记录 graphiti_core/llm_client/utils.py:25-34。

Graphiti · 数据流：嵌入向量生成工具 · 图 2
Graphiti · 数据流：嵌入向量生成工具 · 图 2

来源： graphiti_core/llm_client/utils.py:25-34、graphiti_core/embedder/client.py:32-35

嵌入向量实现

OpenAIEmbedder

使用 OpenAI 的嵌入向量模型（默认使用 text-embedding-3-small）。它同时支持标准的 AsyncOpenAI 和 AsyncAzureOpenAI 客户端 graphiti_core/embedder/openai.py:24-43。该方法会对生成的向量进行切片，以匹配配置的 embedding_dim graphiti_core/embedder/openai.py:60-66。

提供者： OpenAI API 文件： graphiti_core/embedder/openai.py

VoyageAIEmbedder

使用 Voyage AI 的专用嵌入向量模型，默认使用 voyage-3 graphiti_core/embedder/voyage.py:35-43。它通过将各种可迭代类型转换为字符串列表来处理输入归一化，然后再调用 API graphiti_core/embedder/voyage.py:57-66。

提供者： Voyage AI API 文件： graphiti_core/embedder/voyage.py

GeminiEmbedder

使用 Google 的 google-genai 客户端实现嵌入向量生成。它包含处理特定模型关于批次大小约束的逻辑 graphiti_core/embedder/gemini.py:50-86。

批次处理策略

Gemini API 对每个请求的实例数量有限制：

  • gemini-embedding-001：batch_size = 1 graphiti_core/embedder/gemini.py:79-82
  • 其他模型：DEFAULT_BATCH_SIZE = 100 graphiti_core/embedder/gemini.py:42-84

create_batch 方法实现了回退机制：如果批次请求失败，它会记录警告并尝试逐个处理该批次中的每个项目，以确保可靠性 graphiti_core/embedder/gemini.py:155-181。

来源： graphiti_core/embedder/gemini.py:113-183

CrossEncoderClient 接口

基础抽象

CrossEncoderClient 抽象类定义了一个用于重排序的方法 graphiti_core/cross_encoder/client.py:17-23。

方法参数返回值用途
rank()query: str, passages: list[str]list[tuple[str, float]]按相关性分数对段落进行重排序 graphiti_core/cross_encoder/client.py:21-22

返回的列表包含 (段落, 分数) 元组，按分数降序排列，分数归一化到 [0.0, 1.0] 范围。

来源： graphiti_core/cross_encoder/client.py

交叉编码器实现

OpenAIRerankerClient

使用 OpenAI 的补全 API（默认使用 gpt-4.1-nano）来计算相关性分数 graphiti_core/cross_encoder/openai_reranker_client.py:31-34。

Logprob 排序逻辑

该方法并非简单的补全，而是使用对数概率来确定相关性：

  1. 提示词：要求模型回答 "True" 或 "False" 表示是否相关 graphiti_core/cross_encoder/openai_reranker_client.py:70-79。
  2. Logit 偏置：强制模型偏向布尔 Token graphiti_core/cross_encoder/openai_reranker_client.py:91。
  3. 分数计算：提取最高 Token 的对数概率。如果 Token 是 "true"，则分数为 exp(logprob)。如果是 "false"，则分数为 1 - exp(logprob) graphiti_core/cross_encoder/openai_reranker_client.py:110-113。

来源： graphiti_core/cross_encoder/openai_reranker_client.py:61-118

GeminiRerankerClient

使用 Google 的 Gemini API 实现重排序。由于 Gemini 开发者 API 尚不支持 logprobs，该客户端使用直接的数值评分 graphiti_core/cross_encoder/gemini_reranker_client.py:56-58。

排序算法
  1. 提示词生成：为每个段落创建一个提示词，要求给出 0 到 100 之间的相关性分数 graphiti_core/cross_encoder/gemini_reranker_client.py:85-91。
  2. 并发执行：使用 semaphore_gather 并发执行所有评分请求 graphiti_core/cross_encoder/gemini_reranker_client.py:104-117。
  3. 分数提取：使用正则表达式 \b(\d{1,3})\b 从文本响应中提取数值 graphiti_core/cross_encoder/gemini_reranker_client.py:127。
  4. 归一化：通过除以 100 将分数归一化到 [0.0, 1.0] graphiti_core/cross_encoder/gemini_reranker_client.py:131。

来源： graphiti_core/cross_encoder/gemini_reranker_client.py:73-147

BGERerankerClient

提供 BGE 风格交叉编码器的接口，使用本地 sentence-transformers 库 graphiti_core/cross_encoder/bge_reranker_client.py:24-36。它在执行器中运行同步的 predict 方法，以避免阻塞事件循环 graphiti_core/cross_encoder/bge_reranker_client.py:44-46。

来源： graphiti_core/cross_encoder/bge_reranker_client.py

提供者特定考虑

速率限制处理

嵌入向量和重排序客户端都将提供者特定的错误转换为 Graphiti 内部的 RateLimitError：

  • OpenAI：捕获 openai.RateLimitError graphiti_core/cross_encoder/openai_reranker_client.py:119-120。
  • Gemini：检查错误消息中是否包含 "rate limit"、"quota" 或 "resource_exhausted" 等关键词 graphiti_core/cross_encoder/gemini_reranker_client.py:150-158。
并发与批处理
服务实现策略
嵌入向量GeminiEmbedder使用 batch_size，失败时回退到单个调用 graphiti_core/embedder/gemini.py:133-181。
重排序OpenAIReranker使用 semaphore_gather 并行化每个段落的 API 调用 graphiti_core/cross_encoder/openai_reranker_client.py:84-97。
重排序GeminiReranker使用 semaphore_gather 配合 max_output_tokens=3 实现高效评分 graphiti_core/cross_encoder/gemini_reranker_client.py:104-117。

来源： graphiti_core/embedder/gemini.py:113-183、graphiti_core/cross_encoder/openai_reranker_client.py:84-97、graphiti_core/cross_encoder/gemini_reranker_client.py:104-117