RAG 知识库管理

本指南描述从“创建知识源”到“完成检索增强”的完整链路，适用于 Admin 前端操作与 API 调用。

总览

RAG 管理流程包含五个核心对象：

Agent
Knowledge Source
Agent Knowledge Link
Document
Ingestion Job

典型流程如下：

flowchart LR
  Agent[创建 Agent] --> Source[创建知识源]
  Source --> Upload[上传文档]
  Upload --> Ingest[触发摄取任务]
  Ingest --> Mount[挂载知识源到 Agent]
  Mount --> Chat[对话请求携带 agent_id]

前置启动

1. 启动基础设施

just docker-infra

2. 启动 AI 服务

uv run python main.py

3. 启动 Admin 前端

cd admin-frontend
npm install
npm run dev

核心操作

步骤一：创建 Agent

POST /agents 可创建 Agent，支持配置：

system_prompt
model_name
model_provider
model_temperature

这些字段会在对话阶段作为默认行为与模型参数来源。

步骤二：创建知识源并配置默认分块

POST /knowledge-sources 关键字段：

default_chunking_strategy：fixed_size、sentence、paragraph、semantic、recursive
default_chunking_params：策略参数字典

示例：

{
  "name": "产品文档库",
  "description": "客服检索知识源",
  "storage_type": "minio",
  "default_chunking_strategy": "sentence",
  "default_chunking_params": {
    "target_size": 600,
    "max_sentences": 12
  }
}

步骤三：上传文档

上传端点：POST /knowledge-sources/{source_id}/documents

支持常见文本与文档格式，包括 .txt、.md、.pdf、.docx。

步骤四：触发摄取任务

触发端点：POST /knowledge-sources/{source_id}/ingest

请求体可覆盖分块策略：

{
  "agent_id": "agent_001",
  "chunking_strategy": "fixed_size",
  "chunking_params": {
    "chunk_size": 700,
    "chunk_overlap": 80
  }
}

任务状态字段：

queued
running
succeeded
failed

可轮询：

GET /knowledge-sources/{source_id}/ingestion-jobs
GET /ingestion-jobs/{job_id}

步骤五：挂载知识源到 Agent

挂载端点：POST /agents/{agent_id}/mounts

示例：

{
  "source_id": "source_001",
  "is_active": true,
  "priority": 10
}

当请求 POST /stream 或 WS /ws/{session_id} 时携带 agent_id，系统会按挂载关系过滤可检索知识源。

建议运维流程

摄取前预热 Embedding 模型

在批量摄取前，可先调用：

POST /embedding-model/check-readiness

这样可以提前触发模型加载，降低首个摄取任务的等待时间。

故障排查顺序

先看 ingestion_jobs.status 与 status_message
再看 documents.status 与 error_message
最后检查 MinIO 对象与 Qdrant 集合可用性

数据层参考

实体与关系：docs/database/schema.md
迁移机制：docs/database/migrations.md
代码级接口：docs/api/storage.md