文档上传到问答全链路:WeKnora 源码拆解
前面几篇讲的是通用原理。这一篇换一个视角:一个真实系统如何把这些环节串起来,以及哪些地方最容易出错。
以下拆解来自对 WeKnora 公开源码与测试的静态阅读,不依赖本地环境。文中把“源码已实现”和“文档中的目标设计”分开写:前者可以在代码与测试中核对,后者只是规划,不把它当成现状。
1、先看两张链路图
1.1 摄取链路
浏览器上传
→ 原文件/资源引用
→ knowledge 记录(pending + disabled)
→ document:process 异步任务
→ 解析(Go Reader / Python DocReader)
→ 规范化 + 来源位置索引
→ Go 分块
→ 保存 chunks
→ 向量/关键词索引
→ 图片增强 fan-in
→ 后处理增强 fan-in
→ 状态收敛(completed / failed)1.2 问答链路
问题 + 检索范围
→ 服务端鉴权 / 目标归一化(SearchTargets)
→ 保存用户消息
→ 创建助手占位消息
→ 查询理解(可选改写)
→ 多路召回(向量 / 关键词 / 标签)
→ 融合(RRF)
→ 重排(rerank + 规则)
→ 证据合并
→ TopK 截断
→ 组装 Prompt(模型上下文句柄)
→ 模型流式生成
→ 事件总线 / StreamManager
→ SSE
→ 消息与引用持久化
→ 对外 complete两条链路通过持久化的知识记录、块和索引衔接,不存在覆盖整条链路的共同事务。这是理解后面所有一致性问题的基础。
2、四个“完成”信号,含义完全不同
| 信号 | 含义 | 不代表 |
|---|---|---|
| 浏览器上传 100% | 文件传输完成 | 服务端已收到、已登记 |
上传接口 success=true | 请求被受理 | 文档已解析、可检索 |
文档 completed | 处理生命周期收敛 | 每条增强都成功、答案正确 |
流 complete | 本轮输出收尾 | 内容一定正确、消息一定已落库 |
把它们混为一谈,是很多“显示完成了但搜不到”“回答完了但刷新空白”问题的根源。
3、上传:浏览器队列与服务器队列不是一回事
3.1 服务端入口
永久知识库文件上传走:
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:CreateKnowledgeFromFileinternal/application/service/knowledge_create.go:createKnowledgeFromFile、markKnowledgeEnqueueFailedinternal/application/service/knowledge_util.go:calculateFileHash
3.2 创建顺序
校验类型 / 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、dedupKeyfrontend/src/stores/uploadTasksCore.ts:并发与轮询参数frontend/src/stores/uploadQueue.test.ts:迟到回调隔离测试
这组设计的核心思想:服务器事实优先于浏览器状态。 浏览器可以取消显示,但不能假装服务器没收到。
4、摄取:Go 主编排,Python DocReader 是其中一段
ProcessDocument 的职责:
- 恢复租户和知识记录;
- 检查任务是否旧轮次、已取消、删除中、不应重复运行;
- 确认源文件身份;
- 选择解析器;
- 解析 → 规范化 → 分块 → 索引;
- 推进状态。
源码: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、readUnarydocreader/main.py:Read、ReadStream
4.2 两个容易误解的点
ReadStream主要改善解析结果/图片的传递;当前convert仍会io.ReadAll(fileReader)把源文件读成字节,不是任意大文件的端到端零缓冲上传。- DocReader 默认调用超时 30 分钟,实际还受父任务 deadline 限制。解析调用超时与整个文档任务超时是两层约束。
解析输出保留 Markdown、元数据、图片与 source_blocks;规范化后建立来源位置索引,把块范围映射回页码、文本或图片位置。这是后续引用能定位回原文的基础。
5、切分与索引:正文和检索输入分开
5.1 切分策略
当前策略入口支持 legacy、heading、heuristic、recursive、auto,是否启用由配置决定。不能说“所有文档都会自动使用某一种高级策略”。
最值得学习的不变量:
Content == 原文 [Start, End) 的精确切片
位置单位是 rune
End - Start == 正文 rune 数标题层级 breadcrumb 单独保存在 ContextHeader,用于检索输入,不污染正文坐标。
源码:
internal/infrastructure/chunker/splitter.go:Chunk、SplitterConfig、DefaultConfiginternal/infrastructure/chunker/strategy.go:Split、SplitParentChild、NormalizeSplitterConfiginternal/infrastructure/chunker/tokens.go:ApproxTokenCountinternal/types/chunk.go:Chunk.EmbeddingContent、ContextHeader、SourceLocators
5.2 检索输入
基本由三层组成:
文档标题 + 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 等任务名额。下面只选两项看计数变化:
FinalizeSubtask 在同一 SQL 事务中 减计数 + 条件提升;只有 finalizing AND pending_subtasks_count=0 才提升。诊断回读不决定提升,中途重试不释放名额。它不是跨存储事务,也不保证全链路 exactly-once。自动标签等旁路和知识库级 Wiki reduce 不属于这组计数。
源码:
internal/application/service/knowledge_post_process.go:KnowledgePostProcessService.Handleinternal/application/repository/knowledge.go:SetFinalizing、FinalizeSubtask、finalizeSubtask、CompleteProcessingWithoutSubtasks
对应测试:
internal/application/repository/knowledge_finalize_test.goTestFinalizeSubtask_Concurrent_ExactlyOnePromoteTestFinalizeSubtask_FailedPromoteRollsBackDecrementTestUpdateKnowledge_DoesNotClobberPendingCounter
6.3 任务执行器
普通模式使用 Redis + Asynq;Lite 使用进程内 goroutine。
当前 Lite 已实现延迟、重试、timeout/deadline、TaskID 和最终失败钩子,不是“没有重试”;但它不具有 Redis 队列同等的进程外持久性与任务巡检/取消能力。
源码:internal/router/sync_task.go 的 SyncTaskExecutor.Enqueue。
7、提问:范围归一化比想象中复杂
7.1 入口与消息
普通问答路径:
POST /api/v1/knowledge-chat/{session_id}服务端会:
- 校验会话、资源、模型权限及当前轮次占用;
- 先保存用户消息;
- 再保存
is_completed=false的助手占位; - 占位创建失败时,有回滚用户消息的路径。
X-Request-ID 是日志/事件关联标识,不自动等于生成 POST 的幂等键。
源码:
internal/handler/session/qa.go:parseQARequest、persistTurnMessages、executeQAinternal/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 管线的实际阶段:
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、HybridSearchinternal/application/service/chat_pipeline/search.go:searchByTargets、searchSingleTarget
对应测试:
internal/application/service/chat_pipeline/search_error_test.goTestSearchEmbeddingFailureIsNotReportedAsNoResultsTestSearchEmbeddingFailureDegradesToKeywordSearchTestSearchEmbeddingFailureOnVectorOnlyTargetPreservesRootCauseTestSearchKeepsSuccessfulResultsWhenAnotherTargetFails
8.3 融合:不是把 BM25 和余弦相加
当前实现分三种:
vector-only:保留原始检索分数;keyword-only:对无界BM25按各自列表最高分归一化;已经落在[0,1]的分数不随意重标定;hybrid:加权RRF,再除以理论最大值:
(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.goTestFuseOrDeduplicate_KeywordOnlyRescalesUnboundedBM25TestFuseOrDeduplicate_HybridTopOfBothScoresOneTestFuseOrDeduplicate_HybridRanksEachListOnItsOwnTestFuseOrDeduplicate_HybridIgnoresArrivalOrder
8.4 重排
统一入口 reranking.Rerank 包含:
- 候选上限;
- passage 长度适配;
- 阈值过滤;
- 综合分;
MMR选取;- 图片保留规则。
当前综合分:
0.6 * modelScore + 0.3 * baseScore + 0.1 * sourceWeight随后可施加 FAQ boost。这是当前实现,不是通用推荐公式。FAQ 高置信判断取 boost 前的分数,防止人为权重制造“高置信”。
失败路径:
- 未配模型 → 回退召回结果;
- 模型加载失败 → 回退;
- 重排
API失败 → 回退; - 成功重排但阈值过滤为空 → 真正的无结果。
源码:internal/reranking/rerank.go 的 Rerank、CompositeScore、PreBoostScore。
8.5 证据合并
PluginMerge 依次处理:
去重
→ 历史引用补入
→ 父块还原
→ 同来源连续/重叠片段合并
→ FAQ 回答恢复
→ 邻居扩展
→ 再次去重注意:
- 不能对任意看起来相似的表格行做文本去重;
- 编辑/改写后的内容不能继续盲信旧坐标;
- 引用应定位实际命中的来源。
源码:
internal/application/service/chat_pipeline/merge.go:PluginMerge.OnEvent、resolveParentChunksinternal/application/service/chat_pipeline/filter_top_k.go:sortSearchResultsDeterministically、collapseParentSlots
对应测试:
internal/infrastructure/chunker/parent_child_offsets_test.gointernal/application/service/chat_pipeline/merge_position_path_test.goTestGroupAndMerge_TrustedAdjacentRepeatedTextKeepsEveryRowTestGroupAndMerge_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.gointernal/application/service/chat_pipeline/references.go:prepareMessagesWithModelContextinternal/modelcontext/registry.go:Registry、EncodeMessages、RegisterSearchResults、StreamDecoderinternal/modelcontext/citations.go:citationTag、ExpandText、citationStreamExpander
对应测试:
internal/modelcontext/sources_test.gointernal/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 主时序
创建消息
→ agent_query 关联助手 ID
→ 发出 references
→ answer 增量
→ 内部完成整理
→ 数据库保存成功
→ 对外 complete保存失败会发 error.stage=message_persistence,不发布成功完成承诺。
错误路径可以保存部分答案及错误文字,再 complete 收尾。因此 complete 和 is_completed 都不等于业务成功。
源码:
internal/handler/session/qa.go:completeQuickAnswerTurn、completeStreamAssistantMessage、completeAssistantMessageinternal/handler/session/helpers.go:buildStreamResponse、createAgentQueryEventinternal/handler/session/agent_stream_handler.go:handleComplete、publishCompletion
对应测试:
internal/handler/session/image_completion_test.goTestSharedImageCompletionWaitsForPersistedReferencesTestQuickAnswerCompletionPersistsAfterGenerationCancellation
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 停止
前端中止本地流并推进 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 恢复
刷新后:
GET /api/v1/messages/{session_id}/load?limit=20;- 发现未完成的助手消息;
GET /api/v1/sessions/continue-stream/{session_id}?message_id=...;- 服务端从事件
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前端、GoHandler/Service/Repository、Gochunker/索引编排、PythonDocReader 解析服务; 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 阅读时需要保留的限制
REFERENCE_SNAPSHOT、INDEX_ENTRY是文档概念图节点,不是已核实存在的同名表;- 采购规则案例是建议自建测试夹具,不是仓库真实客户业务;
- 当前静态代码支持的功能,不等于具体部署已配置并启用;
- 不声称统一精确
Prompttoken预算、无限续流、所有模式自动重连、取消立即停止计费、跨系统 exactly-once 或重建零停机; - 讲故障应使用“当前代码为防止某机制而做了…… / 已有回归测试”,除非另有事故日志。
14、从这个项目能学到什么
如果只记五条:
- 完成状态是协议,不是布尔值。 上传、受理、可检索、增强完成、流结束,各是各的。
- 旧轮次必须被隔离。 重试、重解析、删除并发时,旧任务不能写新世界。
- 分数尺度要显式处理。 归一化、
RRF、独立排名、稳定排序,缺一不可。 - 正文坐标与语义上下文分离。 检索可以加标题,引用必须回到原文。
- 先持久化,再宣布完成。 流式、引用、停止、恢复都依赖这个顺序。
15、检查清单
- 上传接口的“受理成功”和“处理成功”在客户端分开处理;
- 文件与数据库记录失败时有补偿和对账;
- 异步任务有
attempt/轮次隔离; - 解析器降级只针对明确的协议错误;
- 块正文坐标与检索输入分离;
- 状态收敛有原子计数与条件提升;
- 检索范围在服务端归一化,权限前置过滤;
- 混合检索按排名/归一化融合,不直接加原始分;
- 重排有超时、候选上限和失败回退;
- 引用只允许本轮注册的句柄;
- 流式先落库再
complete; - 停止与续流由服务端控制面实现;
- 有回归测试覆盖并发、乱序、取消和部分失败。
下一步:09 评估,看如何证明这些设计真的有效。
评论
正在加载评论…