跳转至

Services 模块概览

Services 模块（ai_service/services）提供 RAG 知识库的摄取与检索核心能力，位于 API 层之下、存储层之上。它负责把原始文件转成可检索的文本块与向量，并在查询时组装上下文供编排器或 LLM 使用。

模块分层与依赖关系

Services 模块按“基础能力 → 业务编排 → 检索服务”的层级组织，外部存储作为依赖边界：

flowchart TB
  subgraph 基础能力层
    Parser[Parser 子系统]
    Chunking[ChunkingService]
    Embedding[EmbeddingService]
  end

  subgraph 编排层
    Ingestion[IngestionService]
  end

  subgraph 检索层
    Retrieval[RAGRetrievalService]
  end

  subgraph 外部依赖
    MinIO[MinIO]
    Postgres[PostgreSQL]
    Qdrant[Qdrant]
  end

  Ingestion --> Parser
  Ingestion --> Chunking
  Ingestion --> Embedding
  Ingestion --> MinIO
  Ingestion --> Postgres
  Ingestion --> Qdrant

  Retrieval --> Embedding
  Retrieval --> Postgres
  Retrieval --> Qdrant

这张图强调“层级关系”：解析、分块、嵌入是基础能力；摄取是编排层；检索是对外提供知识上下文的服务层；存储是外部依赖。

服务清单

  • Parser 子系统：按内容类型选择解析器，把文档字节转成纯文本与元数据。
  • ChunkingService：将长文本按可配置的大小与重叠策略切分为文本块。
  • EmbeddingService：加载并缓存嵌入模型，生成文本向量。
  • IngestionService：编排摄取流程，串联解析、分块、嵌入与存储。
  • RAGRetrievalService：基于查询向量检索相关文本块，并格式化上下文。

快速上手

文档摄取

from ai_service.services.ingestion import get_ingestion_service

# 获取摄取服务实例
ingestion_service = get_ingestion_service()

# 处理已上传到 MinIO 的文档
chunks_created, chunks_indexed = ingestion_service.process_document(
    document_id="doc-123",
    agent_id="agent-456"
)

print(f"处理完成: 创建 {chunks_created} 个分块，索引 {chunks_indexed} 个向量")

知识检索

from ai_service.services.rag_retrieval import get_rag_service

# 获取检索服务实例
rag_service = get_rag_service()

# 检索相关上下文
context = rag_service.retrieve_and_format(
    query="退款政策是什么？",
    agent_id="agent-456",
    top_k=5,
    score_threshold=0.3
)

print(f"检索上下文:\n{context}")

何时使用各服务

ChunkingService

  • 需要把长文档切成可嵌入的文本块
  • 希望控制分块大小与重叠策略
  • 需要保留文档元数据

EmbeddingService

  • 需要生成文本向量或批量向量
  • 需要离线模型加载与健康检查
  • 需要复用模型以减少加载开销

IngestionService

  • 需要端到端摄取流程
  • 需要处理解析、分块、嵌入与写入存储
  • 需要任务级进度与超时管理

RAGRetrievalService

  • 需要按 Agent 挂载的知识源检索
  • 需要格式化上下文供 LLM 使用
  • 需要控制 top_k 与相似度阈值

服务设计约定

  1. 单例入口：每个服务提供 get_*_service() 工厂函数，减少重复初始化。
  2. 依赖注入：构造函数支持传入自定义依赖，便于测试与替换。
  3. 配置中心：统一从 config 读取参数，但允许构造时覆盖。
  4. 错误可观测：所有服务使用结构化日志记录失败原因。
  5. 类型安全：关键数据结构使用类型注解与 Pydantic 模型。

下一步