项目开源地址 https://github.com/anlew07/TraceMind项目架构详细思路讲解https://zread.ai/anlew07/TraceMind一个本地优先、答案可追溯、面向长期学习与技术积累的个人 AI 知识库。TraceMind 将 PDF、DOCX、Markdown、TXT、技术代码资料、历史对话和已经验证的问题解决经验组织为一套能够检索、核验、沉淀、恢复和持续维护的个人知识系统。当前版本v1.1.0​TraceMind Overview本地优先的个人 AI 知识库整体界面。​快速开始TraceMind 本地运行主要包含四部分PostgreSQL保存知识库、文档、Conversation、KnowledgeEntry 等长期业务数据。Redis Celery执行文档解析、Embedding、索引、重建等异步任务。Qdrant保存 Dense 与 BM25 检索索引。Backend Frontend分别提供 FastAPI API 和 Vue 用户界面。正常开发时建议准备3 个终端分别运行 Backend、Celery Worker 和 Frontend。1) 前置条件请先安装GitPython3.12uvPython 依赖与虚拟环境管理Node.js22.18或24.12与 npmDocker Desktop或支持 Docker Compose 的 Docker Engine可以先确认本地环境git --version python --version uv --version node --version npm --version docker --version docker compose version2) 克隆项目git clone https://github.com/anlew07/TraceMind.git cd TraceMind后续命令默认都从项目根目录执行。3) 准备环境变量项目不会把本地 API Key、数据库密码等配置直接写入代码需要先根据示例文件创建本地.env。Windows PowerShellCopy-Item .env.example .env Copy-Item frontend/.env.example frontend/.envmacOS / Linuxcp .env.example .env cp frontend/.env.example frontend/.env打开根目录.env至少配置 Chat Model# OpenAI-compatible API 地址 LLM_BASE_URL ​ ​ # 实际使用的模型名称 LLM_MODEL如果 Provider 需要鉴权再填写LLM_API_KEYTraceMind 使用 OpenAI-compatible ChatModel因此可以接入提供兼容接口的本地或远程模型服务。.env用于保存本地运行配置和凭据不要提交到 Git。Embedding、Qdrant、PostgreSQL、Redis、Chunk Size、Retrieval Top-K 等参数已经在.env.example中提供默认值首次运行通常不需要修改。4) 启动 PostgreSQL、Redis 和 QdrantTraceMind 将基础设施放在 Docker Compose 中运行docker compose up -d postgres redis qdrant检查容器状态docker compose ps三个服务分别负责PostgreSQL └─ 长期业务数据 ​ ​ Redis └─ Celery Broker / Result Backend ​ ​ Qdrant └─ Dense BM25 检索索引确认对应容器处于正常运行状态后再启动 Backend。5) 启动后端进入 Backendcd backend安装并同步锁定版本的 Python 依赖uv sync --frozen其中--frozen表示严格按照当前uv.lock安装依赖避免本地环境自动改变锁文件。初始化或升级 PostgreSQL 数据库结构uv run alembic upgrade head启动 FastAPIuv run uvicorn app.main:app --reload启动成功后访问Backendhttp://localhost:8000Swaggerhttp://localhost:8000/docs--reload仅用于本地开发代码修改后 Backend 会自动重新加载。6) 启动 Celery Worker保持 Backend 终端运行再打开第二个终端。进入cd TraceMind/backend启动 Celery Workeruv run --no-sync celery -A app.worker.celery_app:celery_app worker --loglevelINFOCelery Worker 负责执行不适合阻塞普通 HTTP 请求的耗时任务例如Document Parse → Chunk → Embedding → Qdrant Index KnowledgeEntry Index Consistency Repair Derived State Rebuild因此Backend 可以正常启动并不代表文档索引任务能够执行进行资料导入时需要同时运行 Celery Worker。Windows 本地使用 CPU Embedding 时推荐线程池模式uv run --no-sync celery -A app.worker.celery_app:celery_app worker --loglevelINFO --poolthreads --concurrency2 --prefetch-multiplier1这里--poolthreadsWindows 本地使用线程池--concurrency2同时执行两个 Worker Thread--prefetch-multiplier1减少单个 Worker 预取过多耗时任务。7) 启动前端保持 Backend 和 Celery Worker 继续运行再打开第三个终端cd TraceMind/frontend安装锁定版本的前端依赖npm ci启动 Vite 开发服务器npm run dev访问http://localhost:5173/首次访问会进入 Landing之后进入 Knowledge Base Workspace。此时本地运行结构大致为Terminal 1 └─ FastAPI Backend :8000 Terminal 2 └─ Celery Worker Terminal 3 └─ Vue / Vite Frontend :5173 Docker Compose ├─ PostgreSQL ├─ Redis └─ Qdrant完整开发、容器和验证说明见 开发指南。可选启用本地 Cross-Encoder RerankerReranker不是 TraceMind 运行的必需组件。默认RERANKER_ENABLEDfalse此时检索链路仍然可以正常执行Dense BM25 ↓ RRF ↓ Top-K Evidence启用 Reranker 后则变为Dense BM25 ↓ RRF ↓ Cross-Encoder Reranker ↓ Top-K Evidence如果需要启用在新的终端中进入 Backendcd backend启动本地 Reranker Serveruv run --no-sync uvicorn app.reranker_server:app --host 127.0.0.1 --port 8011 --workers 1确认健康检查http://127.0.0.1:8011/health/ready返回200后将根目录.env中RERANKER_ENABLEDtrue然后重启 Backend。默认模型为Qwen/Qwen3-Reranker-0.6BCPU / CUDA、模型离线缓存、dtype、batch size 与显存边界见 Reranker 指南。项目概览核心能力多格式文档导入、解析与索引。混合检索、重排序、查询改写与范围过滤。RAG 流式回答与可追溯引用。对话持久化、知识沉淀与检索复用。检索调试、知识浏览与数据恢复。运行方式Vue 3 FastAPIPostgreSQL 保存业务数据Redis Celery 执行异步任务Qdrant 提供检索能力。​Knowledge Base Workspace统一进入文档、检索、对话与知识管理。​关键技术亮点文档多版本管理上传时通过 SHA-256 校验去重原文件原子持久化后创建 Document VersionCelery 异步解析执行确定性切分、Embedding 与 Qdrant 入库。内容未变则复用已有版本与已生效索引内容更新则创建新版本解析和索引状态各自独立追踪。双缓冲式索引发布采用 Active / Building Generation 隔离新旧索引新索引完成向量化入库与 Point Count 完整性校验后再切换 Active构建失败自动沿用旧 Generation避免部分写入污染线上召回结果。Dense BM25 双路混合检索Qwen3 Embedding 负责语义召回Qdrant BM25 负责 API 名称、错误信息、代码标识符和专有名词的精确匹配两路联合召回兼顾语义理解与关键词命中。确定性 RRF 排序融合Dense 和 BM25 的候选结果在应用层通过 RRF倒数排名融合统一排序并用稳定键消除同分抖动确保混合检索结果可重复、可测试。Cross-Encoder 二阶段精排先由 DenseBM25 和 RRF 扩大候选覆盖面再用 Qwen3 Cross-Encoder 对 Query 与候选文档重新评分筛选出 Top‑K Evidence在召回率与最终证据相关性之间做到两阶段平衡。Reranker 自动降级Cross‑Encoder 独立部署为微服务若连接失败、超时、OOM 或响应异常自动回退到 Hybrid RRF 结果精排异常不影响基础检索链路。Query 改写与 Scope 限定连续对话中按需将上下文相关问题重写为独立检索 Query同时支持按文档或路径限定召回范围适配追问、定向资料查询和代码检索场景。Evidence‑first 证据链全链路严格遵循“检索→证据→上下文→LLM→引用”顺序真实来源身份始终保留。回答中的引用可追溯到 Document Version、章节、页码、相对路径或代码行实现答案到原始资料的可核验定位。Citation Guard 引用校验模型生成的引用不被直接采信而是与本轮实际进入上下文的 Evidence 进行比对过滤阻止未召回来源被包装成有效引用。LangGraph 显式 RAG 编排Route → Scope → Rewrite → Retrieve → Rerank → Context → Grounded Generation / No-answer → Finalize将完整 RAG 流程拆分为显式节点支持节点级状态管理、异常处理与执行观测。全链路实时可观测记录 Query 改写、检索、重排、上下文构建、LLM 生成及引用校验各阶段的状态、耗时、候选数量、Scope 和降级信息问题出在哪一阶段一目了然。SSE 流式执行链路LangGraph 执行过程实时映射为 Pipeline → Sources → Token → No-answer / Done 等 SSE 事件前端在答案生成过程中即可同步展示检索阶段、证据来源与流式内容。独立检索工作区语义/混合/重排序检索链路可脱离 LLM 单独运行直接展示排名、RRF 分数、重排分数、Scope 和证据无需创建对话即可快速定位召回或重排问题。对话→已验证知识闭环RAG 问答经人工验证后生成结构化 KnowledgeEntry含背景、根因、方案、失败尝试、标签及证据快照重新 Embedding 并入库使解决过的问题持续沉淀并复用。事实数据与派生状态分层PostgreSQL 和原始文件作为唯一事实来源DocumentChunk、Qdrant 索引和任务运行状态均为可重建的派生状态向量库只负责检索不作为知识的唯一真相。数据一致性与灾难恢复链路Archive / Restore → Consistency Audit → Safe Repair → Rebuild Derived State当 Qdrant 索引损坏或丢失时可基于 PostgreSQL 与原始文件重新执行 Parse → Chunk → Embedding → Index 恢复检索状态。目录与架构后端backend/基于 FastAPI核心代码位于backend/app/整体采用 API → Service → Repository / Infrastructure 的分层方式RAG、检索、解析和异步任务保持独立模块。app/api/接口层聚合 Knowledge Base、Document、Conversation、Retrieval、RAG、Knowledge、Archive / Restore 等 HTTP 与 SSE 接口主要负责参数校验、响应转换、流式事件输出与安全错误映射。app/rag/RAG 执行链路基于 LangGraph 组织 Route → Scope → Rewrite → Retrieve → Rerank → Context → Generate / No-answer → Finalize。graph.py / nodes.py / state.py分别负责工作流编排、节点实现与单次执行状态context.py / citations.py负责上下文构建和引用约束。app/services/核心业务编排承载文档版本、对话、KnowledgeEntry、索引发布、归档恢复、一致性检查和数据重建等核心流程。负责事务边界、跨存储补偿和任务调度避免业务逻辑直接堆积在 API 层。app/parsing/文档解析与切分支持 PDF、DOCX、Markdown、TXT 与常见代码文件并保留页码、章节或代码行等来源信息。chunker.py负责确定性 Chunking使相同输入能够稳定生成相同顺序和内容的 Chunk。app/indexing/向量索引与混合检索封装 Qdrant Collection、Dense BM25 双路召回、确定性 RRF、Payload Filter 等底层索引与检索能力。Generation 的构建、校验与 Active 切换由 Service 层负责业务编排app/embedding/与app/reranker/分别提供 Embedding 与可选 Cross-Encoder 精排。app/tasks/app/worker/异步任务基于 Celery Redis 执行 Parse、Document Index、Knowledge Index、Repair 和 Rebuild避免耗时任务阻塞 FastAPI 请求。app/storage/原始文件与数据恢复管理 Original Files、Trash、Archive / Restore并负责原子写入、安全路径和恢复过程中的文件处理。models/、repositories/、schemas/分别负责 SQLAlchemy 数据模型、PostgreSQL 数据访问和 Pydantic 接口模型使数据库、业务逻辑和 HTTP 数据结构保持分离。integrations/、db/、core/、llm/统一封装 PostgreSQL、Redis、Qdrant、配置、日志和 ChatModel 等基础设施依赖。前端frontend/基于 Vue 3 TypeScript Vite Element Plus 构建围绕 Knowledge Base Workspace 组织文档、检索、对话、知识沉淀与数据恢复页面。RAG 流式交互与执行追踪ConversationView.vue承载 RAG 对话、Evidence 引用和 Execution Trace实时展示 Query Rewrite、Retrieval、Rerank、Evidence、Generation 等执行阶段。services/rag.ts消费后端 SSE 流将 Pipeline、Sources、Token、No-answer、Done 等事件实时映射到前端状态。检索结果可视化SemanticSearchPanel.vue独立展示 Semantic / Hybrid / Reranked 检索结果可查看 Rank、RRF Score、Reranker Score 与对应 Evidence。EvidenceSourceList.vue展示回答引用的 Evidence以及文档、页码、文件路径或代码位置等来源定位信息。文档生命周期管理DocumentView.vue配合DocumentVersionDialog.vue、DocumentChunkDialog.vue展示文档版本、解析 / 索引状态以及实际 Chunk 内容。知识与数据维护Knowledge / Knowledge Map 页面负责 Verified Knowledge 浏览与关系展示Data Management 页面统一提供 Archive / Restore、Audit / Repair 与 Rebuild 操作。运行时数据data/uploads/保存用户上传的原始文档运行时自动创建不纳入 Git 版本管理。PostgreSQL、Redis、Qdrant 数据通过 Docker Volume 持久化。基础设施PostgreSQL业务数据与知识记录。QdrantDense BM25 检索索引。Redis Celery异步任务与任务状态。compose.yaml统一编排本地依赖服务。核心流程1) 项目全链路端到端用户创建或进入 Knowledge Base上传 PDF、DOCX、Markdown、TXT 或代码文件。FastAPI 保存原始文件并创建 Document / DocumentVersion随后通过 Celery 异步执行文档解析、Chunk 切分和索引构建。文档完成索引后可以在 Retrieval Workspace 中直接检查 Dense / Hybrid / Reranked 检索结果也可以进入 Conversation 发起 RAG 问答。前端调用POST /api/v1/knowledge-bases/{knowledge_base_id}/rag/streamFastAPI 在backend/app/api/routes/rag.py中启动 LangGraph 流式执行。LangGraph 依次完成检索范围解析、Query Rewrite、Dense BM25 混合召回、RRF 融合和可选 Cross-Encoder Rerank得到最终 Evidence。Evidence 被组织为受控 ContextLLM 基于真实来源流式生成回答pipeline、sources、token、no_answer、done等 SSE 事件同步推送到前端。对已经解决的问题用户可以进一步整理为 KnowledgeEntry验证并完成索引后它会与原始 Document 一起参与后续 Retrieval形成“检索 → 解答 → 验证 → 沉淀 → 再检索”的知识闭环。2) RAG 全链路重点请求路由route明确的寒暄类问题由本地规则直接走 Direct Generation不查询知识库。其余问题进入完整 RAG 分支继续执行 Scope、Rewrite 和 Retrieval。Direct 分支不会伪造知识库来源或 Citation。检索范围解析resolve_scope支持通过 Document 或文件路径限定检索范围。指定 Scope 时只查询对应文档未指定时从当前 Knowledge Base 中有效的 Document 与 Verified KnowledgeEntry 统一召回。Scope 只限制候选来源不改变后续混合检索流程。上下文查询改写rewrite没有 Conversation History 时直接使用当前 Query。存在上下文依赖时由 ChatModel 判断keep / rewrite将“这个呢”“上一种方法呢”等追问改写成可独立用于检索的问题。Rewrite 只用于 Retrieval不修改用户原始问题。模型超时、调用失败或返回无效结果时自动退回原 Query不中断后续链路。混合检索retrieve使用 Qwen3 Embedding 对 Query 进行一次向量化。Qdrant 同时执行 Dense 语义召回与 BM25 关键词召回。Dense 负责语义相近内容BM25 补充 API 名称、异常信息、代码标识符、配置项和专有名词等精确匹配场景。两路候选在应用层通过确定性 RRFReciprocal Rank Fusion倒数排名融合统一排序得到第一阶段候选结果。同时记录 Dense / Sparse 候选数量以及 Embedding、Qdrant、Fusion 等检索耗时。二阶段精排rerank启用 Reranker 时将 RRF 候选交给 Qwen3 Cross-Encoder重新计算 Query 与候选正文之间的相关性并截取最终 Top-K。Reranker 未启用时直接使用 Hybrid 结果。连接失败、超时、OOM 或服务异常时自动回退 Hybrid RRF不让可选精排能力阻断基础 RAG。Evidence 构建与答案生成prepare_context/generate_grounded最终检索结果转换为带[S1] / [S2] / ...编号的 Evidence并在上下文长度限制内组织为 Context。Evidence 保留文档版本、章节、页码、文件路径或代码行等真实来源信息。没有有效 Evidence 时进入no_answer直接返回资料不足不让模型脱离知识库强行生成。有 Evidence 时流式生成回答StreamingCitationGuard只允许模型引用本轮真实提供的 Source ID过滤无效 Citation。可观测追踪LangGraph 将执行过程映射为routing → query_rewrite → retrieval → rerank → evidence → generation。各阶段记录started / completed / skipped / fallback / failed状态。Execution Trace 同时保留检索模式、候选数量、Scope、Query Rewrite、Reranker Fallback 和各阶段耗时用于定位问题发生在召回、排序、Evidence 还是最终生成。​Conversation EvidenceRAG 对话、执行过程与可追溯 Evidence。​3) 文档入库链路前端上传文件到POST /api/v1/knowledge-bases/{knowledge_base_id}/documents后端校验文件名、扩展名和大小并在流式写入过程中计算 SHA-256。DocumentService.import_document根据规范化路径识别同一逻辑 Document内容 Hash 未变化 → 返回unchanged不重复创建版本。内容发生变化 → 创建新的 DocumentVersion并保留历史版本。DocumentParsingService.parse_version根据文件类型调用对应 Parser提取正文以及页码、章节或代码行号等来源信息。DeterministicChunker执行单层确定性切分相同输入和配置会稳定产生相同顺序、正文和 Hash 的 Chunk当前默认1800 chars 200 overlap。Parse 成功后自动进入 Index TaskQwen3 Embedding 生成 Dense Vector同时构造 BM25 检索文本和 Citation Payload 写入 Qdrant。新索引使用独立 Generation 构建全部 Point 写入并通过完整性校验后才切换为 Active之后新文档即可正式参与 Retrieval。​Document Library查看文档、版本以及 Parse / Index 状态。​4) Generation 索引发布机制隔离构建每次索引任务生成新的 Generation旧 Active Generation 在新索引构建期间继续提供检索新旧索引不会在构建过程中混用。校验后切换只有新 Generation 完成全部 Point 写入、数量校验且仍对应最新 DocumentVersion 后才切换为 Active构建失败时继续使用旧索引。有效索引约束Retrieval 只查询 PostgreSQL 声明的 Active Generation因此失败任务或 Qdrant 中残留的孤立 Point 不会自动进入正式 Evidence。5) KnowledgeEntry 知识沉淀链路用户可以从一条已经完成的 RAG 回答创建 KnowledgeEntry。KnowledgeEntry 将一次问答整理为 Question、Background、Root Cause、Solution、Failed Attempts、Tags 等结构化知识。创建时同时保存原始 Question / Answer、实际 Citation Evidence 与 Generation Metadata Snapshot使沉淀后的知识不再完全依赖原 Conversation。只有verified的 KnowledgeEntry 才进入索引队列未验证内容仅作为草稿保存不参与正式 Retrieval。索引完成后Verified KnowledgeEntry 与 Document 一起进入后续混合检索使已经解决过的问题能够被再次召回和复用。​Knowledge Storage将已验证问题整理为可复用 KnowledgeEntry。​​Knowledge Map浏览知识条目之间的关系与关联。​6) 数据恢复链路Archive / Restore归档 Knowledge Base、Document / DocumentVersion、Original Files、Conversation、KnowledgeEntry 和必要快照Chunk、Vector 和模型缓存不作为核心事实数据保存。Consistency Audit只读检查 PostgreSQL、Original Files 与 Qdrant Generation / Payload 之间是否存在缺失或状态不一致。Safe Repair只修复允许自动恢复的派生状态不修改用户正文和知识内容。Rebuild基于 PostgreSQL Original Files 重新执行 Parse → Chunk → Embedding → IndexDocument 与 Verified KnowledgeEntry 都可以重新建立检索索引。因此即使 Qdrant Collection 损坏或丢失只要长期业务数据和原始文件仍然完整Retrieval State 就可以重新构建。​Data RecoveryArchive / Restore、Audit / Repair 与 Derived State Rebuild。​技术栈后端Python 3.12、FastAPI、SQLAlchemy 2、Alembic。前端Vue 3、TypeScript、Vite、Element Plus、Cytoscape.js。长期数据PostgreSQL、本地 Original Files。异步任务Redis、Celery。检索Qdrant、Qwen3 Embedding、BM25、RRF、Cross-Encoder Reranker。RAGLangChain、LangGraph、OpenAI-compatible ChatModel、SSE、Citation Guard。部署Docker Compose 本地前端开发服务。运行、配置、测试与数据维护说明见 开发指南产品边界见 当前产品。RAG 与检索 — 技术细节1. LangGraph Custom Stream 与 SSE 实时执行流TraceMind 不等待整个 RAG 流程结束后一次性返回结果而是把 LangGraph 的执行阶段、Evidence 和 LLM Token 统一映射为 SSEServer-Sent Events服务端推送事件流。后端通过 LangGraphstream_modecustom执行工作流各节点按阶段输出不同类型的事件pipelineQuery Rewrite、Retrieval、Rerank、Evidence、Generation 等执行阶段和状态。sources本轮真正进入 Context 的 Evidence。tokenLLM 流式生成的回答片段。no_answer没有足够 Evidence 时的终止结果。done本轮检索模式、候选数量、耗时、Citation 等最终元数据。FastAPI 在backend/app/api/routes/rag.py中将这些事件转换为text/event-stream返回前端并在流结束、失败或客户端取消时完成 Conversation 状态收口。前端frontend/src/services/rag.ts使用fetch ReadableStream eventsource-parser解析 POST SSE再把不同事件分发给对应 Handlerif (event.event pipeline) handlers.onPipeline(...) else if (event.event sources) handlers.onSources(...) else if (event.event token) handlers.onToken(...) else if (event.event no_answer) handlers.onNoAnswer(...) else if (event.event done) handlers.onDone(...)请求取消由AbortController负责因此前端既可以实时展示 RAG 执行状态也可以在同一条 Assistant Message 中持续追加最终回答而不需要额外轮询后端任务状态。2. Qdrant Hybrid Search 与 Deterministic RRFTraceMind 的第一阶段检索同时执行 Dense 与 BM25 两条召回链路Dense Path使用 Qwen3 Embedding 将 Query 转换为 Dense VectorQdrant 通过 Cosine Similarity 执行语义检索。BM25 PathChunk 写入索引时同时构造 Sparse TextQdrant 使用 Sparse Vector IDF 完成关键词召回。统一过滤两路检索使用相同的 Knowledge Base、Document、Generation、Language 等 Payload Filter保证参与融合的候选来自同一检索范围。backend/app/indexing/qdrant.py通过query_batch_points一次发起 Dense / Sparse 两个 QueryRequest再在应用层执行确定性 RRFReciprocal Rank Fusion倒数排名融合。RRF 不直接比较两路原始 Score而是按各自排名计算融合分数RRF Score Σ 1 / (k rank)当前实现使用k2并使用由 Relative Path、Line、Chunk Index、Content Hash 等组成的稳定排序键处理同分结果。这样可以避免 Dense Score 与 BM25 Score 量纲不同导致的权重调参问题同时保证相同输入下的融合顺序稳定可复现便于 Retrieval Regression 和问题定位。3. 前端 RAG Execution Trace 状态映射TraceMind 前端不会展示模型私有思维链而是把后端返回的 RAG Pipeline Event 映射为可观测的 Execution Trace。frontend/src/views/ConversationView.vue维护以下主要阶段Query RewriteRetrievalRerankEvidenceGeneration每个阶段根据后端pipelineEvent 映射为pending started → running completed → complete skipped fallback failed实时执行时pipeline更新当前阶段状态sources写入本轮 Evidencetoken持续追加到同一个 Assistant Messagedone保存最终 Generation Metadataerror / cancel会将正在执行的阶段收口为失败或取消状态。历史消息重新打开时前端会根据已经持久化的 Generation Metadata 还原 Query Rewrite、Retrieval、Rerank、Evidence 和 Generation 的执行结果。因此 Execution Trace 展示的是“系统执行到了哪里、使用了什么检索模式、是否发生降级”而不是模型内部推理过程。4. Generation 双缓冲式索引发布文档更新时TraceMind 不直接删除当前索引再重新写入而是为每次 Index Attempt 创建新的generation UUID。​​新 Generation 在后台独立完成 Embedding 和 Qdrant Upsert期间旧 Active Generation 仍然可以正常参与 Retrieval。只有同时满足以下条件新 Generation 才会切换为 Active当前 Version 已完成 Parse并存在有效 Chunk新 Generation 的 Point 已全部写入 QdrantPoint Count 与当前 Chunk Count 一致当前 Index Attempt 仍然有效对应 DocumentVersion 仍然是当前最新版本。如果新索引构建失败或任务已经过期则不会切换 Active Generation旧索引继续提供检索。Retrieval 只查询 PostgreSQL 中声明为 Active 的 Generation因此失败任务、过期任务或 Qdrant 中残留的孤立 Point 不会自动进入正式 Evidence。这种设计避免了文档重新索引期间出现“旧索引已删除、新索引还未构建完成”的不可检索窗口同时也避免半完成索引污染当前检索结果。检索评测TraceMind 使用固定 Retrieval Benchmark 对 Dense、BM25、Hybrid、Reranker、Top-K 和检索阈值进行回归验证并使用独立 Holdout 与 Project Acceptance Set 检查实验结论是否能够迁移到更接近真实工程的查询场景。Retrieval Evaluation v1.1Synthetic dev 共 32 条 Query其中 30 条可回答、2 条负样本RetrievalHit1Hit5Recall10MRR10Dense19/3029/3096.67%80.00%BM2520/3029/3096.67%79.72%Hybrid23/3030/30100%86.39%Hybrid Reranker26/3030/30100%91.94%固定评测结果支持当前默认检索配置Dense BM25 ↓ Application-side Deterministic RRF ↓ Top-K 5当前主要结论Hybrid RetrievalDense 与 BM25 各自存在独有的 Top-5 漏召回Hybrid 在 dev 上达到30/30 Hit5因此继续保留双路召回与 RRF 融合。Reranker在 dev 上改善了部分 Top Rank但收益没有在 Holdout 上稳定复现同时增加明显的尾延迟因此当前仍默认关闭。Top-KTopK3出现额外漏召回TopK10没有进一步质量收益但平均候选内容规模从约770chars 增长到约1359chars因此保持TopK5。Semantic Threshold降低至0.40/0.45主要增加候选高至0.55/0.60会损失部分 Top-1 结果因此保持0.50。Prefetch当前20/20下 Hybrid devRecall10100%暂无数据支持继续扩大候选池。当前默认 Retrieval 配置TopK 5 Semantic threshold 0.50 Dense prefetch 20 Sparse prefetch 20 Reranker disabled除固定 synthetic benchmark 外v1.1 还使用 12 条基于 TraceMind 真实代码与文档构造的 Project Acceptance Query 进行独立验证当前 HybridHit5 8/12。实现细节、精确代码定位和相似内容干扰仍是后续 Retrieval 优化的重点因此 synthetic benchmark 的高分不被视为真实知识库质量上限。评测数据主要用于同一数据集、索引配置和运行环境下的 Retrieval Regression 与工程选型比较。当前数据集规模有限不代表真实知识库上的通用准确率本地延迟数据也不作为生产环境 SLA。完整实验配置、Dataset、Holdout、Reranker / Top-K / Threshold 对比、Failure Analysis 和 Query Rewrite 结果见Retrieval Evaluation 说明Retrieval Evaluation v1.1 完整结果文档文档入口当前产品开发指南UI DesignKnowledge DesignRetrieval Evaluationv1.1.0 Release Notesv1.0.0 Release Notes