跳转至

EmbeddingService 概览 / EmbeddingService Overview

EmbeddingService 为 RAG 摄取与检索链路提供统一的文本向量生成能力。它位于 ChunkingService 之后，被 IngestionService 和 RAGRetrievalService 直接复用。

本文聚焦模块职责、入口对象和集成方式；具体类、方法、参数与返回值以 核心服务 API 参考 中的自动渲染内容为准。

何时阅读本页 / When to Read This Page

适合在以下场景阅读本页：

  • 需要理解嵌入服务在 RAG 主链路中的位置
  • 需要选择 local 或 api 类型的 embedding backend
  • 需要判断何时使用单例工厂、何时显式注入依赖
  • 需要排查模型预热、配置或离线加载问题

关键文件 / Key Files

路径 作用
ai_service/services/embedding.py EmbeddingService、健康检查结果模型和单例工厂的源码入口
配置参考 embedding 与 timeouts 相关配置项说明
Embedding 模型可移植性 本地模型目录、离线模式和预下载策略
核心服务 API 参考 EmbeddingService、EmbeddingReadinessResult、get_embedding_service 的源码级说明

核心类与函数 / Core Classes and Functions

  • EmbeddingService 用于统一路由文本嵌入请求，并根据配置选择 local 或 api backend。
  • EmbeddingReadinessResult 用于表达模型预热或健康检查结果，适合启动前检查和运维诊断。
  • get_embedding_service 提供应用级单例入口，避免重复初始化模型或远端客户端。

规则：本页不再手工维护方法签名。对象级细节请以 核心服务 API 参考 为准。

数据流 / Data Flow

flowchart LR
    A[Caller] --> B[EmbeddingService]
    B --> C[Resolve backend and provider]
    C --> D{backend_type}
    D -->|local| E["sentence_transformers model"]
    D -->|api| F["DashScope compatible endpoint"]
    E --> G[Embedding vector]
    F --> G

配置与运行约定 / Configuration and Runtime Notes

Backend 选择

  • backend_type=local 时，服务使用本地 sentence_transformers 模型。
  • backend_type=api 时，服务使用兼容 OpenAI embedding 接口的远端 provider。
  • provider 与 backend_type 必须匹配；不匹配时会在初始化阶段失败，而不是等到第一次请求时才暴露问题。

模型来源

  • 本地 backend 优先从项目内模型目录读取，其次再回退到本地缓存。
  • 开启离线模式时，仅允许使用本地目录或缓存，不会访问外部模型源。
  • 远端 backend 的凭据与 base_url 从统一模型配置中解析。

预热与健康检查

  • 在服务启动或部署前，可通过 check_readiness() 提前暴露配置、凭据、网络和维度问题。
  • 如果调用链会频繁生成 embedding，优先复用单例而不是每次重新实例化。

更完整的配置字段见 配置参考。

常见集成模式 / Common Integration Patterns

应用级单例

适用于大多数运行时路径：

from ai_service.services.rag.embedding import get_embedding_service

embedding_service = get_embedding_service()
readiness_result = embedding_service.check_readiness()

显式依赖注入

适用于测试、实验性配置或需要覆盖 backend/provider 的场景：

from ai_service.services.rag.embedding import EmbeddingService

embedding_service = EmbeddingService(
    backend_type="local",
    provider="sentence_transformers",
)

不应在本页重复维护的内容 / What This Page Should Not Duplicate

以下内容应留在 API 参考或配置页，而不是继续堆在模块页中：

  • 方法签名、参数和返回值明细
  • 每个结果模型的字段表
  • 与源码 docstring 完全重复的异常说明
  • 可以从 mkdocstrings 自动渲染出来的对象描述