Skip to content

文档上传到问答全链路:WeKnora 源码拆解 ​

前面几篇讲的是通用原理。这一篇换一个视角:一个真实系统如何把这些环节串起来,以及哪些地方最容易出错。

以下拆解来自对 WeKnora 公开源码与测试的静态阅读,不依赖本地环境。文中把“源码已实现”和“文档中的目标设计”分开写:前者可以在代码与测试中核对,后者只是规划,不把它当成现状。

1、先看两张链路图 ​

1.1 摄取链路 ​

text
浏览器上传
 → 原文件/资源引用
 → knowledge 记录(pending + disabled)
 → document:process 异步任务
 → 解析(Go Reader / Python DocReader)
 → 规范化 + 来源位置索引
 → Go 分块
 → 保存 chunks
 → 向量/关键词索引
 → 图片增强 fan-in
 → 后处理增强 fan-in
 → 状态收敛(completed / failed)

1.2 问答链路 ​

text
问题 + 检索范围
 → 服务端鉴权 / 目标归一化(SearchTargets)
 → 保存用户消息
 → 创建助手占位消息
 → 查询理解(可选改写)
 → 多路召回(向量 / 关键词 / 标签)
 → 融合(RRF)
 → 重排(rerank + 规则)
 → 证据合并
 → TopK 截断
 → 组装 Prompt(模型上下文句柄)
 → 模型流式生成
 → 事件总线 / StreamManager
 → SSE
 → 消息与引用持久化
 → 对外 complete

两条链路通过持久化的知识记录、块和索引衔接,不存在覆盖整条链路的共同事务。这是理解后面所有一致性问题的基础。

2、四个“完成”信号,含义完全不同 ​

信号含义不代表
浏览器上传 100%文件传输完成服务端已收到、已登记
上传接口 success=true请求被受理文档已解析、可检索
文档 completed处理生命周期收敛每条增强都成功、答案正确
流 complete本轮输出收尾内容一定正确、消息一定已落库

把它们混为一谈,是很多“显示完成了但搜不到”“回答完了但刷新空白”问题的根源。

3、上传:浏览器队列与服务器队列不是一回事 ​

3.1 服务端入口 ​

永久知识库文件上传走:

text
POST /api/v1/knowledge-bases/{kb_id}/knowledge/file
Content-Type: multipart/form-data

关键字段:

  • file:文件本身;
  • fileName:文件名;
  • tag_ids:标签;
  • process_config:JSON 字符串,解析/切分配置。

URL 导入、手工内容、FAQ、会话附件都有独立入口,不能都解释成这个上传接口。

相关源码:

  • internal/handler/knowledge.go:CreateKnowledgeFromFile
  • internal/application/service/knowledge_create.go:createKnowledgeFromFile、markKnowledgeEnqueueFailed
  • internal/application/service/knowledge_util.go:calculateFileHash

3.2 创建顺序 ​

text
校验类型 / KB / 配置
 → 计算文件内容 MD5
 → 在目标范围检查重复
 → 配额检查
 → 保存文件
 → 创建 pending + disabled 的 knowledge 记录
 → 绑定标签
 → 投递 document:process

注意顺序:先保存文件,再写数据库。 如果数据库创建失败,系统会尽力删除已保存文件,但补偿本身也可能失败。因此需要一个对账/清理机制,不能假设“失败一定干净”。

3.3 一个反直觉的契约 ​

当前上传 Handler 实际返回 HTTP 200。创建服务在序列化任务或入队失败时,会把 parse_status 标记为 failed,但仍返回 knowledge, nil。外层因此可能仍然得到 success=true。

结论:客户端不能只看 HTTP 状态和 success 字段,必须读返回对象里的真实状态。 这是接口契约层面的坑,不是前端粗心。

默认上传大小限制为 50 MB,部署可配置,不能写成所有环境固定值。

3.4 前端上传队列 ​

当前前端实现有几个值得借鉴的细节:

  • 全局默认并发 3;
  • 同一知识库、相同大小的文件不同时在途,让后一个文件能看到前一个已经创建的数据库记录,从而触发内容去重;
  • 大小不是去重结论,也不是服务器级唯一性保证;
  • 传输完成但响应未返回时显示 saving,不接受普通取消——因为服务端可能已经创建了文档,浏览器中断不能撤销服务器事实;
  • generation 与 AbortController 身份共同隔离迟到回调;
  • 取消后重试复用同一条 UI 记录,但旧请求不能覆盖新请求;
  • 传输失败/取消的重试需要保留原始 File,与后台 reparse 不同。

源码:

  • frontend/src/stores/uploadQueue.ts:transfer、cancel、retry、dedupKey
  • frontend/src/stores/uploadTasksCore.ts:并发与轮询参数
  • frontend/src/stores/uploadQueue.test.ts:迟到回调隔离测试

这组设计的核心思想:服务器事实优先于浏览器状态。 浏览器可以取消显示,但不能假装服务器没收到。

4、摄取:Go 主编排,Python DocReader 是其中一段 ​

ProcessDocument 的职责:

  1. 恢复租户和知识记录;
  2. 检查任务是否旧轮次、已取消、删除中、不应重复运行;
  3. 确认源文件身份;
  4. 选择解析器;
  5. 解析 → 规范化 → 分块 → 索引;
  6. 推进状态。

源码:internal/application/service/knowledge_process.go 的 ProcessDocument、convert、callDocReaderWithTimeout、processChunks。

4.1 解析器选择 ​

按配置选择 Go Reader、Python gRPC DocReader 或其他注册引擎。

gRPC 路径优先 ReadStream;只有 codes.Unimplemented 才回退 unary Read。不能把超时、服务错误都当成“协议不支持”而降级,否则会掩盖真正的故障。

相关源码:

  • internal/infrastructure/docparser/grpc_parser.go:GRPCDocumentReader.Read、readStream、readUnary
  • docreader/main.py:Read、ReadStream

4.2 两个容易误解的点 ​

  1. ReadStream 主要改善解析结果/图片的传递;当前 convert 仍会 io.ReadAll(fileReader) 把源文件读成字节,不是任意大文件的端到端零缓冲上传。
  2. DocReader 默认调用超时 30 分钟,实际还受父任务 deadline 限制。解析调用超时与整个文档任务超时是两层约束。

解析输出保留 Markdown、元数据、图片与 source_blocks;规范化后建立来源位置索引,把块范围映射回页码、文本或图片位置。这是后续引用能定位回原文的基础。

5、切分与索引:正文和检索输入分开 ​

5.1 切分策略 ​

当前策略入口支持 legacy、heading、heuristic、recursive、auto,是否启用由配置决定。不能说“所有文档都会自动使用某一种高级策略”。

最值得学习的不变量:

text
Content == 原文 [Start, End) 的精确切片
位置单位是 rune
End - Start == 正文 rune 数

标题层级 breadcrumb 单独保存在 ContextHeader,用于检索输入,不污染正文坐标。

源码:

  • internal/infrastructure/chunker/splitter.go:Chunk、SplitterConfig、DefaultConfig
  • internal/infrastructure/chunker/strategy.go:Split、SplitParentChild、NormalizeSplitterConfig
  • internal/infrastructure/chunker/tokens.go:ApproxTokenCount
  • internal/types/chunk.go:Chunk.EmbeddingContent、ContextHeader、SourceLocators

5.2 检索输入 ​

基本由三层组成:

text
文档标题 + ContextHeader + 块正文

buildKnowledgeIndexContent 只加入文档标题,不把文档自定义元数据重复塞进每个块的嵌入。元数据可以在回答上下文中按文档展示。

默认块大小/重叠为 512/80 字符,不是精确 token。可选的 TokenLimit 使用语言相关的近似估计,也不是模型官方分词器的精确计数。

源码:internal/application/service/knowledge_index_content.go 的 buildKnowledgeIndexContent。

5.3 父子块 ​

  • 父块和子块都写业务库;
  • 父块不重复进入普通文本向量索引;
  • 子块带 ParentChunkID;
  • 召回子块后恢复父级上下文。

这避免了同一内容被重复检索,同时保留“小块精准、大块完整”的好处。

5.4 批量索引与资源控制 ​

BatchIndex 根据 retriever 类型决定是否调用 embedding;关键词-only 路径不强制向量化。

当前批量向量索引有明确的资源控制:

  • 每个窗口最多 200 项;
  • 保存批次 40;
  • 保存并发 5;
  • 完成当前窗口写入后才处理下一窗口,不把全篇向量一直留在内存。

embedding 批调用最多尝试 5 次,初始退避 200 ms,实际最多四次等待:200/400/800/1600 ms。它与文档任务的 MaxRetry(3) 是两层机制:MaxRetry(3) 指允许重试三次,不是总共执行三次。

源码:internal/application/service/retriever/keywords_vector_hybrid_indexer.go。

5.5 部分失败 ​

块已保存、索引失败时,系统会尝试删除块和该文档索引;如果还有重试机会,保留可重跑状态并返回错误;最终尝试才记录失败。

清理同样可能部分失败,所以这不是跨存储原子回滚。工程上要接受“最终一致 + 对账修复”,而不是追求不存在的分布式事务。

6、状态:文档可用与后台工作结束是两个时间点 ​

6.1 两条状态,不是一个“完成” ​

正文是否可用后台工作是否结束
正文与索引已写入,enabled增强任务是否都到终态,由计数决定
某些 processing + enabled 窗口也能检索completed 不保证每项增强成功

enable_status、摘要状态、任务计数、处理轮次 attempt 是不同维度;不能只看 parse_status 判断能否检索。

6.2 多个任务怎样汇合(fan-in) ​

图片任务终态后汇合并触发后处理;后处理再登记摘要、问题生成、图谱、Wiki 等任务名额。下面只选两项看计数变化:

可检索不等于后台工作已结束
可检索不等于后台工作已结束先进入 finalizing 并登记两个任务,再分发。当前剩余任务 2,状态 finalizing,全文一直 enabled。正文已索引:enabled,可供检索先登记名额,再分发任务finalizing · pending = 2摘要任务处理中,不扣名额问题生成任务处理中 / 重试,不扣名额剩余 2 个 → 仍是 finalizing(正文仍可检索)
结算与条件提升须在同一 SQL 事务内;重试途中不结算。示例仅含两项增强,不代表全部任务。

FinalizeSubtask 在同一 SQL 事务中 减计数 + 条件提升;只有 finalizing AND pending_subtasks_count=0 才提升。诊断回读不决定提升,中途重试不释放名额。它不是跨存储事务,也不保证全链路 exactly-once。自动标签等旁路和知识库级 Wiki reduce 不属于这组计数。

源码:

  • internal/application/service/knowledge_post_process.go:KnowledgePostProcessService.Handle
  • internal/application/repository/knowledge.go:SetFinalizing、FinalizeSubtask、finalizeSubtask、CompleteProcessingWithoutSubtasks

对应测试:

  • internal/application/repository/knowledge_finalize_test.go
    • TestFinalizeSubtask_Concurrent_ExactlyOnePromote
    • TestFinalizeSubtask_FailedPromoteRollsBackDecrement
    • TestUpdateKnowledge_DoesNotClobberPendingCounter

6.3 任务执行器 ​

普通模式使用 Redis + Asynq;Lite 使用进程内 goroutine。

当前 Lite 已实现延迟、重试、timeout/deadline、TaskID 和最终失败钩子,不是“没有重试”;但它不具有 Redis 队列同等的进程外持久性与任务巡检/取消能力。

源码:internal/router/sync_task.go 的 SyncTaskExecutor.Enqueue。

7、提问:范围归一化比想象中复杂 ​

7.1 入口与消息 ​

普通问答路径:

text
POST /api/v1/knowledge-chat/{session_id}

服务端会:

  1. 校验会话、资源、模型权限及当前轮次占用;
  2. 先保存用户消息;
  3. 再保存 is_completed=false 的助手占位;
  4. 占位创建失败时,有回滚用户消息的路径。

X-Request-ID 是日志/事件关联标识,不自动等于生成 POST 的幂等键。

源码:

  • internal/handler/session/qa.go:parseQARequest、persistTurnMessages、executeQA
  • internal/application/service/session_knowledge_qa.go:KnowledgeQA、buildSearchTargets、KnowledgeQAByEvent

7.2 检索范围 SearchTargets ​

包含:真实知识库、知识文件、标签约束、来源租户。

几个容易误解的规则:

  • 选择完整知识库且没有标签约束时,该库下再列出的文件会被视为已覆盖,不会缩成“只查这些文件”;
  • 文档标签会解析成文件集合;与显式文件范围同时存在时,可能取交集;
  • FAQ 标签的作用路径不同;
  • 仅标签范围也可能需要检索;
  • 共享知识库的归属租户与会话/执行租户可能不同,不能把“租户 ID 不同”简单等同非法,也不能跳过共享授权。

这段逻辑如果只在 Prompt 里写“只能回答本租户内容”,是做不到隔离的;必须在检索范围归一化阶段完成。

7.3 查询理解 ​

保留 Query,并初始化 RewriteQuery = Query,按配置补全追问/识别意图。

关闭、模型不可用或调用失败时,可以继续使用原问题;不应丢用户输入。

源码:internal/application/service/chat_pipeline/query_understand.go 的 PluginQueryUnderstand.OnEvent。

8、检索管线:每个插件只做一件事 ​

普通 RAG 管线的实际阶段:

text
LOAD_HISTORY?
 → MEMORY_RECALL
 → QUERY_UNDERSTAND
 → CHUNK_SEARCH_PARALLEL
 → CHUNK_RERANK
 → WEB_FETCH?
 → CHUNK_MERGE
 → FILTER_TOP_K
 → DATA_ANALYSIS?
 → INTO_CHAT_MESSAGE
 → CHAT_COMPLETION_STREAM

纯聊天跳过知识检索,但仍可有历史、记忆、图片和临时附件。Agent 是另一种可工具循环的运行模式,不能硬套固定 RAG 管线。

8.1 向量复用按模型空间分组 ​

当前 key 为 模型名 + endpoint + 配置维度,不只是 model ID。跨租户使用同一底层模型时,可以复用一次问题 embedding。

相同维数不代表任意两个模型在同一语义空间,所以不能只用维度做 key。

8.2 降级规则 ​

  • 文本 embedding 失败时,只有存在真实关键词路径的目标才允许降级;
  • vector-only 目标保留根因,不能伪装成“未命中”;
  • 图片查询不能悄悄改成文本关键词检索;
  • 多目标搜索存在部分成功保留路径,某一路失败不是无条件抛弃其他有效结果。

源码:

  • internal/application/service/knowledgebase_search.go:ResolveEmbeddingModelKeys、HybridSearch
  • internal/application/service/chat_pipeline/search.go:searchByTargets、searchSingleTarget

对应测试:

  • internal/application/service/chat_pipeline/search_error_test.go
    • TestSearchEmbeddingFailureIsNotReportedAsNoResults
    • TestSearchEmbeddingFailureDegradesToKeywordSearch
    • TestSearchEmbeddingFailureOnVectorOnlyTargetPreservesRootCause
    • TestSearchKeepsSuccessfulResultsWhenAnotherTargetFails

8.3 融合:不是把 BM25 和余弦相加 ​

当前实现分三种:

  • vector-only:保留原始检索分数;
  • keyword-only:对无界 BM25 按各自列表最高分归一化;已经落在 [0,1] 的分数不随意重标定;
  • hybrid:加权 RRF,再除以理论最大值:
text
(w_v/(k+r_v) + w_k/(k+r_k)) / ((w_v+w_k)/(k+1))

其他规则:

  • 缺席某路不虚构排名;
  • 跨多个返回列表时,取该候选在各列表中的最好排名;
  • 不按并发返回顺序拼接后再排名;
  • 同分用 chunk ID 等稳定规则打破平局。

源码:

  • internal/application/service/knowledgebase_search_fusion.go:fuseOrDeduplicate、fuseWithRRF、bestRanks、rescaleUnboundedScores

对应测试:

  • internal/application/service/knowledgebase_search_fusion_test.go
    • TestFuseOrDeduplicate_KeywordOnlyRescalesUnboundedBM25
    • TestFuseOrDeduplicate_HybridTopOfBothScoresOne
    • TestFuseOrDeduplicate_HybridRanksEachListOnItsOwn
    • TestFuseOrDeduplicate_HybridIgnoresArrivalOrder

8.4 重排 ​

统一入口 reranking.Rerank 包含:

  • 候选上限;
  • passage 长度适配;
  • 阈值过滤;
  • 综合分;
  • MMR 选取;
  • 图片保留规则。

当前综合分:

text
0.6 * modelScore + 0.3 * baseScore + 0.1 * sourceWeight

随后可施加 FAQ boost。这是当前实现,不是通用推荐公式。FAQ 高置信判断取 boost 前的分数,防止人为权重制造“高置信”。

失败路径:

  • 未配模型 → 回退召回结果;
  • 模型加载失败 → 回退;
  • 重排 API 失败 → 回退;
  • 成功重排但阈值过滤为空 → 真正的无结果。

源码:internal/reranking/rerank.go 的 Rerank、CompositeScore、PreBoostScore。

8.5 证据合并 ​

PluginMerge 依次处理:

text
去重
 → 历史引用补入
 → 父块还原
 → 同来源连续/重叠片段合并
 → FAQ 回答恢复
 → 邻居扩展
 → 再次去重

注意:

  • 不能对任意看起来相似的表格行做文本去重;
  • 编辑/改写后的内容不能继续盲信旧坐标;
  • 引用应定位实际命中的来源。

源码:

  • internal/application/service/chat_pipeline/merge.go:PluginMerge.OnEvent、resolveParentChunks
  • internal/application/service/chat_pipeline/filter_top_k.go:sortSearchResultsDeterministically、collapseParentSlots

对应测试:

  • internal/infrastructure/chunker/parent_child_offsets_test.go
  • internal/application/service/chat_pipeline/merge_position_path_test.go
    • TestGroupAndMerge_TrustedAdjacentRepeatedTextKeepsEveryRow
    • TestGroupAndMerge_SameLengthRewriteKeepsBoth

最终 TopK 有稳定排序、可选父块占位聚合和图片保留项,不保证数组长度严格等于 K。

9、证据、Prompt 与引用协议 ​

9.1 引用主体不是 chunk_id ​

引用主体是 SearchResult,包含:

  • 正文;
  • 文档 ID / 标题;
  • 顺序、范围;
  • 匹配类型、分数;
  • 父子关系;
  • 可选来源定位、图片、元数据。

VectorScore 的 JSON tag 是 -,不是保证对外输出的 vector_score。

源码:internal/types/search.go。

9.2 模型上下文句柄 ​

最终送给聊天模型前,会经过 prepareMessagesWithModelContext 和 modelcontext.Registry。

模型看到的是请求内句柄,例如 chunk://N、doc://N,以及结构化来源,而不是让模型直接复制 UUID 或长 URL。

规则:

  • 检索结果注册为本轮证据;
  • 历史引用/导航身份不自动获得本轮可引用资格;
  • 模型输出 <ref id="chunk://N"/>,服务端只对已注册且可引用的句柄展开为公开引用;
  • 模型直接写的公开引用标签会被移除;
  • 未知/未获证据资格的引用不会变成可信来源;
  • 流式解码器处理跨 token/帧拆开的引用与资源句柄,避免半个私有协议泄漏到 UI。

这些句柄不是授权凭证;实际资源访问仍单独鉴权。它约束的是引用身份,不是事实正确性。

源码:

  • internal/application/service/chat_pipeline/into_chat_message.go
  • internal/application/service/chat_pipeline/references.go:prepareMessagesWithModelContext
  • internal/modelcontext/registry.go:Registry、EncodeMessages、RegisterSearchResults、StreamDecoder
  • internal/modelcontext/citations.go:citationTag、ExpandText、citationStreamExpander

对应测试:

  • internal/modelcontext/sources_test.go
  • internal/modelcontext/citations_literal_test.go

9.3 数据边界提示 ​

系统提示中已有 SourceDataBoundaryPrompt,把文档、附件、元数据、网页和工具结果声明为不可信证据数据。

这比“完全没有防护”强,但不能声称提示注入已被彻底解决。提示词是软约束,真正的边界仍在权限、工具鉴权和输出校验。

源码:internal/types/prompt_instructions.go。

9.4 预算边界要谨慎表述 ​

当前可以确认:

  • 历史轮数控制;
  • TopK/候选裁剪;
  • 局部 passage/字符限制;
  • 输出 token 参数。

但在本次阅读的普通 QA 最终消息组装中,没有看到统一的“整份 Prompt 精确 token 总预算裁剪器”。不能把 TopK、近似块 token 或 max_completion_tokens 写成“已经保证总输入不超窗”。

10、流式收尾:complete 不等于成功 ​

10.1 主时序 ​

text
创建消息
 → agent_query 关联助手 ID
 → 发出 references
 → answer 增量
 → 内部完成整理
 → 数据库保存成功
 → 对外 complete

保存失败会发 error.stage=message_persistence,不发布成功完成承诺。

错误路径可以保存部分答案及错误文字,再 complete 收尾。因此 complete 和 is_completed 都不等于业务成功。

源码:

  • internal/handler/session/qa.go:completeQuickAnswerTurn、completeStreamAssistantMessage、completeAssistantMessage
  • internal/handler/session/helpers.go:buildStreamResponse、createAgentQueryEvent
  • internal/handler/session/agent_stream_handler.go:handleComplete、publishCompletion

对应测试:

  • internal/handler/session/image_completion_test.go
    • TestSharedImageCompletionWaitsForPersistedReferences
    • TestQuickAnswerCompletionPersistsAfterGenerationCancellation

10.2 为什么必须先落库 ​

如果 complete 早于消息落库:

  • 用户刷新可能看不到消息;
  • 共享图片/文件访问授权可能依赖已持久化消息中的引用证据,前端收到 complete 就加载资源,可能立刻被拒绝;
  • 断线重连拿到的状态可能不完整。

10.3 前端消费 ​

前端用 @microsoft/fetch-event-source 发认证 POST,不是原生 EventSource 的 GET。

  • 答案在顶层 content;
  • 引用主要在顶层 knowledge_references;
  • 以 response_type 分发;
  • 不能见到任意 done=true 就关闭整轮:例如 agent_query 本身的 Done 为 true,事件类型才是解释语义的前提。

流管理器支持 memory/Redis;Redis 工厂默认事件缓存 TTL 一小时,不是永久日志。

源码:internal/stream/factory.go、frontend/src/api/chat/streame.ts。

11、停止与恢复:服务端控制面 ​

11.1 停止 ​

text
前端中止本地流并推进 streamGeneration
 → POST /api/v1/sessions/{session_id}/stop(带 message_id)
 → 服务端校验消息和会话所有权/租户
 → 往共享 StreamManager 写 stop
 → 独立 watcher 读到后取消实际生成上下文
 → 用不被此次取消带走的上下文保存已有内容

独立 watcher 每 300 ms 轮询,观察 stop/complete/终态 error 后自行退出,另有两小时防泄漏上限。

不能绑定“KnowledgeQA 方法已返回”就销毁 watcher,因为普通问答方法可能在 token goroutine 完成前就返回。

源码:internal/handler/session/stream.go、internal/handler/session/helpers.go 的 setupStopEventHandler、startStopWatcher。

11.2 恢复 ​

刷新后:

  1. GET /api/v1/messages/{session_id}/load?limit=20;
  2. 发现未完成的助手消息;
  3. GET /api/v1/sessions/continue-stream/{session_id}?message_id=...;
  4. 服务端从事件 offset 0 回放并继续读取。

现有回放还有 coalesce 处理;它不是“重发生成 POST”。

11.3 自动重连的条件 ​

前端自动重连有前提:

  • 非 embed;
  • 已拿到助手 ID;
  • 没有终态;
  • 原入口是 agent-chat 或 continue-stream。

普通 knowledge-chat 原连接并不享受同一套无条件自动重连,但刷新页面发现未完成消息后可以主动续流。

空闲检查 30 秒,重试退避 1/2/4/5 秒,最多连续失败 8 次,事件到达重置计数。

11.4 恢复能力的边界 ​

  • 内存模式进程重启会丢实时回放;
  • Redis 缓存过期会丢回放;
  • 历史消息库才是持久展示依据,缓存不是无限期恢复系统;
  • 停止受理成功也不保证远端模型瞬间停止计费。

12、八个高价值故障机制 ​

下面这些是源码注释或回归测试明确覆盖的机制,适合作为设计评审的检查点。它们不是“线上事故复盘”,而是“系统为防止某类问题所做的设计”。

12.1 完成状态是分布式协议 ​

  • 核心索引结束就标 completed,后处理可能看到非 processing 而跳过,摘要状态永远 pending;
  • 先发子任务再初始化计数,快任务可能提前结算,文档永远卡 finalizing;
  • 减计数提交而提升失败,如果不是同一事务,最后一个名额没了,没人再提升;
  • 先 SELECT 计数再决定 promote,读副本滞后可能导致所有 worker 都认为“还有任务”。

当前实现每次无条件尝试 guarded UPDATE,以主库写条件作为真实裁决。

12.2 重解析的旧轮次污染 ​

旧 document worker 可能删除新块,旧后处理可能重新播种计数,旧增强任务也可能扣减新轮次名额。

当前有 attemptSuperseded 及多个阶段检查;新 attempt 的打开时机放在可能拒绝 reparse 的验证之后,避免“新轮次已开但重解析被拒绝”,把旧任务全判过期却无人结算。

测试:internal/application/service/knowledge_attempt_supersede_test.go。

12.3 混合检索的分数可比性 ​

  • 直接把 BM25 混进 [0,1] 相似度,综合分会饱和;
  • 未归一化的 RRF 最大值很小,可能输给其他路径;
  • 多列表拼接后排名,会让后返回列表的好结果平白落后。

当前分别用按列表归一化、RRF 理论最大值缩放、各列表独立排名和稳定 tie-break 处理。

12.4 chunk 同时服务语义与坐标 ​

ContextHeader 和正文分离,既让短子块带章节语义,又保留源位置不变量。

容易踩坑的场景:

  • 父块扩展;
  • 编辑后的内容;
  • 重复表格行;
  • 同长度改写。

测试:parent_child_offsets_test.go、merge_position_path_test.go。

12.5 “检索失败”和“没有知识”不能共用兜底 ​

embedding 服务坏了而 vector-only 知识库没有关键词索引,正确结果是保留服务错误,不是“知识库没有答案”。

如果多目标其他来源成功,可以保留部分结果及诊断。

用户在检索中停止时,取消后的空结果也不能触发“无结果回答”,否则刷新后会看到一段用户从未要求的兜底答案。

12.6 生成完成不等于答案可安全读取 ​

complete 若早于消息落库,不仅刷新可能空白,共享图片/文件访问授权也可能失败。

当前把内部完成准备与外部 publishCompletion 拆开,保存成功才发布;保存失败专门报 message_persistence。

12.7 停止不能只靠 AbortController ​

历史故障机制在源码注释中有描述:旧停止检测绑定 SSE 请求,调用方先断 SSE 再 POST stop,虽然 stop 写入共享流并返回成功,却没有活着的消费者把它转成 context cancellation,模型继续运行。

当前独立 stop watcher 解决“控制消费者随数据连接一起消失”的问题。前端 generation 解决另一层问题——旧事件串到新会话。二者不能互相替代。

12.8 引用是身份协议 ​

请求内句柄减少模型复制 UUID/长 URL 的负担;引用资格与导航地址分开;流式半标签先暂存,校验后才展开;历史中出现过一个来源,不自动证明本轮重新获得它的证据资格。

应强调:它防引用身份伪造/协议泄漏,不是自动事实核查器。

13、现有实现与目标设计的分界 ​

13.1 当前确实存在 ​

  • 根目录 Vue/Pinia 前端、Go Handler/Service/Repository、Go chunker/索引编排、Python DocReader 解析服务;
  • Redis + Asynq 和 Lite 进程内执行器两条任务路径;
  • 父子分块、来源定位、混合检索/RRF、重排/MMR、证据合并;
  • 消息占位、事件总线/StreamManager/SSE、停止与续流;
  • attempt 轮次检查、增强任务 fan-in、局部数据库事务、清理补偿;
  • 模型上下文句柄/证据资格编解码、来源数据不可信提示。

13.2 文档中属于目标、不可写成已落地 ​

  • FastAPI 全 Python 业务后端、SQLAlchemy 2 async + SQLite 的新最小闭环;
  • 生产目标 Redis + ARQ,以及之后的 PostgreSQL/对象存储验证路径;
  • 新的 python/backend/app/{services,repositories,integrations,workers} 与独立 python/frontend 模块划分;
  • S0—S10、60 步路线、建议测试矩阵和假模型验收,不是完成情况或真实模型质量报告;
  • 建议内部显式区分 success/failure/stopped,不代表现有外层协议已改成单一严格终止事件。

本次目录核对没有发现 refactor/python/;refactor/AGENTS.md 对 Python 目录的描述是工作区指南/目标组织,不能用它代替实际代码存在证据。

13.3 阅读时需要保留的限制 ​

  1. REFERENCE_SNAPSHOT、INDEX_ENTRY 是文档概念图节点,不是已核实存在的同名表;
  2. 采购规则案例是建议自建测试夹具,不是仓库真实客户业务;
  3. 当前静态代码支持的功能,不等于具体部署已配置并启用;
  4. 不声称统一精确 Prompt token 预算、无限续流、所有模式自动重连、取消立即停止计费、跨系统 exactly-once 或重建零停机;
  5. 讲故障应使用“当前代码为防止某机制而做了…… / 已有回归测试”,除非另有事故日志。

14、从这个项目能学到什么 ​

如果只记五条:

  1. 完成状态是协议,不是布尔值。 上传、受理、可检索、增强完成、流结束,各是各的。
  2. 旧轮次必须被隔离。 重试、重解析、删除并发时,旧任务不能写新世界。
  3. 分数尺度要显式处理。 归一化、RRF、独立排名、稳定排序,缺一不可。
  4. 正文坐标与语义上下文分离。 检索可以加标题,引用必须回到原文。
  5. 先持久化,再宣布完成。 流式、引用、停止、恢复都依赖这个顺序。

15、检查清单 ​

  • 上传接口的“受理成功”和“处理成功”在客户端分开处理;
  • 文件与数据库记录失败时有补偿和对账;
  • 异步任务有 attempt/轮次隔离;
  • 解析器降级只针对明确的协议错误;
  • 块正文坐标与检索输入分离;
  • 状态收敛有原子计数与条件提升;
  • 检索范围在服务端归一化,权限前置过滤;
  • 混合检索按排名/归一化融合,不直接加原始分;
  • 重排有超时、候选上限和失败回退;
  • 引用只允许本轮注册的句柄;
  • 流式先落库再 complete;
  • 停止与续流由服务端控制面实现;
  • 有回归测试覆盖并发、乱序、取消和部分失败。

下一步:09 评估,看如何证明这些设计真的有效。

评论

正在加载评论…