6.4 KiB
系统架构
Vue 3 + TS 前端
| HTTP /api
FastAPI + Pydantic
|-- 知识管理 API -- PostgreSQL
|-- 问答服务
|-- 关键词检索
|-- Embedding 查询向量 -> pgvector 检索
|-- 结果融合 -> 证据检查 -> LLM API
|-- 答案 + 来源
|-- 后台更新任务（后续）
|-- 来源获取 -> 人工核验 -> 文本切分 -> 生成向量 -> 发布版本
当前后端实现健康/数据库就绪检查、来源与文档管理、知识增删改查、分页筛选、人工审核、历史快照、认证会话/角色权限、文本/向量版本及关键词/精确向量检索；问答仍为占位接口。数据库由 Alembic 显式迁移并使用 pgvector，RRF 和 RAG 待后续实现。前端来源登记/查询已接入，实验页仍为静态原型，文档、审核、完整分页与检索页面需继续联调。
阶段 2 数据边界
sources登记来源名称、HTTP(S) 网址和备注；documents登记所属来源、正文、分类与采集时间。knowledge_items保留基础版本全部字段，新增可选来源/文档引用、采集时间、人工审核字段、版本和软删除状态。历史条目不强行补造来源或时间。audit_events在同一事务中保存创建、修改、审核、失效、删除和迁移导入事件；知识快照包含当时关联的来源与文档。version用于内容并发控制，PATCH/审核/DELETE 必须匹配读取版本；ORM 版本检查处理并发写入冲突，引用操作对来源/文档加行锁，避免与修改和删除交错。- 修改知识或关联依据会撤销当前审核结论。未来正式检索必须同时限定
verification_status = 'verified'和is_deleted = false；当前管理列表不承担检索或索引发布功能。 - 文档版本通过递增版本号及完整历史快照留存；
chunks、Embedding 模型版本与索引发布版本在检索阶段单独实现，不能把记录版本当作已实现索引切换。 - 旧库首次升级自动接管基础表，保留条目与导入快照。没有完整审核记录的旧
verified状态回到待审核。启动不自动迁移，缺失或不匹配的版本会明确报错。
安全边界
新增 users、auth_sessions 与 auth_rate_limits。Argon2id 保存密码哈希，随机 Cookie 会话只保存摘要，角色逐次由数据库校验。来源白名单与会话 CSRF 保护写入；改密撤销所有会话。管理资源和检索历史均限管理员，公开检索只返回已核验资料。具体字段、来源、Cookie、预算和迁移见 认证接口契约。
当前仍供本机开发与联调；完整生产部署、网关限流、访问审计、邮箱验证、账号恢复和前端权限页面仍待后续工程验收。
关键词检索基线（T06）
POST /api/retrieval 在同一 SQL 语料快照中筛选有效的已审核知识，读取出处和记录版本，再进行固定中文分词、标题加权 BM25 排序和原文片段截取。语料指纹覆盖本次实际参与排序的内容与出处版本；算法标识和参数独立记录。管理页的字面子串筛选继续用于管理，正式关键词基线使用专用检索接口。
新增 retrieval_runs 保存查询、模式、语料指纹和完整结果快照，支持分页读取及按 UUID 复核。零命中如实记录；当前依据修改后失效不会改写历史，但后续检索必须重新检查审核与父记录状态。响应耗时是本次真实读取、分词、排序及片段生成耗时，不含写日志或模型调用。
关键词基线仍按知识条目检索，显示片段最长 240 字符；持久化 chunks、文本与向量版本见下方。关键词没有倒排索引，全语料计算明确限制条目数及总字符数，超限报错，适用于首批小规模资料与后续对照实验准备，不能当作生产检索性能结论。
切分与索引版本（T05）
index_versions/chunks 保存已审核语料的原文切分、出处与版本、参数、内容哈希及语料指纹。构建先保存 ready 快照，不切换当前发布；index_state 管理发布指针、代数与目录修订号，发布同一事务更新前后状态并追加 index_publications。
目录写入、构建与发布共用状态行锁，目录写入先于父记录锁获取该锁并递增修订号。发布核对代数、修订号和当前语料指纹；失败回滚，保留旧版本。目录变化后旧指针仍可追溯，但 is_current=false，不可据此绕过正式审核。历史快照不会被改写。接口均限管理员并沿用 Cookie/CSRF，完整边界见 INDEX_API.md。
这只是后续索引的文本版本基础，关键词基线行为不变；没有生成向量或宣称已实现 ANN/混合检索。同步构建和全局写锁面向当前有限语料，后续异步/增量发布须重新设计并验证并发协议。
本地 Embedding 评估（T07 准备）
app/services/embedding.py 定义固定模型身份、可替换编码接口及可选 CPU Provider；模型库按需导入，普通 API 启动不加载权重。evaluation/local_embeddings.py 在独立进程中验证真实模型向量和 token 预算，并测量已标注合成样本的资源/排序结果；不读取或写入业务数据库。评估依据和限制见 本地模型评估，API 集成见下方。
向量快照与精确检索（T07）
embedding_spaces/vector_versions/chunk_vectors 将固定空间绑定已发布文本 chunks，复合外键同时约束文本版本、空间和维度，pgvector 检查维度/单位范数。构建只接受完整当前审核快照；模型加载与编码前后分开事务，编码在目录发布锁外，入库前重新复核原文切分、指纹与代数。
vector_state/vector_publications 管理独立向量代数与当前指针，失败事务回滚旧状态。目录或文本发布变化使旧向量不可用于当前检索。公开向量接口按已发布空间执行精确余弦排序，以 chunk 为单位并保留原文偏移/出处；查询编码前后复核同一代数，结果和完整配置进入检索历史。管理与历史仍限管理员。
CPU 运行默认关闭，启用后首次使用离线缓存、延迟加载；同一进程仅一个编码调用，忙则 503。同步快照上限 2000 chunks，没有跨进程队列、ANN 或 RRF；真实领域质量仍待核验语料及独立问题集。字段和完整边界见 VECTOR_API.md。