# OmniRAG 

**Repository Path**: uesugi-java/omni-rag

## Basic Information

- **Project Name**: OmniRAG 
- **Description**: RAG知识库系统，支持从非机构化数据，结构化数据，对话上下文采集数据创建知识库，并提供接口提供给Agent使用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# omni-rag 中文项目说明

## 1 项目概览

### 1.1 项目定位

`omni-rag` 是一个企业级 RAG 智能基座系统，用于把外部文档、网页、JSON/XML 结构化数据和长期会话上下文异步写入知识索引，并向上层业务系统、Agent 或应用提供统一查询能力。

系统已经拆分为两个独立运行的应用：

| 应用 | 目录 | 职责 |
| --- | --- | --- |
| ingestion 应用 | `apps/ingestion` | 接收上传、Webhook、HTML URL、JSON/XML、会话上下文，写入任务，投递 RabbitMQ，由 worker 完成解析、拆分、向量化和索引写入。 |
| query 应用 | `apps/query` | 提供同步/异步查询、RAG 文档目录、反馈、知识缺口、后台只读管理、检索、重排、LLM 回答和 Agentic RAG。 |
| shared 公共包 | `shared` | 提供配置、schema、数据库模型、日志、模型生命周期、解析、Milvus、Elasticsearch、运行时工具等两边共享能力。 |

### 1.2 设计原则

- 所有入库入口都是异步提交，只返回任务排队状态，不在 HTTP 请求内执行大文件解析和向量化。
- 文档类输入先转换为 Markdown，再从持久化的 Markdown 文件读取并拆分向量化，避免大内容长期占用内存。
- JSON/XML 作为结构化数据入口单独提交，不与 PDF、Word、Excel、TXT、HTML 等文档上传接口混用。
- LlamaIndex 负责 RAG 核心索引、检索和查询抽象；LangChain 只用于可选 Agentic 编排和工具调用层。
- 启动阶段会检查必要中间件和模型，必要依赖不可用时应快速失败。

## 2 项目结构

### 2.1 顶层目录

| 路径 | 说明 |
| --- | --- |
| `apps/ingestion` | 入库 API、Webhook、MQ 生产者、入库 worker、文档转换和索引写入。 |
| `apps/query` | 查询 API、混合检索、重排、LLM 调用、反馈、缺口和后台管理接口。 |
| `shared` | 两个应用共享的配置、schema、数据库、日志、模型、解析、搜索和向量库封装。 |
| `config` | 主配置文件，当前主要使用 `config/rag_config.yaml`。 |
| `scripts` | 初始化、启动、模型预热、RabbitMQ 测试脚本。 |
| `scripts/sql` | PostgreSQL 元数据表创建、索引创建、校验和删除脚本。 |
| `tests` | 单元测试、ingestion/query/shared 测试。 |
| `models/huggingface` | 默认 Hugging Face 模型缓存目录。 |
| `data/converted_markdown` | 默认转换后 Markdown 文件目录。 |

### 2.2 ingestion 应用结构

| 路径 | 说明 |
| --- | --- |
| `apps/ingestion/main.py` | ingestion FastAPI 入口，只注册入库相关路由，可按配置启动内嵌 worker。 |
| `apps/ingestion/routers` | `documents`、`context`、`html`、`structured_data`、`webhook`、`health` 路由。 |
| `apps/ingestion/services/ingestion_service.py` | 统一任务提交、任务持久化、MQ 投递和 worker 处理逻辑。 |
| `apps/ingestion/workers/ingestion_worker.py` | 独立 RabbitMQ worker 入口。 |
| `apps/ingestion/processing` | 文档入库、LlamaIndex 节点适配、格式处理。 |
| `apps/ingestion/connectors` | RabbitMQ、对象/本地文档存储、Markdown artifact 存储。 |

### 2.3 query 应用结构

| 路径 | 说明 |
| --- | --- |
| `apps/query/main.py` | query FastAPI 入口，只注册查询和后台读侧路由。 |
| `apps/query/routers` | `query`、`documents`、`feedback`、`gaps`、`admin`、`health` 路由。 |
| `apps/query/services/query_service.py` | 查询编排，负责检索、重排、置信度和答案生成。 |
| `apps/query/retrievers` | Milvus 向量检索、Elasticsearch BM25、混合检索、LlamaIndex 查询适配。 |
| `apps/query/rerank` | 重排服务封装。 |
| `apps/query/agents` | 意图路由、置信度、知识缺口和 Agentic RAG。 |

### 2.4 shared 公共包结构

| 路径 | 说明 |
| --- | --- |
| `shared/config/settings.py` | 读取 YAML 配置和环境变量覆盖。 |
| `shared/schemas/__init__.py` | API、任务消息、RAG block、查询结果等 Pydantic schema。 |
| `shared/db/models.py` | PostgreSQL SQLAlchemy 元数据模型。 |
| `shared/db/client.py` | RAGRepository 数据访问封装。 |
| `shared/models` | embedding、reranker、模型下载、缓存、预加载和进程级模型注册表。 |
| `shared/vector_store/milvus_client.py` | Milvus collection 创建、写入、查询、删除和统计。 |
| `shared/search/elasticsearch_client.py` | Elasticsearch BM25 索引创建、写入、查询和删除。 |
| `shared/runtime` | FastAPI 运行时、路由注册、依赖检查。 |
| `shared/parsing` | 文档解析、归一化和文本清洗。 |

## 3 主要功能

### 3.1 异步文档入库

支持 PDF、Word、Excel、TXT、Markdown、HTML 文件上传。文档上传后先落本地存储，再创建 `ingestion_tasks` 任务，投递 RabbitMQ，worker 消费后完成：

1. 文档解析和去噪。
2. 使用 MarkItDown 转换为 Markdown。
3. 将 Markdown 保存到 `converted_markdown_storage.root_dir`。
4. 从 Markdown 文件读取内容。
5. 使用 LlamaIndex 生成节点并拆分为 block。
6. 调用 embedding 模型生成向量。
7. 写入 PostgreSQL、Milvus、Elasticsearch。

### 3.2 HTML URL 入库

`POST /api/v1/html/url` 接收远程 HTML 地址。worker 下载页面、限制页面大小和重定向次数，然后按文档类流程转换为 Markdown 并写入索引。

### 3.3 JSON/XML 结构化数据入库

JSON 和 XML 不走文档上传接口，使用独立结构化数据接口：

- JSON 支持 HTTP body 和 `.json` 文件上传。
- XML 支持 HTTP body 和 `.xml` 文件上传。
- 系统不直接查询外部业务数据库；调用方需要先从自己的数据库查询数据，再以 JSON 或 XML 提交。

### 3.4 Webhook 事件入库

`POST /api/v1/webhook/dms` 接收外部 DMS 或文件系统事件，支持单条事件、数组批次和 `{events: [...]}` 批次。接口完成签名校验、事件解析、幂等检查和任务入队，不在 HTTP 请求内下载、解析或索引文档。

### 3.5 长期会话上下文 RAG

`POST /api/v1/context` 接收对话上下文，保存会话状态，并把会话内容作为长期记忆任务写入 RAG。后续查询可以通过语义检索召回历史上下文。

### 3.6 混合检索与 Agentic RAG

query 应用使用 Milvus 向量召回、Elasticsearch BM25 关键词召回、RRF 融合和 reranker 重排。LlamaIndex 承担核心 RAG 检索与查询能力，LangChain 保留为 Agentic 编排和工具调用层。

## 4 API 接口

### 4.1 通用说明

- 默认 API 前缀：`/api/v1`。
- ingestion 接口负责写侧提交和 worker 入库。
- query 接口负责读侧查询、目录、反馈、缺口和后台管理。
- 入库类接口成功时通常返回 `status=queued`，表示任务已持久化并投递 MQ，不表示索引已经完成。
- 请求会生成或透传 `request_id`，用于串联 API、MQ、worker、数据库、索引和模型日志。

### 4.2 ingestion API

| 方法与路径 | 用途 | 主要入参 | 主要出参 | 语义 |
| --- | --- | --- | --- | --- |
| `GET /api/v1/health` | ingestion 健康检查 | 无 | dependency 状态、worker 状态 | 同步 |
| `POST /api/v1/documents` | 上传 PDF、Word、Excel、TXT、Markdown、HTML 等文档文件 | `file`，`metadata` 表单 JSON；metadata 可含 `source_type`、`source_id`、`title`、`permission`、`tags`、`version` | `document_id`、`task_id`、`status`、`request_id` | 异步提交 |
| `DELETE /api/v1/documents/{source_id}` | 删除已 RAG 的文档数据 | `source_id` 路径参数 | `task_id`、`source_id`、`status=queued`、`request_id` | 异步提交 |
| `POST /api/v1/context` | 写入长期会话上下文 | `user_id`、`session_id`、`messages`、`context`、`metadata`、`permission`、`tags`、`ttl_seconds` | `session_id`、`source_id`、`task_id`、`status=queued`、`request_id` | 异步提交 |
| `POST /api/v1/html/url` | 提交远程 HTML 地址 | `url`、`source_id`、`metadata` | `task_id`、`source_id`、`status=queued`、`request_id` | 异步提交 |
| `POST /api/v1/structured-data/json` | 提交 JSON body | `data`、`dataset_id`、`primary_key`、`version`、`metadata` | `task_id`、`source_id`、`status=queued`、`request_id` | 异步提交 |
| `POST /api/v1/structured-data/json/file` | 上传 `.json` 文件 | `file` | `task_id`、`source_id`、`status=queued`、`request_id` | 异步提交 |
| `POST /api/v1/structured-data/xml` | 提交 XML body | `xml`、`dataset_id`、`version`、`metadata` | `task_id`、`source_id`、`status=queued`、`request_id` | 异步提交 |
| `POST /api/v1/structured-data/xml/file` | 上传 `.xml` 文件 | `file` | `task_id`、`source_id`、`status=queued`、`request_id` | 异步提交 |
| `POST /api/v1/webhook/dms` | 接收 DMS 文档事件 | Header: `X-Webhook-Signature`、`X-Webhook-Event`；Body: 单事件、事件数组或 `{batch_id, events}` | 单事件返回 `event_id`、`task_id`、`source_id`、`status`；批次返回 `batch_id`、`accepted_count`、`items` | 异步提交 |

### 4.3 query API

| 方法与路径 | 用途 | 主要入参 | 主要出参 | 语义 |
| --- | --- | --- | --- | --- |
| `GET /api/v1/health` | query 健康检查 | 无 | PostgreSQL、Milvus、Elasticsearch、model cache、LLM provider 状态 | 同步 |
| `POST /api/v1/query` | 同步 RAG 查询 | `question`、`user_id`、`session_id`、`context`、`filter`、`top_k` | `answer`、`confidence`、`sources`、`request_id`、`processing_time_ms` | 同步，有超时和并发控制 |
| `POST /api/v1/query/async` | 异步查询提交 | 同 `POST /query` | `task_id`、`status`、`request_id` | 异步提交 |
| `GET /api/v1/documents/rag` | 查询已 RAG 文档目录 | `limit`、`offset` | `items`、`total`、`limit`、`offset`、`request_id` | 同步 |
| `POST /api/v1/feedback` | 记录用户反馈 | `request_id`、`helpful`、`rating`、`comment`、`correct_answer` | `feedback_id`、`request_id`、`status=recorded` | 同步 |
| `GET /api/v1/gaps/{gap_id}` | 查询知识缺口 | `gap_id` | `gap_id`、`status`、`question`、`reason`、`created_at` | 同步 |
| `POST /api/v1/admin/login` | 后台登录 | `username`、`password` | `access_token`、`token_type`、`expires_in` | 同步 |
| `GET /api/v1/admin/tasks` | 查询任务记录 | Bearer token；`status`、`task_type`、`operation`、`source_id`、`batch_id`、`limit`、`offset` | `items`、`limit`、`offset` | 同步 |
| `GET /api/v1/admin/tasks/{task_id}` | 查询单个任务详情 | Bearer token；`task_id` | `task`、`source`、`logs` | 同步 |
| `GET /api/v1/admin/documents` | 查询文档/来源记录 | Bearer token；`status`、`source_type`、`limit`、`offset` | `items`、`limit`、`offset` | 同步 |
| `GET /api/v1/admin/documents/{source_id}` | 查询单个文档/来源详情 | Bearer token；`source_id` | `source`、`logs` | 同步 |
| `DELETE /api/v1/admin/documents/{source_id}` | 后台读侧删除保护 | Bearer token；`source_id` | 返回 409，提示到 ingestion 服务提交删除 | 同步保护 |
| `GET /api/v1/admin/processing-logs` | 查询处理日志 | Bearer token；`task_id`、`source_id`、`operation`、`outcome`、`limit`、`offset` | `items`、`limit`、`offset` | 同步 |
| `GET /api/v1/admin/vector-store` | 查询向量库概览 | Bearer token | collection、dimension、metric、storage_mode、vector_count | 同步 |

### 4.4 查询请求 JSON 示例

```json
{
  "question": "请总结已经入库文档中的系统架构设计。",
  "user_id": "u-001",
  "session_id": "s-001",
  "context": {
    "tenant": "default"
  },
  "filter": {
    "source_type": "upload",
    "permission": "public"
  },
  "top_k": 10
}
```

## 5 处理流程

### 5.1 入库流程图

```mermaid
flowchart TD
    A["调用方提交 HTTP 请求"] --> B["ingestion API 校验入参"]
    B --> C["保存文件或 payload 引用"]
    C --> D["写入 ingestion_tasks 和 rag_sources"]
    D --> E["发布 RabbitMQ 消息"]
    E --> F["rag_exchange direct"]
    F --> G["rag_queue"]
    G --> H["IngestionWorker 协程消费"]
    H --> I{"任务类型"}
    I -->|文档/HTML| J["MarkItDown 转 Markdown"]
    I -->|JSON/XML/上下文| K["结构化文本展开"]
    J --> L["保存 converted Markdown 文件"]
    L --> M["从 markdown_uri 读取文本"]
    K --> M
    M --> N["LlamaIndex 节点拆分"]
    N --> O["Embedding 生成向量"]
    O --> P["PostgreSQL 写 documents/blocks/logs"]
    O --> Q["Milvus 写 rag_vectors"]
    O --> R["Elasticsearch 写 rag_bm25"]
    P --> S["更新任务和来源状态"]
    Q --> S
    R --> S
```

### 5.2 查询时序图

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant API as query API
    participant Service as QueryService
    participant Milvus as Milvus
    participant ES as Elasticsearch
    participant Rerank as Reranker
    participant LLM as LLM Provider
    participant DB as PostgreSQL

    Client->>API: POST /api/v1/query
    API->>Service: 传入 QueryRequest 和 request_id
    Service->>Milvus: 向量召回
    Service->>ES: BM25 召回
    Milvus-->>Service: vector sources
    ES-->>Service: bm25 sources
    Service->>Service: RRF 融合
    Service->>Rerank: 重排候选 sources
    Rerank-->>Service: rerank_score
    Service->>LLM: 基于 sources 生成答案
    LLM-->>Service: answer
    Service->>DB: 写 query_logs 和可能的 gaps
    Service-->>API: QueryResponse
    API-->>Client: answer/confidence/sources/request_id
```

### 5.3 Webhook 批处理时序图

```mermaid
sequenceDiagram
    participant DMS as 外部 DMS
    participant API as ingestion webhook
    participant DB as PostgreSQL
    participant MQ as RabbitMQ
    participant Worker as IngestionWorker

    DMS->>API: POST /api/v1/webhook/dms events[1..n]
    API->>API: HMAC 签名校验和 JSON 解析
    loop 每个事件
        API->>DB: 检查 event_id 幂等并写任务
        API->>MQ: 发布统一 IngestionTaskMessage
    end
    API-->>DMS: batch_id/items/status
    MQ-->>Worker: rag_task
    Worker->>DB: 更新 processing/completed/failed
```

## 6 模型说明

### 6.1 默认模型

| 角色 | 默认模型 | 配置位置 | 说明 |
| --- | --- | --- | --- |
| Embedding | `BAAI/bge-large-zh-v1.5` | `embedding.model` | 默认向量维度 `1024`，用于文档 block 和查询向量。 |
| Reranker | `BAAI/bge-reranker-v2-m3` | `reranker.model` | 用于候选结果重排，默认输出 `output_k=10`。 |
| LLM | `deepseek-chat` | `llm.model` | 默认 provider 为 DeepSeek，可通过配置替换。 |

### 6.2 模型缓存与预加载

模型缓存默认目录为 `./models/huggingface`，可通过 `HF_CACHE_DIR` 或 `config/rag_config.yaml` 调整。

启动预加载由 `model_preload` 控制：

| 配置 | 默认值 | 说明 |
| --- | --- | --- |
| `model_preload.enabled` | `true` | 是否启用启动预加载。 |
| `model_preload.fail_fast` | `true` | 模型下载、加载、warmup 失败时终止启动。 |
| `model_preload.embedding_required` | `true` | embedding 模型为必需。 |
| `model_preload.reranker_required` | `true` | reranker 模型为必需。 |
| `model_preload.warmup` | `true` | 启动时执行最小 warmup 调用。 |

`shared/models/model_manager.py` 负责模型下载、缓存解析、进程级注册和预加载。运行时 embedding 和 reranker 调用会复用已加载模型，不应每次重新实例化。

### 6.3 CUDA 依赖

项目依赖中已指定 CUDA 版本 PyTorch 源：

- `torch==2.11.0`
- `torchvision==0.26.0`
- `torchaudio==2.11.0`
- `[[tool.uv.index]] pytorch-cu128`

使用 GPU 时需要确保宿主机 NVIDIA 驱动和 CUDA runtime 与安装包匹配，并在配置中设置：

```yaml
embedding:
  device: "cuda"

reranker:
  device: "cuda"
```

离线环境建议先在可联网环境运行 `uv run python scripts/warm_models.py`，再复制 `HF_CACHE_DIR` 到目标机器，并设置 `HF_LOCAL_FILES_ONLY=true`。

## 7 配置说明

### 7.1 主配置文件

主配置文件是 `config/rag_config.yaml`。敏感值建议通过环境变量覆盖，不要把真实密码、token、API key 提交到仓库。

| 配置域 | 说明 |
| --- | --- |
| `rag` | 应用名称、版本、环境。 |
| `document_ingestion` | 文档存储、文件大小、流式保存 chunk、拆分参数。 |
| `document_parser` | 支持格式、PDF/Word 开关、解析超时。 |
| `document_format_conversion` | MarkItDown 转换、去噪、Excel 限制、Markdown 大小限制。 |
| `converted_markdown_storage` | 转换后 Markdown 保存目录、保留天数、大小限制、删除清理策略。 |
| `vector_db` | Milvus URI、database、collection、维度、索引类型、metric。 |
| `bm25_index` | Elasticsearch 地址、索引名、认证、BM25 参数。 |
| `database.postgresql` | PostgreSQL 连接池和账号配置。 |
| `cache.redis` | Redis 连接和 TTL。 |
| `message_queue` | RabbitMQ 主机、端口、账号、vhost。 |
| `ingestion_queue` | RabbitMQ 业务拓扑、worker 并发、prefetch、重试和 DLQ。 |
| `llama_index` | LlamaIndex reader、node parser、retriever、reranker、query engine。 |
| `langchain_agent` | LangChain Agentic 层开关。 |
| `model_preload` | 模型启动预加载和失败策略。 |
| `dependency_readiness` | 各中间件是否作为启动必需依赖。 |
| `query_execution` | 查询超时、并发、降级策略。 |
| `admin` | 后台 admin 账号、token 密钥、过期时间。 |
| `logging` | JSON 日志级别、输出和文件滚动。 |

### 7.2 常用环境变量

| 环境变量 | 说明 |
| --- | --- |
| `DB_HOST`、`DB_PORT`、`DB_NAME`、`DB_USER`、`DB_PASSWORD` | PostgreSQL 覆盖配置。 |
| `MQ_HOST`、`MQ_PORT`、`MQ_USER`、`MQ_PASSWORD`、`MQ_VHOST` | RabbitMQ 覆盖配置。 |
| `INGESTION_EXCHANGE_NAME`、`INGESTION_QUEUE_NAME`、`INGESTION_ROUTING_KEY` | 入库 MQ 拓扑覆盖。 |
| `INGESTION_WORKER_STARTUP_MODE` | `embedded`、`external` 或 `disabled`。 |
| `ES_URL`、`ES_USERNAME`、`ES_PASSWORD`、`ES_API_KEY` | Elasticsearch 地址和认证。 |
| `MILVUS_URI`、`MILVUS_HOST`、`MILVUS_PORT`、`MILVUS_COLLECTION` | Milvus 连接和 collection。 |
| `HF_CACHE_DIR`、`HF_LOCAL_FILES_ONLY` | Hugging Face 缓存和离线模式。 |
| `LLM_PROVIDER`、`LLM_API_KEY`、`LLM_API_BASE`、`LLM_MODEL` | LLM provider 配置。 |
| `OMNI_RAG_ADMIN_USERNAME`、`OMNI_RAG_ADMIN_PASSWORD`、`OMNI_RAG_ADMIN_TOKEN_SECRET` | 后台管理登录配置。 |
| `OMNI_RAG_STARTUP_CHECK` | 是否启用启动依赖检查。 |
| `OMNI_RAG_ALLOW_MEMORY_FALLBACK` | 是否允许测试用内存 fallback，生产应关闭。 |

## 8 技术栈

### 8.1 后端与工程

| 类型 | 技术 |
| --- | --- |
| 语言 | Python 3.11 |
| 包管理 | uv |
| Web 框架 | FastAPI |
| ASGI | Uvicorn |
| 数据校验 | Pydantic |
| ORM | SQLAlchemy |
| 测试 | pytest、pytest-asyncio |
| 格式化与检查 | black、ruff、mypy |

### 8.2 RAG 与数据组件

| 类型 | 技术 |
| --- | --- |
| RAG 核心 | LlamaIndex |
| Agentic 编排 | LangChain |
| Embedding/Reranker | sentence-transformers、FlagEmbedding |
| 文档转换 | MarkItDown、PyMuPDF、aspose-words-foss、openpyxl |
| 向量数据库 | Milvus、PyMilvus |
| 关键词检索 | Elasticsearch、rank-bm25 本地降级能力 |
| 元数据数据库 | PostgreSQL |
| 消息队列 | RabbitMQ、aio-pika |
| 缓存 | Redis |

## 9 启动、调试与部署

### 9.1 安装依赖

```bash
uv sync
```

### 9.2 初始化数据库、队列和索引

```bash
uv run python scripts/init_db.py
uv run python scripts/init_indexes.py
uv run python scripts/warm_models.py
```

如果需要使用 SQL 脚本初始化 PostgreSQL：

```bash
uv run python scripts/init_db.py --mode sql
```

### 9.3 启动 ingestion

本地一体化模式可以让 ingestion API 启动内嵌 worker，配置项为：

```yaml
ingestion_queue:
  worker_startup_mode: "embedded"
```

启动 ingestion API：

```bash
uv run python scripts/start_ingestion_api.py
```

生产或拆分部署建议使用外部 worker：

```bash
uv run python scripts/start_ingestion_worker.py
```

也可以使用当前 worker 脚本：

```bash
uv run python scripts/run_ingestion_worker.py
```

### 9.4 启动 query

```bash
uv run python scripts/start_query_api.py
```

query 应用不会启动 ingestion worker，也不会注册入库写侧路由。

### 9.5 调试 RabbitMQ

```bash
uv run python scripts/test_rabbitmq.py --url http://localhost:5672/ --username admin --password admin
uv run python scripts/test_rabbitmq.py --url http://localhost:5672/ --username admin --password admin --business-topology --queue rag_queue
```

业务拓扑模式会声明并验证 `rag_exchange`、`rag_queue`、`rag_task`。

### 9.6 运行测试和质量检查

```bash
uv run pytest
uv run ruff check .
uv run black --check .
```

### 9.7 部署注意事项

- PostgreSQL 和 RabbitMQ 默认是必需依赖，未连接成功时启动失败。
- Milvus、Elasticsearch、Redis、对象存储、LLM provider 可通过 `dependency_readiness` 设置是否启动必需。
- 模型预加载默认 fail fast，模型缺失、下载失败、CUDA 不可用都会在启动阶段暴露。
- 生产环境应将 `INGESTION_WORKER_STARTUP_MODE=external`，单独部署 worker 并按 CPU/GPU/内存设置 `worker_concurrency`。
- 生产环境不要开启 `OMNI_RAG_ALLOW_MEMORY_FALLBACK=true`。

## 10 数据库、索引和向量库结构

### 10.1 PostgreSQL 主要表

| 表 | 用途 |
| --- | --- |
| `documents` | RAG 文档主记录，记录来源类型、来源 ID、标题、状态、权限、版本和元数据。 |
| `blocks` | 文档拆分后的知识块，保存内容、token 数、chunk 序号、权限、标签和元数据。 |
| `ingestion_tasks` | 统一入库任务记录，记录任务类型、操作、来源、状态、重试、payload 引用、发布状态和错误。 |
| `rag_sources` | 入库来源目录，记录显示名称、来源 URI、checksum、状态、最新任务、block/vector 计数。 |
| `processing_logs` | 任务处理日志，记录阶段、结果、耗时、worker、错误详情。 |
| `query_logs` | 查询日志，记录 request_id、用户、会话、问题、答案、置信度和 sources。 |
| `feedbacks` | 用户反馈，记录是否有帮助、评分、评论和正确答案。 |
| `gaps` | 知识缺口，记录问题、原因、状态和请求来源。 |
| `sessions` | 会话上下文，记录 user_id、上下文 JSON 和过期时间。 |
| `schemas` | schema 定义记录。 |
| `event_processing` | Webhook 事件处理状态和重试信息。 |
| `document_processing_status` | 文档处理状态、最后事件、错误和重试次数。 |

### 10.2 PostgreSQL 索引

SQL 脚本位于 `scripts/sql`：

| 脚本 | 用途 |
| --- | --- |
| `001_create_metadata_tables.sql` | 创建元数据表。 |
| `002_create_metadata_indexes.sql` | 创建查询和处理所需索引。 |
| `003_verify_metadata_schema.sql` | 校验 schema。 |
| `099_drop_metadata_tables.sql` | 删除元数据表，通常只用于重置环境。 |

代码中还定义了关键 ORM 索引：

- `ix_documents_source_unique`：按 `source_type`、`source_id`、`version` 查询文档。
- `ix_blocks_document_chunk`：按 `document_id` 和 `chunk_index` 查询 block。
- `ix_ingestion_tasks_source_status`：按 `source_id` 和 `status` 查询任务。

### 10.3 RabbitMQ 拓扑

| 项 | 默认值 | 说明 |
| --- | --- | --- |
| Exchange | `rag_exchange` | direct exchange。 |
| Queue | `rag_queue` | 统一入库任务队列。 |
| Routing key | `rag_task` | 普通任务路由键。 |
| Dead letter queue | `rag_queue_dlq` | 失败超过重试上限后的死信队列。 |
| Dead letter routing key | `rag_task_dlq` | 死信路由键。 |

`doc_events` 已不作为运行时业务队列使用。外部事件、文件上传、HTML 下载任务、JSON/XML 提交和上下文写入都会转换为统一的 `IngestionTaskMessage`，投递到 `rag_queue`。

### 10.4 Milvus 向量库结构

| 项 | 默认值 | 说明 |
| --- | --- | --- |
| Database | `RAG` |
| Collection | `rag_vectors` |
| Dimension | `1024` |
| Metric | `IP` |
| Index type | `HNSW` |
| 主键字段 | `id` |
| 向量字段 | `vector` |

写入 payload 主要包含：

- `id`
- `vector`
- `content`
- `source_id`
- `source_type`
- `document_id`
- `metadata`

Milvus collection 会在 `scripts/init_indexes.py` 或首次写入/查询前通过 `ensure_collection()` 校验，不存在时创建。

### 10.5 Elasticsearch 索引结构

| 项 | 默认值 | 说明 |
| --- | --- | --- |
| Index | `rag_bm25` |
| Analyzer | `standard` |
| 用途 | BM25/关键词检索 |

主要 mapping 字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `content` | `text` | 知识块文本。 |
| `source_id` | `keyword` | 来源 ID。 |
| `source_type` | `keyword` | 来源类型。 |
| `permission` | `keyword` | 权限。 |
| `tags` | `keyword` | 标签。 |
| `timestamp` | `date` | 时间戳。 |

### 10.6 converted Markdown artifact

文档类输入转换后的 Markdown 默认保存在：

```yaml
converted_markdown_storage:
  provider: local
  root_dir: ./data/converted_markdown
  retention_days: 30
  max_file_size_mb: 100
  max_directory_size_mb: 10240
  cleanup_on_delete: true
```

相关元数据会进入 task、source、block 或 admin 响应：

- `markdown_artifact_id`
- `markdown_uri`
- `markdown_checksum`
- `markdown_size_bytes`
- `normalized_format`
- `converter`

日志和后台接口只暴露 artifact 元信息，不返回完整 Markdown 内容。

## 11 日志与排障

### 11.1 日志格式

系统使用结构化 JSON 日志，关键字段包括：

- `timestamp`
- `level`
- `service`
- `event`
- `request_id`
- `task_id`
- `source_id`
- `event_id`
- `batch_id`
- `operation`
- `duration_ms`
- `outcome`
- `error_detail`

敏感字段如 `password`、`token`、`secret`、`api_key`、`authorization`、`signature`、`bearer_token` 应被脱敏。

### 11.2 常见排障点

| 现象 | 检查方向 |
| --- | --- |
| 启动失败 | 检查 `dependency.check.error`、数据库、RabbitMQ、模型缓存和 `dependency_readiness`。 |
| 消息未消费 | 检查 `mq.consume.start`、`mq.consume.received`、worker 是否独立启动或 embedded。 |
| RabbitMQ 发布失败 | 检查 `mq.connect.*`、`mq.declare.*`、`mq.publish.error`。 |
| Milvus 无向量 | 检查 `vector.write`、`storage_mode=milvus`、collection 名、dimension 和 `scripts/init_indexes.py`。 |
| 查询超时 | 检查 `query.execution.timeout`、`query_execution` 超时配置、Milvus/ES/reranker/LLM 状态。 |
| Word/PDF 出现二进制文本 | 检查 MarkItDown 转换、`document.convert.error`、converted Markdown artifact。 |

## 12 编码与文档规范

### 12.1 编码要求

- 所有 Markdown 文档使用 UTF-8 编码。
- 不复制历史乱码文本。
- 命令、路径、配置键、API 路径和代码标识符保留英文。
- 中文正文提交前应检查是否包含明显乱码字符。

### 12.2 注释规范

Python 公共模块、类、函数和复杂服务方法应遵循 PEP 8、PEP 257 和 Google Style docstring。注释应说明意图、边界、幂等、重试、降级和运维取舍，不重复显而易见的代码。