# langchain-study
**Repository Path**: mkee/langchain-study
## Basic Information
- **Project Name**: langchain-study
- **Description**: LangChain + LangGraph 开发本地知识库
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-03
- **Last Updated**: 2026-07-31
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# LangChain RAG 知识库问答系统
基于 **LangGraph + LangChain + FastAPI** 的企业级检索增强生成（RAG）系统，采用 **Hybrid RAG + Reranking** 架构，支持流式输出、多 Agent 协作、权限控制和生产化部署。
---
## 目录
- [系统架构](#系统架构)
- [RAG 工作流程详解](#rag-工作流程详解)
- [项目结构](#项目结构)
- [脚本说明](#脚本说明)
- [scripts/ — 工具脚本](#scripts--工具脚本)
- [core/ — 核心基础设施](#core--核心基础设施)
- [retrieval/ — 检索模块](#retrieval--检索模块)
- [rag/ — RAG 工作流](#rag--rag-工作流)
- [ingestion/ — 文档导入管线](#ingestion--文档导入管线)
- [memory/ — 记忆系统](#memory--记忆系统)
- [agent/ — 多 Agent 协作](#agent--多-agent-协作)
- [evaluation/ — RAG 评估](#evaluation--rag-评估)
- [security/ — 权限控制](#security--权限控制)
- [api/ — API 接口层](#api--api-接口层)
- [web/ — Web 前端](#web--web-前端)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [API 参考](#api-参考)
- [监控与运维](#监控与运维)
---
## 系统架构
### 整体架构图
```
┌─────────────────────────────────────────────────────────────────────┐
│ 用户输入层 │
│ [Vue 3 SPA] [REST API] [文件上传] │
└──────────────────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Query 理解模块 │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ 同义改写 │ │ HyDE 扩展 │ │ 多查询扩展 │ │
│ │ (LLM 改写) │ │ (假设性文档) │ │ (关键词提取) │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
└──────────────────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 混合检索层 │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ 语义检索 (向量) │ │ 关键词检索 (BM25) │ │
│ │ Milvus / Chroma │ │ rank_bm25 │ │
│ │ BGE / DashScope │ │ │ │
│ └──────────┬──────────┘ └──────────┬──────────┘ │
│ │ │ │
│ └──────────┬───────────────┘ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ RRF 融合排序 │ │
│ │ Reciprocal Rank │ │
│ │ Fusion (k=60) │ │
│ └──────────┬──────────┘ │
└──────────────────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 重排序层 │
│ ┌─────────────────────────────────────────────┐ │
│ │ Cross-encoder Reranker │ │
│ │ BAAI/bge-reranker-base / MiniLM │ │
│ │ 对 RRF 结果逐对打分，取 Top-K (5) │ │
│ └─────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 上下文组装层 │
│ ┌─────────────────────────────────────────────┐ │
│ │ 权限过滤 + 记忆注入 + 压缩拼接 │ │
│ │ · 三级权限过滤（公开/部门/机密） │ │
│ │ · 短期记忆（对话窗口）注入 │ │
│ │ · 长期记忆（偏好/实体）注入 │ │
│ │ · 上下文压缩（截断 + 摘要） │ │
│ └─────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LLM 生成层（流式输出） │
│ ┌─────────────────────────────────────────────┐ │
│ │ 智谱 GLM-4.7-Flash（免费） │ │
│ │ · SSE 流式输出 │ │
│ │ · 约束 Prompt（无信息时拒绝回答） │ │
│ │ · 引用来源标注 │ │
│ └─────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 多 Agent 协作层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 检索 Agent │ │ 分析 Agent │ │ 写作 Agent │ │
│ │ (retriever) │ │ (analyzer) │ │ (writer) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 编排器 (Orchestrator)：任务路由 + 消息总线 + 权限继承 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
### 核心设计原则
1. **模块化**：每个功能模块独立封装，通过 `__init__.py` 统一导出
2. **可配置**：所有参数通过 `.env` 文件配置，支持运行时切换
3. **可观测**：内置 Prometheus 指标、调试追踪器、RAG 评估
4. **生产化**：指数退避重试、熔断器保护、令牌桶限流、请求队列
---
## RAG 工作流程详解
### 完整查询流程（LangGraph 工作流）
```
用户提问: "年假怎么请？"
│
▼
┌──────────────┐
│ 1. 查询改写 │ ← QueryRewriter.rewrite()
│ │ 改写为多个同义表达:
│ │ "年假怎么请" → "年假申请流程"
│ │ "年假怎么请" → "如何休年假"
│ │ "年假怎么请" → "带薪年假请假步骤"
└──────┬───────┘
▼
┌──────────────┐
│ 2. 混合检索 │ ← HybridRetriever.hybrid_search()
│ │
│ ┌─────────┐ │ ┌───────────┐
│ │ 语义检索 │ │ │ BM25 检索 │
│ │ (向量) │ │ │ (关键词) │
│ │ 返回 10条│ │ │ 返回 10条 │
│ └────┬────┘ │ └─────┬─────┘
│ └──────┬──────┘
│ ▼
│ ┌──────────────┐
│ │ RRF 融合排序 │ ← reciprocal_rank_fusion(k=60)
│ │ 合并去重后 │
│ │ 返回 12条 │
│ └──────┬───────┘
└───────────┼──────────┘
▼
┌──────────────┐
│ 3. 重排序 │ ← ReRanker.rerank()
│ │ Cross-encoder 逐对打分
│ │ 取 Top-5 最相关文档
└──────┬───────┘
▼
┌──────────────┐
│ 4. 反思判断 │ ← reflect_on_documents()
│ │ LLM 评估检索结果是否足够
│ │
│ 足够吗？ │
│ / \ │
│ 是 否 │
│ │ │
│ ▼ ▼
│ 生成答案 回到步骤2，改进查询后重新检索
└──────┬───────┘
▼
┌──────────────┐
│ 5. 上下文组装 │ ← ContextBuilder.build()
│ │ · 注入长期记忆（偏好/实体）
│ │ · 注入短期记忆（对话历史）
│ │ · 拼接检索文档
│ │ · 权限过滤
└──────┬───────┘
▼
┌──────────────┐
│ 6. 生成答案 │ ← LLM 调用（带约束 Prompt）
│ │ 流式输出到前端 SSE
│ │ 自动评估（忠实度/相关性/召回率）
└──────┬───────┘
▼
┌──────────────┐
│ 7. 记忆存储 │
│ │ · 短期记忆：保存本轮对话
│ │ · 长期记忆：提取偏好/实体
└──────┬───────┘
▼
输出答案
```
### LangGraph 工作流节点图
```
┌─────────────┐
│ rewrite │ ← 查询改写
│ (改写+扩展) │
└──────┬──────┘
▼
┌─────────────┐
│ retrieve │ ← 混合检索（语义+BM25）
│ (检索文档) │
└──────┬──────┘
▼
┌─────────────┐
│ format │ ← RRF 融合 + Rerank 重排序
│ (格式化) │ + 上下文压缩
└──────┬──────┘
▼
┌─────────────┐
│ reflect │ ← LLM 反思检索质量
│ (反思) │
└──────┬──────┘
│
┌──────┴──────┐
│ should_continue│
│ (条件判断) │
└──┬───────┬───┘
│ │
"生成答案" "继续检索"
│ │
▼ └──→ 回到 retrieve
┌─────────────┐
│ generate │ ← 生成最终答案
│ (生成答案) │
└─────────────┘
```
---
## 项目结构
```
langchain-study/
│
├── app.py # FastAPI 应用入口（兼容旧引用）
├── main.py # 服务启动入口
│
├── app/ # 应用主模块
│ ├── __init__.py # FastAPI 应用工厂（路由注册、中间件、SPA 兜底）
│ │
│ ├── core/ # ═══ 核心基础设施 ═══
│ │ ├── __init__.py # 统一导出
│ │ ├── config.py # 全局配置（Pydantic Settings，支持 .env 覆盖）
│ │ ├── clients.py # LLM/Embedding/向量库客户端（带重试+熔断）
│ │ ├── prompt_manager.py # 提示词管理器（YAML 模板加载）
│ │ ├── retry.py # 指数退避重试 + 熔断器
│ │ ├── throttle.py # 令牌桶限流 + 优先级队列 + 上下文窗口管理
│ │ ├── streaming.py # 流式输出（DashScope SSE 实现）
│ │ └── metrics.py # Prometheus 指标收集
│ │
│ ├── retrieval/ # ═══ 检索模块 ═══
│ │ ├── __init__.py # 统一导出
│ │ ├── bm25_retriever.py # BM25 关键词检索器
│ │ ├── hybrid_retriever.py # 混合检索（RRF 融合排序：稠密+稀疏）
│ │ └── reranker.py # Cross-encoder 重排序 + 上下文压缩
│ │
│ ├── rag/ # ═══ RAG 工作流 ═══
│ │ ├── __init__.py # 统一导出
│ │ ├── workflow.py # LangGraph 工作流图定义
│ │ ├── query_rewriter.py # 查询改写器（LLM 同义改写 + HyDE 扩展）
│ │ ├── context_builder.py # 上下文组装器（记忆注入 + 文档拼接）
│ │ └── debug_tracer.py # 本地调试追踪器（节点执行可视化）
│ │
│ ├── ingestion/ # ═══ 文档导入管线 ═══
│ │ ├── __init__.py # 统一导出
│ │ ├── parser.py # 文档解析引擎（PDF/Word/PPT/Excel/纯文本）
│ │ ├── splitter.py # 文本分割器（RecursiveCharacterTextSplitter）
│ │ └── pipeline.py # 导入管线（解析→分割→向量化→存储）
│ │
│ ├── memory/ # ═══ 记忆系统 ═══
│ │ ├── __init__.py # 统一导出
│ │ ├── short_term.py # 短期记忆（对话窗口管理 + 摘要压缩）
│ │ └── long_term.py # 长期记忆（偏好提取 + 实体提取 + 向量存储）
│ │
│ ├── agent/ # ═══ 多 Agent 协作 ═══
│ │ ├── __init__.py # 统一导出
│ │ ├── tool_registry.py # 工具注册中心（冲突检测 + 分布式锁 + 优先级调度）
│ │ ├── task_decomposer.py # 任务分解器（LLM 分解 + 检查点 + 回滚 + 自我纠错）
│ │ └── orchestrator.py # Agent 编排器（注册/发现/路由/消息总线/权限继承）
│ │
│ ├── evaluation/ # ═══ RAG 评估 ═══
│ │ ├── __init__.py # 统一导出
│ │ └── evaluator.py # LLM-as-Judge 评估（忠实度/相关性/召回率）
│ │
│ ├── security/ # ═══ 权限控制 ═══
│ │ ├── __init__.py # 统一导出
│ │ └── permission.py # 三级权限（公开/部门/机密）过滤
│ │
│ ├── api/ # ═══ API 接口层 ═══
│ │ ├── __init__.py # 统一导出
│ │ ├── routes.py # SPA 入口路由（返回 index.html）
│ │ └── routes_v1.py # REST API v1（JSON + SSE 流式）
│ │
│ └── web/ # ═══ Web 前端 ═══
│ ├── __init__.py # 模块声明
│ ├── template_utils.py # 模板渲染工具
│ ├── templates/ # Prompt 配置文件
│ │ └── prompts/
│ │ └── prompts.yaml # 系统Prompt模板
│ └── static/ # Vue 3 SPA 静态文件
│ ├── index.html # Vue 3 单页应用入口
│ ├── css/app.css # 样式文件
│ └── js/ # JavaScript（内联在HTML中）
│
├── tests/ # 单元测试
│ └── test_core.py # 14 个测试类覆盖所有模块
│
├── monitoring/ # 监控配置
│ ├── prometheus.yml # Prometheus 配置
│ ├── alerts.yml # 告警规则
│ └── grafana-dashboard.json # Grafana 仪表盘
│
├── docker-compose.yml # Milvus + 应用集群部署
├── .env # 环境变量（API 密钥）
├── env_template.txt # 环境变量模板
├── requirements.txt # 生产依赖
├── requirements-dev.txt # 开发/测试依赖
├── pyproject.toml # 项目配置（pytest 设置）
├── DEV_PLAN.md # 开发计划
└── .gitignore # Git 忽略规则
```
---
## 脚本说明
### scripts/ — 工具脚本
| 文件 | 作用 | 使用方法 |
|------|------|-----------|
| **manage_models.py** | **模型管理工具（推荐）**。统一管理BGE嵌入模型和Reranker模型的下载、检查和测试。通过ModelScope下载模型，完全免费且国内访问稳定。 | `python scripts/manage_models.py --download-all`
`python scripts/manage_models.py --check`
`python scripts/manage_models.py --test` |
| **check_reranker.py** | **检查Reranker模型状态**。验证BGE reranker模型是否已安装，检查缓存目录，测试模型加载。 | `python scripts/check_reranker.py` |
| **test_reranker.py** | **测试Reranker模型加载**。验证下载的BGE reranker模型是否可以正常加载和使用，测试相关性评分功能。 | `python scripts/test_reranker.py` |
**模型下载说明：**
1. **推荐使用统一管理工具**：
```bash
# 下载所有模型（嵌入+Reranker）
python scripts/manage_models.py --download-all
# 仅下载嵌入模型（约1.3GB）
python scripts/manage_models.py --download-embedding
# 仅下载Reranker模型（约1.1GB）
python scripts/manage_models.py --download-reranker
```
2. **检查模型状态**：
```bash
python scripts/manage_models.py --check
```
3. **测试模型加载**：
```bash
python scripts/manage_models.py --test
```
4. **模型文件位置**：
- 嵌入模型：`models/bge-large-zh-v1.5/`
- Reranker模型：`models/bge-reranker-base/`
- 总大小：约2.4GB
5. **优势**：
- ✅ 完全免费，无API调用成本
- ✅ 本地运行，速度快
- ✅ 中文效果好，专为中文优化
- ✅ 通过ModelScope下载，国内访问稳定
---
### core/ — 核心基础设施
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **config.py** | **全局配置中心**。使用 Pydantic 管理所有配置项，支持 `.env` 文件和环境变量覆盖。包含 LLM、嵌入模型、向量数据库、文档分块、检索、评估、记忆、服务器等全部配置。 | `Settings` 类 |
| **clients.py** | **外部客户端封装**。LLM 客户端（通义千问）、Embedding 客户端（DashScope/BGE 可切换）、向量数据库客户端（Chroma/Milvus 可切换）。所有客户端使用单例模式延迟初始化，带重试和熔断保护。 | `LLMClient`, `EmbeddingClient`, `VectorStoreClient` |
| **prompt_manager.py** | **提示词管理器**。从 `prompts.yaml` 加载所有 Prompt 模板，提供 `get_rag_prompt()`, `get_reflect_prompt()`, `get_query_rewrite_prompt()` 等方法。 | `PromptManager` |
| **retry.py** | **重试与熔断机制**。提供 `@retry`（指数退避重试装饰器，支持同步/异步函数）和 `CircuitBreaker`（熔断器，状态流转：CLOSED→OPEN→HALF_OPEN→CLOSED）。全局实例：`llm_circuit_breaker`, `embedding_circuit_breaker`。 | `retry()`, `async_retry()`, `CircuitBreaker` |
| **throttle.py** | **并发与限流**。`TokenBucket` 令牌桶限流器（支持 100+ 并发），`RequestQueue` 优先级请求队列，`RequestHandler` 整合限流+队列（多工作协程），`ContextWindowManager` 上下文窗口管理（四层压缩策略：丢弃低分→截断长文→滑动窗口）。 | `TokenBucket`, `RequestQueue`, `RequestHandler`, `ContextWindowManager` |
| **streaming.py** | **流式输出**。封装 DashScope 原生流式 API，支持 `stream_generate()`（单轮生成）、`stream_chat()`（多轮对话）、`stream_rag_answer()`（RAG 流式回答）。通过 SSE 推送到前端。 | `StreamLLM` |
| **metrics.py** | **Prometheus 指标收集**。定义 LLM 调用、检索延迟、知识库大小、熔断器状态、请求队列、HTTP 请求耗时等指标。提供 `/metrics` 端点和请求耗时中间件。 | `metrics_endpoint()`, `metrics_middleware()` |
### retrieval/ — 检索模块
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **bm25_retriever.py** | **BM25 关键词检索器**。使用 `rank_bm25` 库实现传统关键词检索，作为语义检索的补充。支持动态更新索引。 | `BM25Retriever` |
| **hybrid_retriever.py** | **混合检索器**。核心函数 `reciprocal_rank_fusion()` 实现 RRF 融合排序算法：`score(d) = Σ(1/(k + rank_i(d)))`。`HybridRetriever` 类整合稠密向量检索 + BM25 稀疏检索，支持 RRF 融合和加权融合两种模式。 | `reciprocal_rank_fusion()`, `HybridRetriever` |
| **reranker.py** | **重排序与上下文压缩**。`ReRanker` 使用 Cross-encoder 模型（BGE-reranker / MiniLM）对检索结果逐对计算相关性分数，重新排序。`ContextCompressor` 负责过滤低分文档、截断长内容，减少 LLM 输入噪声。 | `ReRanker`, `ContextCompressor` |
### rag/ — RAG 工作流
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **workflow.py** | **LangGraph 工作流核心**。定义完整 RAG 工作流图：`rewrite_query`(查询改写) → `retrieve_documents`(混合检索) → `format_documents`(RRF+Rerank+压缩) → `reflect_on_documents`(LLM 反思) → `should_continue`(条件判断) → `generate_answer`(生成答案)。支持多轮检索反思机制。 | `RagState`, `get_rag_graph()`, `build_rag_graph()` |
| **query_rewriter.py** | **查询改写器**。使用 LLM 将用户问题改写成多个同义表达，提高检索召回率。支持 `rewrite()`（同义改写）和 `expand_with_hyde()`（HyDE 假设性文档扩展）。 | `QueryRewriter` |
| **context_builder.py** | **上下文组装器**。将检索结果、短期记忆、长期记忆按优先级组装为 LLM 可用的上下文。支持截断和 score 标记。 | `ContextBuilder` |
| **debug_tracer.py** | **调试追踪器**。LangChain 回调处理器，记录工作流各节点的执行时间、输入输出。支持控制台输出和文件日志。`print_summary()` 打印执行摘要（各节点耗时）。 | `LocalDebugTracer` |
### ingestion/ — 文档导入管线
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **parser.py** | **文档解析引擎**。统一接口解析多种格式：PDF（PyMuPDF）、Word（python-docx）、PPT（python-pptx）、Excel（openpyxl）、纯文本。支持单个文件和批量目录解析。 | `DocumentParser` |
| **splitter.py** | **文本分割器**。使用 `RecursiveCharacterTextSplitter` 将长文档切分为小段，支持配置 `chunk_size` 和 `chunk_overlap`。 | `get_text_splitter()`, `split_documents()`, `split_text()` |
| **pipeline.py** | **导入管线**。将解析→分割→向量化→存储串成完整流程。支持 `ingest_file()`（单文件）、`ingest_directory()`（目录批量）、`ingest_text()`（纯文本）三种导入方式。 | `IngestionPipeline` |
### memory/ — 记忆系统
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **short_term.py** | **短期记忆**。对话窗口管理，维护最近 N 轮对话（默认 5 轮）。超出窗口时自动调用 LLM 压缩为摘要。`get_context()` 返回格式化后的对话历史上下文。 | `ConversationMemory`, `ConversationTurn` |
| **long_term.py** | **长期记忆**。每次对话后自动提取用户偏好和关键实体，使用独立的向量库持久化存储。支持去重、相似度检索、记忆上下文注入。`extract_and_store()` 自动提取，`get_memory_context()` 检索相关记忆。 | `LongTermMemory` |
### agent/ — 多 Agent 协作
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **tool_registry.py** | **工具注册中心**。管理所有可用工具的注册、发现、调用和冲突解决。每个工具有独立的 `asyncio.Lock`，支持并发控制、优先级调度、调用超时、状态监控。 | `ToolRegistry`, `Tool`, `ToolRequest` |
| **task_decomposer.py** | **任务分解器**。LLM 驱动的复杂任务自动分解为子任务 DAG（有向无环图）。支持拓扑排序执行、检查点快照与回滚、LLM 自我纠错与重试。`execute_with_rollback()` 是核心入口。 | `TaskDecomposer`, `Task`, `Checkpoint` |
| **orchestrator.py** | **Agent 编排器**。Agent 注册与发现、任务路由（根据角色/能力匹配 Agent）、消息总线（发布/订阅模式）、权限继承（子 Agent 继承父 Agent 权限）。`run_agent_loop()` 启动 Agent 主循环。 | `AgentOrchestrator`, `Agent`, `MessageBus` |
### evaluation/ — RAG 评估
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **evaluator.py** | **LLM-as-Judge 评估器**。自动评估三项指标：忠实度（回答是否基于上下文）、答案相关性（回答是否切题）、上下文召回率（上下文是否覆盖所需信息）。每项 0-10 分，输出 JSON 格式评分和理由。 | `RagEvaluator` |
### security/ — 权限控制
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **permission.py** | **三级权限管理器**。`public`（所有人可查）、`department`（部门成员可查）、`confidential`（特定角色可查）。`filter_documents()` 根据用户上下文过滤文档，`check_permission()` 检查单个文档权限。 | `PermissionManager`, `UserContext`, `PermissionLevel` |
### api/ — API 接口层
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **routes.py** | **旧版路由**。使用 Jinja2 模板渲染的 Web 页面路由。包含首页、添加文档、查询、验证知识库、文档详情、删除文档、清空对话、查看长期记忆等功能。 | 10 个路由函数 |
| **routes_v1.py** | **REST API v1**。JSON 格式的 API 接口，支持 SSE 流式输出。包含查询（非流式/流式）、文档管理（添加/上传/列表/删除）、记忆管理（对话历史/长期记忆 CRUD）、系统状态等 11 个端点。 | 11 个路由函数 |
### web/ — Web 前端
| 文件 | 作用 | 关键类/函数 |
|------|------|-------------|
| **template_utils.py** | **Jinja2 模板渲染工具**。封装 Jinja2 环境，提供 `render_template()` 和 `TemplateResponse()` 函数，用于旧版模板渲染。 | `render_template()`, `TemplateResponse()` |
| **static/index.html** | **Vue 3 SPA 入口**。单页应用，包含三面板布局：侧栏（对话历史+系统状态）、主内容区（问答面板/文档管理面板/记忆面板）。支持流式聊天、Markdown 渲染、文件上传、对话管理、记忆查看。 | Vue 3 Composition API |
---
## 快速开始
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
### 2. 配置 API 密钥
```bash
copy env_template.txt .env
```
编辑 `.env` 文件，填入 API 密钥：
```
# 智谱 GLM API 密钥（从 https://open.bigmodel.cn/ 获取）
ZHIPU_API_KEY=your-zhipu-api-key-here
ZHIPU_MODEL=glm-4.7-flash # 免费模型
# 嵌入模型: bge (本地免费) | zhipu (收费) | dashscope (收费)
EMBEDDING_MODEL=bge
```
**API 密钥获取：**
- 智谱 GLM：https://open.bigmodel.cn/
- 阿里云通义千问：https://dashscope.console.aliyun.com/
### 3. 下载模型（可选，推荐）
**方案A：使用本地免费模型（推荐）**
通过ModelScope下载BGE模型，完全免费：
```bash
# 安装ModelScope
pip install modelscope sentencepiece
# 下载所有模型（嵌入+Reranker，约2.4GB）
python scripts/manage_models.py --download-all
```
下载完成后，修改 `.env` 配置：
```
# 切换到本地免费模型
EMBEDDING_MODEL=bge
RERANK_ENABLED=true
```
**方案B：使用云端模型**
- **智谱嵌入模型**：成本低（约0.0007元/千token），无需下载
- **阿里云DashScope**：需要付费，在线服务
**模型对比：**
| 方案 | 嵌入模型 | Reranker | 月成本 | 适用场景 |
|------|---------|----------|--------|---------|
| **本地免费（推荐）** | BGE本地 | BGE本地 | ¥0 | 频繁使用、成本敏感 |
| 智谱云端 | 智谱嵌入 | BGE本地 | ¥10-50 | 中等使用、快速部署 |
| 完全云端 | 智谱嵌入 | 无 | ¥10-50 | 临时测试、轻量使用 |
### 4. 启动服务
**重要：必须使用虚拟环境的Python启动服务！**
#### 方式1：使用启动脚本（推荐）
**Windows**：
```bash
# 方式A：简洁启动脚本
run.bat
# 方式B：详细启动脚本
start_server.bat
```
**Linux/Mac**：
```bash
bash start_server.sh
```
#### 方式2：直接使用命令
**Windows**：
```bash
.venv\Scripts\python main.py
```
**Linux/Mac**：
```bash
source .venv/bin/activate
python main.py
```
#### 方式3：使用uvicorn（热重载模式）
**Windows**：
```bash
.venv\Scripts\uvicorn app:create_app --host 0.0.0.0 --port 8000 --reload
```
**Linux/Mac**：
```bash
source .venv/bin/activate
uvicorn app:create_app --host 0.0.0.0 --port 8000 --reload
```
#### 访问地址
启动成功后访问：
- **前端界面**: http://localhost:8000
- **API文档**: http://localhost:8000/docs
- **监控指标**: http://localhost:8000/metrics
访问 http://localhost:8000 使用 Vue 3 SPA 界面。
### 5. 运行测试
```bash
pip install -r requirements-dev.txt
pytest
```
---
## 配置说明
所有配置项在 `.env` 文件中管理，详见 [env_template.txt](env_template.txt)。
### 核心配置分组
| 分组 | 关键配置 | 默认值 | 说明 |
|------|---------|--------|------|
| **LLM** | `DASHSCOPE_API_KEY` | - | 阿里云通义千问 API 密钥 |
| **嵌入模型** | `EMBEDDING_MODEL` | `dashscope` | 可选: `dashscope` / `bge` |
| | `BGE_EMBEDDING_MODEL` | `BAAI/bge-large-zh-v1.5` | BGE 嵌入模型名称 |
| | `BGE_RERANKER_MODEL` | `BAAI/bge-reranker-base` | BGE 重排序模型名称 |
| **向量数据库** | `VECTOR_STORE` | `chroma` | 可选: `chroma` / `milvus` |
| | `MILVUS_HOST` | `localhost` | Milvus 地址 |
| | `MILVUS_PORT` | `19530` | Milvus 端口 |
| **文档分块** | `CHUNK_SIZE` | `500` | 每块字符数 |
| | `CHUNK_OVERLAP` | `50` | 块间重叠字符数 |
| **检索** | `HYBRID_TOP_K` | `6` | 混合检索返回数 |
| | `RRF_K` | `60` | RRF 融合常数 |
| | `RERANK_TOP_K` | `5` | 重排序后保留数 |
| **记忆** | `MEMORY_MAX_TURNS` | `5` | 短期记忆对话轮数 |
| | `LONG_TERM_MEMORY_ENABLED` | `true` | 长期记忆开关 |
| **评估** | `EVAL_ENABLED` | `true` | RAG 评估开关 |
| **服务器** | `HOST` | `0.0.0.0` | 监听地址 |
| | `PORT` | `8000` | 监听端口 |
---
## API 参考
### REST API v1 端点
#### 查询接口
**POST /api/v1/query**
- 功能：非流式 RAG 查询
- 请求体：`{"question": "问题", "top_k": 5}`
- 返回：`{"answer": "...", "documents": [...], "evaluation": {...}}`
**POST /api/v1/query/stream**
- 功能：SSE 流式 RAG 查询
- 请求体：`{"question": "问题", "top_k": 5}`
- 返回：SSE 流，event 类型：
- `data: {"type": "document", "content": "..."}` - 检索到的文档
- `data: {"type": "token", "content": "..."}` - 流式文本片段
- `data: {"type": "done", "answer": "..."}` - 完成信号
- `data: {"type": "error", "content": "..."}` - 错误信息
#### 文档管理
**POST /api/v1/documents** - 添加文本
**POST /api/v1/documents/upload** - 上传文件（PDF/Word/PPT/Excel/纯文本）
**GET /api/v1/documents** - 获取文档列表
**DELETE /api/v1/documents/{id}** - 删除文档
#### 记忆管理
**GET /api/v1/memory/conversation** - 获取对话历史
**POST /api/v1/memory/conversation/clear** - 清空对话历史
**GET /api/v1/memory/long-term** - 获取长期记忆
**POST /api/v1/memory/long-term/clear** - 清空长期记忆
#### 系统状态
**GET /api/v1/status** - 获取系统配置和状态
---
## 监控与运维
### Prometheus 指标
启用 Prometheus 指标收集后，访问 `http://localhost:8000/metrics` 查看指标。
| 指标名 | 类型 | 说明 |
|--------|------|------|
| `llm_requests_total` | Counter | LLM 请求总数 |
| `llm_requests_failed_total` | Counter | LLM 请求失败数 |
| `llm_duration_seconds` | Histogram | LLM 请求耗时 |
| `retrieval_requests_total` | Counter | 检索请求总数 |
| `retrieval_duration_seconds` | Histogram | 检索耗时 |
| `knowledge_base_documents_total` | Gauge | 知识库文档总数 |
| `circuit_breaker_state` | Gauge | 熔断器状态 |
| `request_queue_size` | Gauge | 请求队列大小 |
| `http_request_duration_seconds` | Histogram | HTTP 请求耗时 |
### 告警规则
定义在 `monitoring/alerts.yml` 中：
| 告警名 | 触发条件 | 严重级别 |
|--------|---------|---------|
| `HighLLMFailureRate` | LLM 失败率 > 10% | warning |
| `HighRetrievalLatency` | 检索延迟 p95 > 2s | warning |
| `NoDocuments` | 知识库为空 | info |
| `CircuitBreakerOpen` | 熔断器开启 | critical |
| `RequestQueueBacklog` | 队列积压 > 100 | warning |
### 启动监控栈
```bash
docker-compose -f docker-compose.yml -f docker-compose.monitor.yml up -d
```
---
## 流程分支与触发条件
本系统提供详细的流程分支测试文档，涵盖各个流程分支的触发条件、验证方法和常见问题排查。
**👉 查看完整测试文档：[workflow.md](workflow.md)**
### 核心流程分支概览
系统根据用户输入自动路由到以下分支：
| 分支名称 | 触发条件 | 验证方法 | 日志关键词 |
|---------|---------|---------|-----------|
| **文档查询** | 自然语言问题 | 聊天框输入问题 | `query_branch`, `混合检索` |
| **文档上传** | 上传文件 | 点击上传按钮 | `document_management_branch`, `文档解析` |
| **文档删除** | 删除操作 | 点击删除按钮 | `document_management_branch`, `文档删除` |
| **短期记忆** | 对话轮次 > 1 | 多轮对话 | `short_term_memory`, `对话轮次` |
| **长期记忆** | 对话结束 | 查询偏好 | `long_term_memory`, `提取记忆` |
| **查询改写** | `QUERY_REWRITE_ENABLED=true` | 输入模糊问题 | `query_rewriter`, `改写查询` |
| **混合检索** | `HYBRID_RETRIEVAL_ENABLED=true` | 任意查询 | `hybrid_retriever`, `向量+BM25` |
| **重排序** | `RERANK_ENABLED=true` | 任意查询 | `reranker`, `重排序完成` |
### 快速验证自动路由
**最简单的验证方法：**
```bash
# 1. 启动服务（开启DEBUG日志）
DEBUG=true .venv\Scripts\python main.py
# 2. 在浏览器访问 http://localhost:8000
# 3. 在聊天框输入不同内容，观察终端日志：
输入：年假政策是什么？
日志：路由决策: query_branch
输入：上传文档
日志：路由决策: document_management_branch
输入：你记得我是谁吗？
日志：路由决策: memory_aware_query_branch
```
### 功能开关与配置
```bash
# .env 配置文件
# 核心功能开关
QUERY_REWRITE_ENABLED=true # 查询改写
HYBRID_RETRIEVAL_ENABLED=true # 混合检索
RERANK_ENABLED=true # 重排序
MEMORY_ENABLED=true # 短期记忆
LONG_TERM_MEMORY_ENABLED=true # 长期记忆
EVAL_ENABLED=true # 效果评估
```
**详细测试流程、验证方法、常见问题排查，请查看：[workflow.md](workflow.md)**
---
### 🔄 RAG 工作流总览
```
用户输入
↓
┌─────────────────────────────────────┐
│ 工作流编排器 │
│ 根据输入类型自动路由到不同分支 │
└──────────────┬──────────────────────┘
│
┌────────┴────────┬─────────────┬──────────────┐
↓ ↓ ↓ ↓
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 文档查询 │ │ 文档管理 │ │ 记忆管理 │ │ 系统管理 │
│ 分支 │ │ 分支 │ │ 分支 │ │ 分支 │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
↓ ↓ ↓ ↓
混合检索 文档增删 记忆查询 系统配置
+ 重排序 + 更新 + 存储 + 监控
↓ ↓ ↓ ↓
LLM生成 返回结果 返回历史 返回状态
↓ ↓ ↓ ↓
└──────────────────────┴─────────────┴──────────────┘
↓
返回给用户
```
---
### 📋 主要流程分支
系统根据用户输入自动路由到以下分支：
#### 1. **文档查询分支**
**触发条件：**
- 用户输入为自然语言问题
- 不包含特殊命令前缀
- 不匹配文档管理指令
**验证方法：**
```bash
# 访问前端：http://localhost:8000
# 在聊天框输入：
# 测试1：简单查询
输入：年假政策是什么？
预期：触发文档查询分支，返回年假政策相关内容
# 测试2：复杂查询
输入：如何申请年假？需要提前多少天？
预期：触发查询改写 + 混合检索 + 重排序
# 测试3：多轮对话
输入1：公司的年假政策
输入2：那病假呢？
预期：触发短期记忆，理解"那病假"指代"病假政策"
```
**日志验证：**
```log
# 查看日志输出（终端或日志文件）
2026-07-29 11:20:50 - app.rag.workflow - INFO - 开始文档查询流程
2026-07-29 11:20:51 - app.retrieval.hybrid_retriever - INFO - 执行混合检索
2026-07-29 11:20:52 - app.retrieval.reranker - INFO - 执行重排序
2026-07-29 11:20:53 - app.rag.workflow - INFO - LLM生成回答
```
---
#### 2. **文档管理分支**
**触发条件：**
- 用户上传文档（通过前端界面上传按钮）
- 用户删除文档（通过文档管理界面）
- API调用文档管理接口
**验证方法：**
**方法1：通过前端界面上传**
```bash
# 访问：http://localhost:8000
# 点击"文档管理" → "上传文档"
# 选择文件：policy.pdf
预期：
1. 前端显示上传进度
2. 后台解析文档并分块
3. 向量化并存储到Chroma
4. 返回成功消息："文档上传成功，共导入 X 个文档块"
```
**方法2：通过API上传**
```bash
# 使用curl测试
curl -X POST http://localhost:8000/api/v1/documents/upload \
-F "file=@test.pdf" \
-F "permission=public"
预期返回：
{
"success": true,
"message": "文档上传成功",
"document_id": "doc_123",
"chunks": 15
}
```
**方法3：通过前端删除文档**
```bash
# 访问文档管理界面
# 点击文档右侧的"删除"按钮
预期：
1. 文档从向量库中删除
2. 更新文档列表
3. 返回成功消息
```
**日志验证：**
```log
2026-07-29 11:22:10 - app.ingestion.pipeline - INFO - 开始解析文档: policy.pdf
2026-07-29 11:22:12 - app.ingestion.text_splitter - INFO - 文档分块完成: 15 chunks
2026-07-29 11:22:15 - app.core.clients - INFO - 文档向量化完成
2026-07-29 11:22:16 - app.api.routes_v1 - INFO - 文档上传成功: doc_123
```
---
#### 3. **记忆管理分支**
**触发条件：**
- 系统启用长期记忆（`LONG_TERM_MEMORY_ENABLED=true`）
- 对话轮次超过阈值
- 用户主动查询记忆
**验证方法：**
**方法1：短期记忆验证**
```bash
# 在聊天界面连续对话
用户：公司的年假政策是什么？
系统：年假政策规定...
用户：那病假呢？ # 测试上下文理解
系统：病假政策规定...（正确理解"病假"）
用户：我是张三，研发部的
系统：好的，已记录...
用户：我有什么信息？
系统：您是张三，研发部员工（验证短期记忆）
# 查看日志
2026-07-29 11:25:10 - app.memory.short_term - INFO - 添加对话轮次: turn_5
```
**方法2：长期记忆验证**
```bash
# 步骤1：首次对话，建立记忆
用户：我经常需要查询年假政策
系统：已记住您的偏好...
# 步骤2：查看长期记忆存储
# 检查文件：memory_store/chroma.sqlite3
# 应包含提取的偏好记录
# 步骤3：重新开始对话（刷新页面）
用户：你记得我喜欢查询什么吗？
系统：您经常查询年假政策（验证长期记忆）
# 查看日志
2026-07-29 11:26:20 - app.memory.long_term - INFO - 提取并存储记忆: 用户关注年假政策
```
**方法3：API直接查询记忆**
```bash
# 查询长期记忆
curl http://localhost:8000/api/v1/memory/long-term?query=年假
预期返回：
{
"memories": [
{
"type": "preference",
"content": "用户关注年假政策",
"confidence": 0.9,
"created_at": "2026-07-29T11:26:20"
}
]
}
```
---
#### 4. **查询改写分支**
**触发条件：**
- 配置启用查询改写（`QUERY_REWRITE_ENABLED=true`）
- 用户输入自然语言问题
- 查询长度大于阈值
**验证方法：**
```bash
# 在聊天界面输入模糊问题
用户：年假怎么请？
# 查看日志，确认查询改写
2026-07-29 11:28:10 - app.rag.query_rewriter - INFO - 原始查询: 年假怎么请？
2026-07-29 11:28:11 - app.rag.query_rewriter - INFO - 改写查询:
1. 年假申请流程
2. 如何休年假
3. 带薪年假请假步骤
# 预期：系统使用改写后的多个查询进行检索，提高召回率
```
**配置调整：**
```bash
# 修改.env文件
QUERY_REWRITE_ENABLED=true # 启用查询改写
QUERY_REWRITE_COUNT=3 # 改写问题数量
# 重启服务验证
.venv\Scripts\python main.py
```
---
#### 5. **混合检索分支**
**触发条件：**
- 配置启用混合检索（`HYBRID_RETRIEVAL_ENABLED=true`）
- 知识库不为空
- 用户发起查询请求
**验证方法：**
```bash
# 在聊天界面输入查询
用户：公司的薪酬体系是怎样的？
# 查看日志，确认混合检索
2026-07-29 11:30:10 - app.retrieval.hybrid_retriever - INFO - 向量检索返回: 10 条
2026-07-29 11:30:11 - app.retrieval.hybrid_retriever - INFO - BM25检索返回: 10 条
2026-07-29 11:30:12 - app.retrieval.hybrid_retriever - INFO - RRF融合完成，共 15 条去重结果
```
**关闭混合检索对比：**
```bash
# 修改.env文件，关闭混合检索
HYBRID_RETRIEVAL_ENABLED=false
# 重启服务
# 再次查询，日志应显示：
2026-07-29 11:31:10 - app.retrieval.hybrid_retriever - INFO - 仅使用向量检索: 10 条
# 对比效果：混合检索召回率更高
```
---
#### 6. **重排序分支**
**触发条件：**
- 配置启用重排序（`RERANK_ENABLED=true`）
- 混合检索返回结果数量 > RERANK_TOP_K
- 本地Reranker模型已下载
**验证方法：**
```bash
# 在聊天界面输入查询
用户：工作时间是怎么规定的？
# 查看日志，确认重排序执行
2026-07-29 11:32:10 - app.retrieval.reranker - INFO - 加载Reranker模型: bge-reranker-base
2026-07-29 11:32:12 - app.retrieval.reranker - INFO - 重排序完成: 15 → 5 条
2026-07-29 11:32:12 - app.retrieval.reranker - INFO - 平均相关度: 0.85
# 预期：重排序后的文档相关度更高
```
**关闭重排序对比：**
```bash
# 修改.env文件，关闭重排序
RERANK_ENABLED=false
# 重启服务
# 再次查询，日志应显示：
2026-07-29 11:33:10 - app.retrieval.hybrid_retriever - INFO - 跳过重排序，直接返回: 10 条
# 对比效果：重排序后相关性提升约10%
```
---
### 🤖 自动路由验证
系统的自动路由功能根据输入内容智能选择处理分支。
#### **路由决策流程**
```python
# 伪代码：路由决策逻辑
def route_request(user_input):
if is_document_upload(user_input):
return "document_management_branch"
elif is_memory_query(user_input):
return "memory_branch"
elif is_system_command(user_input):
return "system_branch"
else:
return "query_branch" # 默认：文档查询
```
---
#### **验证方法1：通过日志观察路由**
```bash
# 启动服务（开启DEBUG日志）
DEBUG=true .venv\Scripts\python main.py
# 测试场景1：文档查询
用户输入：年假政策是什么？
日志输出：
2026-07-29 11:35:10 - app.rag.workflow - DEBUG - 路由决策: query_branch
2026-07-29 11:35:10 - app.rag.workflow - INFO - 执行文档查询流程
# 测试场景2：文档上传（通过API）
curl -X POST http://localhost:8000/api/v1/documents/upload -F "file=@test.pdf"
日志输出：
2026-07-29 11:36:10 - app.api.routes_v1 - DEBUG - 路由决策: document_management_branch
2026-07-29 11:36:10 - app.ingestion.pipeline - INFO - 开始解析文档
# 测试场景3：记忆查询
curl http://localhost:8000/api/v1/memory/long-term?query=年假
日志输出：
2026-07-29 11:37:10 - app.memory.long_term - DEBUG - 路由决策: memory_branch
2026-07-29 11:37:10 - app.memory.long_term - INFO - 检索长期记忆
```
---
#### **验证方法2：通过API测试路由**
```bash
# 测试脚本：test_routing.py
import requests
import json
# 测试1：文档查询路由
response = requests.post(
"http://localhost:8000/api/v1/query/stream",
json={"question": "年假政策"}
)
print("文档查询路由:", response.headers.get("X-Route-Branch"))
# 测试2：文档上传路由
with open("test.pdf", "rb") as f:
response = requests.post(
"http://localhost:8000/api/v1/documents/upload",
files={"file": f}
)
print("文档上传路由:", response.headers.get("X-Route-Branch"))
# 测试3：记忆查询路由
response = requests.get(
"http://localhost:8000/api/v1/memory/long-term",
params={"query": "年假"}
)
print("记忆查询路由:", response.headers.get("X-Route-Branch"))
```
---
#### **验证方法3：通过前端界面观察**
```bash
# 步骤1：打开浏览器开发者工具（F12）
# 访问：http://localhost:8000
# 步骤2：切换到Network标签，勾选"Preserve log"
# 步骤3：在聊天框输入不同类型的内容
# 场景1：普通查询
输入：年假有几天？
观察Network：
- POST /api/v1/query/stream
- Response Headers: X-Route-Branch: query_branch
# 场景2：上传文档
点击"文档管理" → "上传文档"
观察Network：
- POST /api/v1/documents/upload
- Response Headers: X-Route-Branch: document_management_branch
# 场景3：查询记忆（需要先建立记忆）
输入：你记得我是谁吗？
观察Network：
- POST /api/v1/query/stream
- Response Headers: X-Route-Branch: memory_aware_query_branch
```
---
### ⚙️ 功能开关与配置
系统通过环境变量控制各个功能分支：
```bash
# .env 配置文件
# 核心功能开关
QUERY_REWRITE_ENABLED=true # 查询改写
HYBRID_RETRIEVAL_ENABLED=true # 混合检索
RERANK_ENABLED=true # 重排序
MEMORY_ENABLED=true # 短期记忆
LONG_TERM_MEMORY_ENABLED=true # 长期记忆
EVAL_ENABLED=true # 效果评估
# 参数配置
QUERY_REWRITE_COUNT=3 # 改写问题数量
HYBRID_TOP_K=10 # 混合检索数量
RERANK_TOP_K=5 # 重排序保留数量
MEMORY_MAX_TURNS=5 # 短期记忆轮次
```
---
### 🧪 完整测试流程
#### **测试脚本：test_all_branches.py**
```python
"""
系统流程分支完整测试脚本
运行方法：.venv\Scripts\python test_all_branches.py
"""
import requests
import json
BASE_URL = "http://localhost:8000"
def test_query_branch():
"""测试文档查询分支"""
print("\n=== 测试文档查询分支 ===")
response = requests.post(
f"{BASE_URL}/api/v1/query/stream",
json={"question": "年假政策是什么？"},
stream=True
)
print(f"状态码: {response.status_code}")
print(f"路由分支: {response.headers.get('X-Route-Branch')}")
# 读取流式响应
for line in response.iter_lines():
if line:
print(f"数据: {line.decode('utf-8')}")
def test_document_upload_branch():
"""测试文档上传分支"""
print("\n=== 测试文档上传分支 ===")
# 创建测试文件
with open("test_doc.txt", "w", encoding="utf-8") as f:
f.write("这是一个测试文档。\n包含年假政策信息。")
# 上传文件
with open("test_doc.txt", "rb") as f:
response = requests.post(
f"{BASE_URL}/api/v1/documents/upload",
files={"file": f},
data={"permission": "public"}
)
print(f"状态码: {response.status_code}")
print(f"响应: {response.json()}")
print(f"路由分支: {response.headers.get('X-Route-Branch')}")
def test_memory_branch():
"""测试记忆管理分支"""
print("\n=== 测试记忆管理分支 ===")
# 查询长期记忆
response = requests.get(
f"{BASE_URL}/api/v1/memory/long-term",
params={"query": "年假"}
)
print(f"状态码: {response.status_code}")
print(f"记忆数量: {len(response.json().get('memories', []))}")
print(f"路由分支: {response.headers.get('X-Route-Branch')}")
def test_rerank_branch():
"""测试重排序分支"""
print("\n=== 测试重排序分支 ===")
# 触发查询（确保有足够多的检索结果）
response = requests.post(
f"{BASE_URL}/api/v1/query/stream",
json={"question": "工作时间 薪酬 年假"},
stream=True
)
print(f"状态码: {response.status_code}")
# 查看日志确认重排序执行
def run_all_tests():
"""运行所有测试"""
print("开始测试系统流程分支...")
try:
test_query_branch()
test_document_upload_branch()
test_memory_branch()
test_rerank_branch()
print("\n✅ 所有测试完成！")
except Exception as e:
print(f"\n❌ 测试失败: {e}")
if __name__ == "__main__":
run_all_tests()
```
**运行测试：**
```bash
# 启动服务
.venv\Scripts\python main.py
# 运行测试脚本
.venv\Scripts\python test_all_branches.py
```
---
### 📊 流程分支总结表
| 分支名称 | 触发条件 | 验证方法 | 日志关键词 |
|---------|---------|---------|-----------|
| **文档查询** | 自然语言问题 | 聊天框输入问题 | `query_branch`, `混合检索` |
| **文档上传** | 上传文件 | 点击上传按钮 | `document_management_branch`, `文档解析` |
| **文档删除** | 删除操作 | 点击删除按钮 | `document_management_branch`, `文档删除` |
| **短期记忆** | 对话轮次 > 1 | 多轮对话 | `short_term_memory`, `对话轮次` |
| **长期记忆** | 对话结束 | 查询偏好 | `long_term_memory`, `提取记忆` |
| **查询改写** | `QUERY_REWRITE_ENABLED=true` | 输入模糊问题 | `query_rewriter`, `改写查询` |
| **混合检索** | `HYBRID_RETRIEVAL_ENABLED=true` | 任意查询 | `hybrid_retriever`, `向量+BM25` |
| **重排序** | `RERANK_ENABLED=true` | 任意查询 | `reranker`, `重排序完成` |
---
### 💡 常见问题排查
#### **问题1：混合检索未执行**
```bash
# 检查配置
cat .env | grep HYBRID_RETRIEVAL_ENABLED
# 应输出：HYBRID_RETRIEVAL_ENABLED=true
# 检查知识库是否为空
curl http://localhost:8000/api/v1/documents/count
# 应返回：{"count": > 0}
# 检查日志
grep "混合检索" logs/app.log
```
#### **问题2：重排序未执行**
```bash
# 检查配置
cat .env | grep RERANK_ENABLED
# 应输出：RERANK_ENABLED=true
# 检查模型是否存在
ls models/bge-reranker-base/
# 应存在模型文件
# 检查日志
grep "重排序" logs/app.log
```
#### **问题3：长期记忆未提取**
```bash
# 检查配置
cat .env | grep LONG_TERM_MEMORY_ENABLED
# 应输出：LONG_TERM_MEMORY_ENABLED=true
# 检查记忆存储目录
ls memory_store/
# 应存在Chroma数据库文件
# 查看日志
grep "提取记忆" logs/app.log
```
---
## 常见问题与解答
本系统提供详细的Q&A文档，涵盖文档处理、检索优化、重排序、查询处理、上下文管理、评估监控、Agent协作、部署优化等所有核心功能。
**👉 查看完整Q&A文档：[Q&A.md](Q&A.md)**
### Q&A文档目录
- 📄 **文档处理与分块策略** (Q1-Q5)
- Chunk策略选择、大小调优、重叠参数设置、文档类型处理、效果评估
- 🔍 **检索与召回优化** (Q6-Q13)
- 召回率评估与优化、混合检索实现、BM25调优、向量检索参数、RRF融合算法、检索延迟优化
- 🎯 **重排序与精排优化** (Q14-Q18)
- 重排序实现原理、Cross-encoder选择、Top-K参数设置、性能影响、效果评估
- 🔎 **查询处理与扩展** (Q19-Q22)
- 查询改写实现、HyDE扩展、多查询扩展、过度扩展避免
- 🧩 **上下文处理与组装** (Q23-Q26)
- 上下文组装策略、窗口限制处理、压缩方法、记忆注入
- 📊 **评估与监控** (Q27-Q30)
- RAG效果评估、忠实度评估、在线性能监控、告警规则设置
- 🤖 **Agent与记忆系统** (Q31-Q34)
- 多Agent协作、长期/短期记忆管理、记忆去重
- 🚀 **部署与成本优化** (Q35-Q38)
- LLM选择、嵌入模型选择、系统成本优化、吞吐量提升
- 🔐 **权限控制与安全** (Q39-Q40)
- 权限控制实现、信息泄露防护
**共40个常见问题，详细解答请查看：[Q&A.md](Q&A.md)**
---