# kb_system **Repository Path**: wenwang2000/kb_system ## Basic Information - **Project Name**: kb_system - **Description**: kb_system - **Primary Language**: Python - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-30 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 企业级知识库管理系统 · 操作手册 一套面向企业的文档知识库管理系统:支持常见文档的解析入库、**S/A/B/C/D/E 六级保密等级**管控、 **Elasticsearch + Milvus 混合检索与重排**、检索前置优化、**跨密级检索审批流**与**全链路审计**, 模型统一通过**本地 Ollama** 提供,不依赖任何外部大模型服务。 --- 核心解决三件事: 1. **知识沉淀**:把散落在 PDF/Word/Excel/HTML/文本中的资料,统一解析、清洗、分块、向量化后落库; 2. **安全可控**:文档按 S/A/B/C/D/E 六级保密等级管控,检索结果严格不越权,超范围需走审批; 3. **可检索可追溯**:Elasticsearch 全文 + Milvus 向量混合召回并重排,结果给出原文引用; 所有敏感操作全量审计。 **适用版本**:v1.0 **默认访问地址**:http://127.0.0.1:5000 --- ## 1. 环境要求 ### 1.1 软件依赖 | 组件 | 版本 | 端口 | | --- |-------------------------| --- | | Python | 3.10 – 3.13 | — | | MySQL | 8.0+ | 3306 | | Elasticsearch | 8.13 ~ 8.19(**必须 8.x**) | 9200 | | Milvus | 2.4+(Standalone 或嵌入式) | 19530 | | Ollama | - | 11434 | > **端口冲突排查**:若 3306/9200/19530/11434/5000 被占用,改组件端口后同步修改 `.env`。 ### 1.2 技术栈 架构图 ``` ┌──────────────────────────── 接入层 ────────────────────────────┐ │ Web 页面(Jinja2 + 原生 JS) REST API(/api/**,Bearer/ Cookie 双鉴权) │ │ 登录 / 文档管理 / 智能检索 / 审批中心 / 审计日志 / 管理后台 │ └───────────────────────────────┬───────────────────────────────┘ │ ┌──────────────────────── 应用服务层 ──────────────────────────────┐ │ services/ 文档服务 · 审批服务 · 审计服务 · 用户服务 │ │ pipeline/ 解析 → 清洗降噪 → 分块 → 向量化 → 三写(状态机) │ │ retrieval/ 前置理解 → 多路召回 → RRF 融合 → 重排 → 引用 → 生成 │ └───────────────────────────────┬───────────────────────────────┘ │ ┌──────────────────────── 存储与模型层 ────────────────────────────┐ │ MySQL 业务元数据 / 分块原文 / 审批流 / 审计日志 │ │ Elasticsearch kb_chunks 索引(BM25 全文 + 密级过滤) │ │ Milvus kb_chunks 集合(HNSW/COSINE 向量 + 密级过滤) │ │ Ollama 提供大模型服务 │ └───────────────────────────────────────────────────────────────┘ ``` 分层说明 | 层次 | 选型 | | --- |--------------------------------------------------------------------------| | Web 框架 | FastAPI + Uvicorn + Jinja2 模板 + 原生 JS 前端 | | 关系数据库 | MySQL 8.0(业务元数据 / 审批 / 审计),SQLAlchemy 2.x + PyMySQL | | 全文检索 | Elasticsearch 8.x(BM25,中文分词 + 密级 filter) | | 向量检索 | Milvus 2.4(HNSW + COSINE,密级 filter 表达式) | | 模型服务 | 本地 Ollama 部署,0成本(适合自己学习) | | 文档解析 | pdfplumber / pypdf、python-docx、openpyxl、BeautifulSoup + lxml、markdownify | | 中文分词 | Elasticsearch IK 分词插件(ik_max_word 索引 / ik_smart 搜索) | ### 1.3 项目结构 ``` enterprise_kb/ ├── app/ │ ├── core/ 配置、密级/角色/状态常量、安全、错误、日志 │ ├── db/ SQLAlchemy 模型、会话、建表与内置账号 │ ├── schemas/ Pydantic 请求/响应模型 │ ├── clients/ MySQL(DB) / ES / Milvus / Ollama 客户端 │ ├── pipeline/ 文档解析 → 清洗降噪 → 分块 → 入库流水线 │ ├── retrieval/ 前置理解、多路召回、RRF 融合、重排、检索服务 │ ├── services/ 文档、审批、审计、用户领域服务 │ ├── api/ REST 接口(auth/documents/search/approval/audit/admin/system) │ ├── web/ Jinja2 模板、静态资源、页面路由 │ └── main.py 应用入口 ├── scripts/ 初始化与验证脚本 ├── tests/ 单元测试 ├── docs/ 文档 ├── docker-compose.yml docker部署编排 └── init.sh / start.sh 初始化、启动脚本 ``` ### 1.4 数据模型 #### MySQL(库 `kb`,utf8mb4) | 表 | 用途 | 关键字段 | | --- | --- | --- | | `kb_user` | 用户与密级 | `username` `role` `clearance` `department` `is_active` | | `kb_document` | 文档主表 | `doc_no` `title` `level` `status` `version` `summary` `chunk_count` `created_by_name` `updated_by_name` `created_at` `updated_at` `published_at` `error` | | `kb_chunk` | 分块原文与元数据 | `chunk_uid` `doc_id` `chunk_index` `section` `char_count` `text` | | `kb_approval` | 审批单 | `request_no` `action` `target_id` `level_required` `payload` `status` `current_step` `total_steps` `requester_name` `approver_name` `decided_at` | | `kb_approval_record` | 审批步骤流水 | `approval_id` `step` `actor_name` `action` `comment` `created_at` | | `kb_audit_log` | 审计日志 | `trace_id` `actor_*` `action` `resource_*` `level` `result` `detail` `ip` `user_agent` `created_at` | #### Elasticsearch 索引 `kb_chunks` `chunk_uid(keyword)` `doc_id(integer)` `doc_no(keyword)` `doc_title(text, ik_analyzer)` `level(keyword)` `section(text + raw.keyword)` `chunk_index(integer)` `tags(keyword)` `department(keyword)` `status(keyword)` `created_at(date)` `text(text, ik_analyzer)` 自定义分析器 `ik_analyzer` = `ik_max_word` tokenizer + `lowercase` + `cjk_width`(索引时最细粒度切分); 搜索分析器 `ik_search_analyzer` = `ik_smart` tokenizer + `lowercase` + `cjk_width`(检索时智能粗粒度切分)。 密级过滤通过 `terms: {level: [...]}` 实现;`number_of_replicas=0`(单节点部署)。 #### Milvus 集合 `kb_chunks` `chunk_uid(VARCHAR, 主键)` `doc_id(INT64)` `doc_no(VARCHAR)` `doc_title(VARCHAR)` `level(VARCHAR)` `section(VARCHAR)` `chunk_index(INT64)` `text(VARCHAR)` `vector(FLOAT_VECTOR, dim=1024)` 索引:`HNSW`,度量 `COSINE`,参数 `{"M":16,"efConstruction":200}`,检索 `ef=128`。 密级过滤通过 `filter` 表达式 `level in ["S","A",...]` 实现,**在库内完成、不落应用层**。 --- --- ## 2. 部署 ### 2.1 方式一:Docker Compose ```bash cd kb_system docker compose up -d # 拉起 MySQL / ES / Milvus(etcd+minio) / Ollama docker compose ps # 等待各组件 healthy ``` `docker-compose.yml` 已包含 MySQL 8.0、Elasticsearch 8.x、etcd、MinIO、Milvus Standalone、 Ollama 六个服务及数据卷;Milvus 依赖 etcd 与 MinIO 自动编排。 ### 2.2 方式二:使用已有组件 若内已有 MySQL / ES / Milvus / Ollama 集群,仅需修改 `.env`: ```ini MYSQL_HOST=<主机> MYSQL_PORT=3306 MYSQL_USER=<用户> MYSQL_PASSWORD=<密码> MYSQL_DB=<数据库> ES_HOSTS=http://<主机>:9200 # 集群多节点用逗号分隔 ES_USERNAME=<用户> ES_PASSWORD=<密码> # 无认证留空 MILVUS_HOST=<主机> MILVUS_PORT=19530 MILVUS_URI= # 连接 Standalone/集群时留空 OLLAMA_BASE_URL=http://<主机>:11434 ``` **ES 版本要求**:应用依赖的 Python 客户端为 8.x,服务端必须为 ES 8.x。 若使用 ES 9.x,需同步将 `requirements.txt` 中的 `elasticsearch` 升级到 9.x 并调整兼容头。 **Milvus 部署形态选择**: | `.env` 配置 | 部署形态 | 适用场景 | | --- | --- | --- | | `MILVUS_URI=`(留空) | Standalone / 集群(`MILVUS_HOST:MILVUS_PORT`) | 生产 | | `MILVUS_URI=./data/milvus_kb.db` | 官方嵌入式模式(本地数据文件) | 单机开发 / 无独立 Milvus 服务 | ## 3. 初始化 ```bash # 准备需要的模型 ollama pull qwen3.5:9b ollama pull qwen3-embedding:latest # 数据库初始化脚本 ./init.sh ``` --- ## 4. 启动与停止 ### 4.1 启动 ```bash # Linux / macOS 一键启动 ./start.sh ``` 启动日志出现 `Uvicorn running on http://0.0.0.0:5000` 即成功。 ### 4.2 停止 前台 `Ctrl + C`;后台运行用 `pkill -f "uvicorn app.main:app"`。 ### 4.3 健康检查 ```bash curl http://127.0.0.1:8000/api/health ``` --- ## 5. 内置账号 | 用户名 | 初始密码 | 角色 | 密级 | 部门 | | --- | --- | --- | --- | --- | | `admin` | `admin123` | 系统管理员 | S | 系统管理部 | | `approver` | `approver123` | 审批人 | S | 保密管理部 | | `editor` | `editor123` | 知识编辑 | B | 研发中心 | | `viewer` | `viewer123` | 普通用户 | D | 市场部 | ### 角色权限矩阵 | 能力 | admin | approver | editor | viewer | | --- | --- | --- | --- | --- | | 检索(≤ 自身密级) | ✅ | ✅ | ✅ | ✅ | | 上传 / 更新 / 删除文档 | ✅ | — | ✅ | — | | 发起跨密级授权申请 | ✅ | ✅ | ✅ | ✅ | | 处理审批 | ✅ | ✅ | — | — | | 查看全量审计 | ✅ | ✅ | — | — | | 用户与密级管理 | ✅ | — | — | — | | 读取任意密级文档 | ✅ | ✅ | — | — | --- ## 6. 系统功能 | 能力 | 说明 | | --- | --- | | 文档管理 | 12 类格式解析入库,支持新增、更新(版本递增)、下载、分块查看、删除 | | 入库流水线 | 可恢复状态机:`received → parsing → chunked → embedded → indexed → published` | | 密级体系 | S/A/B/C/D/E 六级,文档记录创建人/更新人与时间;B 级及以上发布需审批 | | 混合检索 | BM25 多查询路 + 向量多查询路,RRF 融合后重排,结果附**原文引用** | | 前置优化 | 查询改写、子问题拆分、意图识别(6 类)、关键词提取 | | 密级管控 | 过滤在检索边界内完成(ES terms filter / Milvus filter expr),绝不"先全量后过滤" | | 审批流 | 5 类审批动作 + 完整审批页面,审批通过后自动续跑被拦截的流程 | | 审计 | 14 类动作全量留痕(谁/何时/对什么/结果/密级/IP/UA/明细),支持查询统计与 CSV 导出 | --- ### 保密等级体系 | 等级 | 中文名 | 敏感度分值 | 说明 | | --- | --- | --- | --- | | S | 绝密 | 5 | 最高 | | A | 机密 | 4 | | | B | 秘密 | 3 | | | C | 内部受限 | 2 | | | D | 内部 | 1 | | | E | 公开 | 0 | 默认等级 | ### 检索时序 ``` 用户提问 └─ 前置理解:改写 / 子问题拆分 / 意图识别 / 关键词(Ollama) └─ 权限解析:allowed = ≤ 用户密级;blocked = > 用户密级 └─ 跨密级探测:ES count(blocked 密级 且与问题相关) > 0 ? ├─ 是 → 创建「跨密级检索授权」审批单 → 返回 approval_required + 单号 │ 审批通过后携带 approval_no 重新检索 → 放行至授权密级 └─ 否 → 继续 └─ 多路召回(每条查询变体):ES BM25 × N + Milvus 向量 × N └─ RRF 融合 → 重排(Ollama listwise)→ Top-N └─ 组装原文引用 citations → 生成答案(每条结论带 [编号])→ 写审计 ``` ### 6.1 登录/退出 1. 浏览器打开 `http://127.0.0.1:5000`,自动跳转 `/login`; 2. 输入用户名与密码,点击「登录」; 3. 成功后进入工作台,令牌同时写入 `HttpOnly` Cookie(浏览器会话)与前端存储(API 调用)。 登录失败提示「用户名或密码错误」,同时写入审计(`login` / `denied`)。连续失败可结合审计排查。 ``` # 核心代码 [routes_auth.py](app/api/routes_auth.py) ``` ### 6.2 工作台 `/` 展示当前用户、密级、角色与各功能入口,可快速跳转文档管理、智能检索、审批中心、审计日志、 管理后台。 ``` # 核心代码 [dashboard.html](app/web/templates/dashboard.html) ``` ### 6.3 文档管理 `/documents` **上传文档** 1. 点击「上传文档」; 2. 选择本地文件(支持 pdf/docx/xlsx/xlsm/csv/txt/md/markdown/json/log/html/htm); 3. 填写标题、选择**保密等级**(默认 E)、部门、标签; 4. 提交后: - 等级为 **C/D/E** → 直接进入入库流水线,状态依次推进到 `published`; - 等级为 **S/A/B** → 状态变为 `pending_approval`,需到审批中心处理后方可检索。 **列表与筛选** 支持按标题/文档号关键词、密级、状态过滤与分页;列表仅显示**当前用户可见密级**的文档 (`admin` / `approver` 可见全部)。 **查看分块**:点击「分块」查看该文档切分后的每个 chunk(序号、章节、字符数、原文), 用于确认解析与切分质量。 **下载**:点击「下载」获取原始文件,操作写入审计(`doc.download`)。 **更新**:选择文档 →「更新」,可替换文件或修改标题/密级/部门/标签; 版本号自增,旧版本索引自动失效;S/A/B 级更新同样进入审批。 **删除**:点击「删除」,MySQL 记录、ES 索引与 Milvus 向量同步清除。 ``` # 核心代码 页面操作:[routes_documents.py](app/api/routes_documents.py) 入库操作:[ingest.py](app/pipeline/ingest.py) ``` ### 6.4 智能检索 `/search` 1. 在输入框输入自然语言问题(如"差旅报销标准是多少"); 2. 可选参数:结果条数、是否生成答案、是否启用前置理解; 3. 点击「检索」,页面展示: - **前置理解卡片**:改写后的问句、识别到的意图、拆分出的子问题、提取的关键词; - **答案区**:模型基于资料生成、带 `[编号]` 引用标注的答案; - **命中列表**:每条显示标题、密级、章节、来源(`bm25` / `vector`)与得分; - **原文引用**:每条命中对应的原文片段,可对照核对; - **trace_id 与耗时**:便于与审计日志关联排障。 **跨越密级时的处理** 当检索命中高于自己密级的资料时,系统**不会返回该内容**,而是: 1. 页面提示「命中更高密级资料,需提交跨密级检索审批」并给出**审批单号**(形如 `AP20261031xxxxxx`); 2. 到「审批中心」查看进度; 3. 审批通过后,携带该单号重新检索即可放行至授权密级(在检索框填入审批单号后检索)。 #### 混合检索、多路召回与重排 | 环节 | 实现 | | --- | --- | | 多路召回 | 对**每组查询变体**(改写句 + 各子问题)分别执行 ES BM25 召回与 Milvus 向量召回,得到 `bm25#i` / `vector#i` 多条召回路 | | 融合 | RRF(Reciprocal Rank Fusion,`RRF_K=60`)跨路融合,取候选 `max(top_k*2, 30)` | | 重排 | `retrieval/rerank.py` 基于本地模型对候选做 listwise 重排,输出 `RERANK_TOP_N=8` | | 原文引用 | 每条命中生成 `Citation`:`chunk_uid / doc_no / doc_title / level / section / chunk_index / score / text`,可回溯到 MySQL 中的分块原文 | | 答案生成 | 以引用块(受 `CONTEXT_MAX_CHARS=6000` 预算约束)拼装上下文,要求模型"仅依据资料作答,关键结论标注 [编号],资料不足则明确说明",从机制上抑制幻觉 | | 检索参数 | `RETRIEVAL_TOP_K=20`(每路召回)、`RERANK_TOP_N=8`(最终条数) | #### 检索前置优化 | 能力 | 输出字段 | 说明 | | --- | --- | --- | | 查询改写 | `rewritten` | 补全省略、消除指代、口语转书面,得到更适合检索的问句 | | 子问题拆分 | `sub_questions` | 多目标问题拆为 1–4 个可独立检索的子问题 | | 意图识别 | `intent` / `intent_label` | `fact / summary / compare / process / definition / other` 六类 | | 关键词提取 | `keywords` | 模型抽取 3–8 个关键词;模型未给出时用 ES IK 分词兜底提取 | 可通过 `understand=false` 关闭前置优化(用于排障或纯关键词检索场景) ### 6.5 审批中心 `/approvals` - **待办 / 我发起的 / 全部** 三个视图切换; - 点击某条记录查看详情:申请动作(新建/更新/密级变更/跨密级授权)、目标、申请密级、 申请理由、payload 明细、**审批步骤流水**(谁在何时做了什么); - 审批人可点击「通过」或「驳回」并填写意见; - **通过后系统自动续跑流程**: - 文档类 → 触发对应文档继续入库并推进到 `published`; - 检索类 → 该单号即成为跨密级检索凭证; - 若下游流程受阻(例如模型服务未启动),审批结论仍然生效,失败原因记录在审批单的 `payload.flow_error` 字段与文档 `error` 字段中,排障后重新提交该文档即可。 **审批动作(5 类)**:`create`(新建发布)、`update`(文档更新)、`level_change`(密级变更)、 `access_request`(跨密级检索授权)、`delete`(删除)。 **审批状态(4 类)**:`pending` → `approved` / `rejected` / `canceled`。 **审批流机制**: 1. 触发:文档新增/更新且密级 ≥ B,或用户检索命中高于自身密级的资料; 2. 建单:生成单号 `AP{YYYYMMDD}{6位随机}`,记录申请人、目标、申请密级、理由、结构化 payload; 3. 处理:审批人在**审批中心页面**通过/驳回并填写意见,每次操作写入 `kb_approval_record` 步骤流水; 4. **审批通过后流程继续**: - 文档类审批 → 自动续跑入库流水线,文档状态推进到 `published`; - 检索类审批 → 用户携带 `approval_no` 重新发起检索,`_resolve_levels` 校验该单已通过后 临时放行至授权密级; 5. **续跑失败的容错**:审批结论先落库生效,若后续流水线失败(如模型服务不可用), 失败原因写入审批单 `payload.flow_error` 并在文档 `error` 字段体现,**不会回滚已生效的审批结论**。 > 跨密级探测使用 `ESClient.count_relevant()`:只返回"相关条数",**不返回任何高密级正文**, > 因此申请人不会通过审批提示泄露受控内容。 ### 6.6 审计日志 `/audit` - 筛选条件:操作人、动作、资源类型、密级、结果、关键词、时间区间; - 列表展示时间、操作人(角色/密级)、动作、资源、结果、IP、User-Agent、明细; - 「统计」区域展示按动作 / 结果 / 密级的分组计数与总量; - 「导出 CSV」下载全量(BOM 头,Excel 直接可读); - 普通用户只能看到自己的记录。 `kb_audit_log` 记录字段:`trace_id`、操作人(id/姓名/角色/密级)、动作、资源类型/ID/名称/密级、 结果、明细 JSON、IP、User-Agent、时间。 **审计动作(14 类)**: | 分类 | 动作 | | --- | --- | | 认证 | `login` / `logout` | | 文档 | `doc.upload` / `doc.update` / `doc.delete` / `doc.publish` / `doc.download` | | 检索 | `search` / `retrieve.blocked`(越权命中拦截) | | 审批 | `approval.submit` / `approval.approve` / `approval.reject` | | 管理 | `user.manage` / `level.manage` | - 查询:多条件过滤(操作人、动作、资源类型、密级、结果、关键词、时间区间)+ 分页; - 统计:按动作 / 结果 / 密级分组计数 + 总量; - 导出:`GET /api/audit/export` 输出带 BOM 的 CSV,便于 Excel 打开; - **权限**:仅 `admin` / `approver` 可见全量审计,普通用户只能看自己的记录。 ### 6.7 管理后台 `/admin` - **用户管理**:新增用户(用户名、密码、角色、密级、部门);启用/停用、修改角色与密级、 重置密码; - **运行配置**:查看当前密级定义、角色定义、模型名、分块与检索参数、审批开关; - **组件健康**:MySQL / ES / Milvus / Ollama 逐项状态与版本明细。 --- ## 7、接口清单 所有接口挂载在 `/api` 前缀下,鉴权支持 `Authorization: Bearer ` 与 Cookie 两种方式。 ### 7.1 系统与认证 | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/api/health` | 全局健康检查(MySQL/ES/Milvus/Ollama 逐项状态) | | POST | `/api/auth/login` | 登录,返回 JWT 并下发 HttpOnly Cookie | | POST | `/api/auth/logout` | 登出并清除 Cookie | | GET | `/api/auth/me` | 当前登录用户信息 | ### 7.2 文档 | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/api/documents/meta` | 可用密级、支持的文件扩展名 | | POST | `/api/documents/upload` | 上传文档(multipart:file + title + level + department + tags) | | GET | `/api/documents` | 文档列表(keyword/level/status/分页,按可见密级过滤) | | GET | `/api/documents/{id}` | 文档详情(越权返回 403) | | GET | `/api/documents/{id}/chunks` | 分块列表(含原文) | | PUT | `/api/documents/{id}` | 更新文档(multipart,可换文件 / 改密级,S/A/B 触发审批) | | DELETE | `/api/documents/{id}` | 删除文档(ES + Milvus + MySQL 同步失效) | | GET | `/api/documents/{id}/download` | 下载原始文件(写审计) | ### 7.3 检索与审批 | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/api/search` | 混合检索:`{query, top_k?, rerank_top_n?, levels?, understand?, generate?, approval_no?}` → 命中、引用、答案、`approval_required`、`approval_no`、`trace_id`、耗时 | | POST | `/api/approvals` | 创建审批单 | | GET | `/api/approvals` | 审批列表(scope/status/分页) | | GET | `/api/approvals/{id}` | 审批详情(含步骤流水) | | POST | `/api/approvals/{id}/decision` | 审批处理:`{decision: approve/reject/cancel, comment}` | ### 7.4 审计与管理 | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/api/audit` | 审计查询(多条件 + 分页) | | GET | `/api/audit/stats` | 审计统计(按动作/结果/密级) | | GET | `/api/audit/export` | 导出 CSV | | GET | `/api/admin/users` | 用户列表 | | POST | `/api/admin/users` | 新建用户(角色 + 密级) | | PUT | `/api/admin/users/{id}` | 修改用户(角色/密级/启停/重置密码) | | GET | `/api/admin/config` | 当前运行配置(密级、角色、模型、检索参数) | | GET | `/api/admin/health` | 组件健康明细 | ### 7.5 Web 页面 | 路径 | 页面 | | --- | --- | | `/login` | 登录 | | `/` | 工作台 | | `/documents` | 文档管理 | | `/search` | 智能检索 | | `/approvals` | 审批中心 | | `/audit` | 审计日志 | | `/admin` | 管理后台 | ### 7.6 错误码 | HTTP | code | 触发场景 | | --- | --- | --- | | 400 | `BAD_REQUEST` | 参数错误(如非法密级、不支持的文件类型) | | 401 | `UNAUTHORIZED` | 未登录 / 令牌无效或过期 | | 403 | `PERMISSION_DENIED` | 越权访问文档、非授权角色操作 | | 404 | `NOT_FOUND` | 文档 / 审批单不存在 | | 409 | `CONFLICT` | 状态冲突(如重复审批) | | 500 | `INTERNAL_ERROR` | 处理失败(流水线异常) | | 503 | `DEPENDENCY_UNAVAILABLE` | MySQL / ES / Milvus / Ollama 任一不可用 | --- ## 8. 关键参数 | 参数 | 默认值 | 含义 | | --- | --- | --- | | `CHUNK_SIZE` / `CHUNK_OVERLAP` | 600 / 80 | 分块长度与重叠字符数 | | `MIN_CHUNK_CHARS` | 20 | 小于该值的碎片在章节内合并 | | `MAX_UPLOAD_MB` | 100 | 单文件上传上限 | | `EMBED_DIM` | 1024 | bge-m3 向量维度 | | `RETRIEVAL_TOP_K` | 20 | 每路召回的候选数 | | `RERANK_TOP_N` | 8 | 重排后最终保留条数 | | `RRF_K` | 60 | RRF 融合平滑常数 | | `CONTEXT_MAX_CHARS` | 6000 | 送入生成模型的上下文预算 | | `PUBLISH_APPROVAL_MIN_LEVEL` | `B` | 需发布审批的起始密级(S/A/B 需审批) | | `APPROVAL_ENABLED` | `true` | 审批流总开关 | | `MAX_AUTO_LEVEL` | `A` | 自动放行的最高密级上限 | | `ACCESS_TOKEN_EXPIRE_MINUTES` | 480 | 登录令牌有效期(分钟) | --- ## 9. REST API 使用示例 ```bash # 登录,保存 Cookie curl -c cookie.txt -X POST http://127.0.0.1:8000/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"username":"editor","password":"editor123"}' # 上传文档(S 级将进入审批) curl -b cookie.txt -X POST http://127.0.0.1:8000/api/documents/upload \ -F 'file=@差旅制度.pdf' -F 'title=差旅报销制度' -F 'level=B' -F 'department=财务部' -F 'tags=[]' # 混合检索 curl -b cookie.txt -X POST http://127.0.0.1:8000/api/search \ -H 'Content-Type: application/json' \ -d '{"query":"差旅报销标准","generate":true,"understand":true}' # 凭审批单号重试跨密级检索 curl -b cookie.txt -X POST http://127.0.0.1:8000/api/search \ -H 'Content-Type: application/json' \ -d '{"query":"差旅报销标准","approval_no":"AP20261031ABCDEF"}' # 审批通过 curl -b cookie.txt -X POST http://127.0.0.1:8000/api/approvals/1/decision \ -H 'Content-Type: application/json' -d '{"decision":"approve","comment":"同意"}' ``` ---