知识库工作台实施说明

使用流程

1. 打开知识库模块的“文档中心”，创建目录并上传文件。首期本地解析 PDF（原生文字）、DOCX、PPTX、XLSX、CSV、TXT、Markdown。
2. 人工模式解析后进入文档详情，检查原文、调整规则并生成预览。可以修改、拆分、合并和停用分片；保存会生成新的草稿版本。
3. 在“知识库”中新建知识库、添加文档，选择需要发布的草稿版本。新文档可以关联多个知识库。
4. 在“设置”选择关键词、向量或混合检索。向量/混合模式必须选择模型网关已经发布的 Embedding；Rerank 可选。设置保存为草稿，构建发布完成后生效。
5. 点击“构建并发布”，在处理任务页查看结果。构建失败保留旧发布版本。原文件替换或分片修改后，需要逐库更新草稿版本并发布。
6. 在“检索测试”输入问题，检查内容、来源、召回渠道、融合分数、重排分数和阶段耗时。Agent 使用同一检索服务，且只能访问其配置的知识库。

自动模式须选择目标知识库，解析后按该库默认规则切片，并登记索引发布请求。解析和发布状态分开显示；解析完成不表示已经能被检索。

本地运行

后端 .env 中配置 AGENT_DATABASE_URL、AGENT_MILVUS_URL、AGENT_MILVUS_TOKEN、AGENT_KNOWLEDGE_S3_ENDPOINT、AGENT_KNOWLEDGE_S3_BUCKET、AGENT_KNOWLEDGE_S3_ACCESS_KEY、AGENT_KNOWLEDGE_S3_SECRET_KEY。真实凭据不写入本文档或示例。

cd C:\code\ai-project\backend
uv sync
uv run alembic upgrade head
uv run uvicorn agent_platform.applications.customer_service.main:app --host 127.0.0.1 --port 8000
# 另开终端；解析和索引需要此独立 Worker
uv run python -m agent_platform.applications.worker.knowledge

前端 npm run dev，地址 http://127.0.0.1:5173/#/knowledge。Worker 按配置的 AGENT_TENANT_ID 处理队列；多租户部署需为目标租户配置 Worker，当前不提供动态全租户调度。

已联通的服务地址：PostgreSQL 10.0.11.112:55433，Milvus 10.0.11.112:19530，MinIO 10.0.11.112:19000，桶名 agent-knowledge。服务器及中间件由用户维护，不再由本任务安装或重启。

数据与一致性

• 0019_knowledge_workspace：目录、文档租户与源文件信息、版本解析页、分片来源、知识库文档关联、后台任务、草稿/发布检索配置。
• 0020_knowledge_lifecycle：内容摘要去重、自动发布请求标记、持久向量清理记录。
• 文档版本不可变，人工修改通过新版本表达。知识库分别保存关联的草稿版本和发布版本，不自动替换其他知识库正在使用的版本。
• 发布时核验任务所有权、取消标志、租约和知识库修订号；旧 Worker 不得提交新结果。
• Milvus 集合先完整构建，再在 PostgreSQL 事务中切换集合指针和发布版本；旧集合保留至少五分钟后清理。未完成的集合登记一小时后清理，清理失败延后重试。
• 停用/移除通过 PostgreSQL 结果过滤立即生效。新版本未发布前，旧版本仍可检索。原件按租户、文档和内容摘要归档到 S3；PG 当前仍留有原件副本，存储配额和保留期尚未建设。
• 删除是逻辑删除：停止检索并清除 PG 原件，保留分片版本、审计和 S3 归档；不等同于隐私数据的彻底清除。

接口

前缀 /api/v1/knowledge-workspace：

接口	用途
GET /capabilities	可用格式、Parser/存储配置及上传限制
GET/POST /folders	文档目录
GET /documents	按名称、类型、状态、目录过滤，服务端分页
POST /uploads	上传原文件，人工/自动处理
GET /documents/{id}	原文、分片草稿和知识库关联
GET /documents/{id}/download	下载当前原文件
POST /documents/{id}/replace	替换文件并创建新的解析任务
POST /documents/{id}/preview	预览分片
PUT /documents/{id}/draft	保存新分片版本，校验 revision
PATCH/DELETE /documents/{id}	移动、启停、逻辑删除
GET /libraries/{id}	文档关联、版本和发布任务
POST /libraries/{id}/documents	关联文档或更新关联草稿版本
DELETE /libraries/{id}/documents/{did}	移除关联
PUT /libraries/{id}/settings	保存检索和分片设置草稿
POST /libraries/{id}/publish	异步构建并发布
POST /search	与 Agent 共用的检索链路及诊断
GET /tasks	最近任务
POST /tasks/{id}/retry、cancel	重试、请求取消

原有文本知识接口保留供已有模块和示例使用；新工作台走新版本发布接口。

验证与边界

已验证：真实中间件连接、原件 S3 写入、Milvus 建集合/写向量/检索、关键词与向量融合、重排协议、发布失败保留旧版本、替换文件、租户隔离、版本冲突、取消、管理员和只读用户页面。

模型联调使用 demo Embedding/Rerank，验证协议和数据流，不验证实际语义质量。使用真实服务时需在模型网关创建并发布相应方案，再到知识库设置绑定。没有自动把 demo 模型作为用户知识库的默认模型。

尚未交付：真实 OCR 和旧格式转换适配器、父子分片、页内坐标定位、大文件流式解析、音视频、知识图谱、文档 ACL、正式账号体系。分片字符上限不是模型 Token 上限，真实模型超限会由网关返回错误，不会发布半成品索引。

当前新工作台界面为中文；既有多语言词典保持通过校验，新页面的完整多语言覆盖待补齐。

本次验证记录

• 2026-09-22：29 项知识库及平台相关回归测试通过。
• 后续新增/加强文件格式与失败恢复检查后，6 项知识库专项测试通过，包含真实 Milvus、MinIO 与 PostgreSQL 联调。
• 管理员和只读用户两条 Playwright 页面流程通过；检查桌面分片页和移动检索页。
• 前端 TypeScript、生产构建和现有 i18n 词典检查通过；主应用仍有超过 500 kB 的既有 bundle 提示，知识库页面已单独懒加载。
• 本地 API、前端代理和独立知识库 Worker 已启动。服务器中间件未在本次联调中重启。

分片分页与局部保存

文档详情和规则预览默认每页 20 个分片，使用 offset、limit（最大 100）及 revision 参数。响应包含 chunks、total、offset、limit；详情不再附带完整原文和页面数据。解析原文通过 GET /documents/{id}/source 按需加载，每页最多 10000 字符。

页面保存提交当前页的 offset、replace_count 和编辑后的 chunks，服务端按版本合并其余分片；规则重新生成时携带 regenerate=true，服务端按同一规则生成完整结果后合并当前页修改。翻页前须保存本页编辑，跨页合并暂不支持。版本变化返回 409，避免覆盖他人的新版本。预览仅分页传输与渲染，服务端仍计算整篇分片以获得准确总数。

分片与向量构建确认

分片入口根据现有分片显示“生成分片预览”或“重新分片（生成预览）”，始终确认后执行，已有分片时展示数量并说明未保存编辑将被替换。上传确认同时说明初始分片以及自动模式的后续构建行为。

知识库发布入口按是否配置 Embedding 显示“生成向量并发布”或“发布关键词索引”；已有发布版本时提示重建影响。确认框展示关联草稿的文档和启用分片数量、模型及固定版本、调用费用提示和失败保留旧索引的行为。前端同步锁防止重复点击，提交后至任务完成期间按钮不可重复执行；服务端已有活动任务唯一约束继续防止并发重复创建任务。

可选语义分片

默认仍为 hybrid（智能结构），新增 semantic。选择已发布的 Embedding 配置及固定版本后，系统先按结构生成最多 300 字符的连续文本单元，再按相邻单元余弦相似度合并；低于阈值（默认 0.65）或达到分片长度上限时分开。标题、页面与表格边界保留，纯表格内容按行组处理，不参加语义合并。语义模式不添加重叠。

参数：semantic_profile_id、semantic_profile_version、semantic_threshold。阈值越高通常切分越细。分片分析与最终检索向量是两个独立阶段，后者仍需构建并发布。

数据库 knowledge_semantic_cache 以文档、原文内容、完整规则、固定模型版本与算法版本标识缓存结果，数据库锁防止同一文档的并发重复生成。预览翻页和保存复用缓存；修改参数或原文会重新计算。模型不可用时明确失败，不静默改用其他策略。限制为最多 20000 个分析单元和 10000 个最终分片。首次预览由独立 Worker 后台执行，浏览器提交任务后即可查看进度或取消。Worker 自动处理也支持库级 semantic 配置。

知识工作台界面

文档列表独立展示解析状态、分片数与按关联知识库统计的发布情况；发布统计表示版本记录，不将文档已停用等同于仍可检索。分片编辑使用全宽工作台，规则配置与分页预览左右分区，高级参数折叠，顶部显示解析、分片及按库发布流程。未保存编辑、未生成的规则调整、已保存草稿有不同提示；离开编辑页时保护未保存的内容。关联知识库页签逐库展示草稿和发布版本，可进入对应知识库继续发布。发布面板展示本次构建模型和固定版本、文档版本差异、最近构建任务状态与时间。

分片任务进度与取消

迁移 0024_chunk_preview_tasks 增加 preview 任务类型及 progress/result 字段。工作台使用 POST /documents/{id}/preview-tasks?revision=... 提交固定文档版本与规则的任务；同文档同时只能有一个活动预览任务。GET /documents/{id}/tasks 恢复任务状态，页面每 2 秒轮询，也可点击“刷新进度”。普通分片报告已处理页/内容块，语义分片报告已分析单元/总单元，未知总量的阶段只显示阶段名称。

“取消分片”调用现有任务取消接口；排队任务立即取消，执行中在下一个检查点结束，模型请求本身不保证能撤回。每批语义模型调用前检查取消与租约，写预览前再次检查，因此取消不会覆盖已保存草稿。普通分片按页/内容块检查，整篇策略在计算结束后检查。不支持暂停后断点续跑；取消后重新生成可能重新调用模型。

完成后点击“查看预览”，有未保存编辑时再次确认。结果通过 GET /tasks/{id}/result?offset=0&limit=20 分页读取，最大每页 100；翻页不重新计算。预览绑定原文版本，过期结果返回 409。用户确认保存草稿后才产生新版本。旧同步 preview 接口保留，但工作台不再通过该接口发起长请求。预览结果保存在 PostgreSQL，尚未配置自动过期清理，应后续按保留期限清理终态任务结果。

按文档显示向量生成数量

知识库文档列表显示“总分片 / 已生成向量”。总数为库内草稿版本的启用分片数；构建中按成功写入 Milvus 的批次数量累计，并显示“构建中”，每 5 秒刷新。此时写入完成不代表已发布可检索。任务 progress.documents 记录各文档版本、总数和完成数，重试从新集合的 0 开始。

无活动构建时，仅在草稿与发布版本一致、Embedding 配置版本一致且存在已发布向量索引时显示完整数量，否则显示 0。失败或取消后丢弃临时集合的数量，不将失败进度作为有效向量；旧发布版本仍可使用。仅关键词模式显示 0，停用文档/关联不计入生成数量。旧运行任务没有批次进度时显示“—”，避免虚报。

检索测试分数阈值

搜索请求可传 min_vector_score（-1～1）与 min_rerank_score（有限实数，按重排模型原始分数）。检索测试页面的最低向量相似度默认 0.5，可修改或清空；最低重排分数默认留空。API 未传阈值时仍不进行分数过滤，边界等于阈值时保留。阈值仅影响此次检索测试，不改写知识库发布配置或 Agent 默认检索行为。

向量阈值在 RRF 融合前过滤向量通道，混合检索仍允许关键词通道召回；纯关键词模式不能使用向量阈值。重排阈值在模型返回并归一化为 Top N 后过滤，未配置或未启用重排时不能使用。过滤后允许结果少于 Top K，甚至为空，不通过补回低分结果凑数。界面分别显示向量相似度、融合分数、重排分数，RRF 融合分数不是相似度百分比。

Deepexi 重排端点可能忽略 top_n 并返回全部候选，适配器验证所有编号与有限分数，再按分数排序截取 Top N；重复或越界编号仍拒绝。

模块视觉规范

知识库模块采用统一的浅灰面板、16px 面板圆角、20px 内容间距及标题层级。文档中心、分片工作台、知识库、检索测试、处理任务共用表格、状态、空状态和卡片规则；目录选中使用淡紫色，主要操作保留黑色按钮。模块样式限制在 knowledge-workspace、knowledge-dialog、knowledge-drawer，避免影响其他模块。

检索参数使用带标签的响应式网格，向量、融合和重排分数单独展示；构建历史折叠显示，任务页增加当前列表的状态汇总和刷新入口。弹窗、设置抽屉统一内边距和底部操作区域，样式集中维护于 knowledge.css，移动端统一在 760px/420px 断点调整。