18 KiB
18 KiB
项目进度
当前阶段:Retrieval Demo 闭环完成
已完成:DEMO-001~DEMO-010、ARCH-001~ARCH-006 进行中:无 阻塞:无
下一任务:无。docs/demo/DEMO_SCOPE.md 当前批准的必做任务已经完成;可选 DEMO-011~013
或 V1 backlog 需在明确选定新 Task 后再开始。
Provider 架构迁移按 ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → ARCH-005 → ARCH-006
执行并已完成。DEMO-010 在迁移闭环验收后实施,未扩大为完整 V1 Admin Console。
任务记录
DEMO-001
- 建立 Python 3.12/uv 工具链与依赖锁文件,新增 FastAPI 应用、类型化配置、 健康检查、OpenAPI 地址和可执行的 Make 命令。
- 新增可重复执行的单元测试、集成测试及 Evaluation 种子数据校验。
- 已验证格式、Lint、严格类型检查、测试、依赖锁、API 启动、健康检查响应及 版本化 OpenAPI 输出。
DEMO-002
- 新增 canonical Document 元数据、简化的处理状态、SQLAlchemy 数据库/Session 工厂,以及首个只向前执行的 Alembic 迁移。
- 新增与 Provider 无关的 ObjectStorage 接口和本地适配器,支持禁止覆盖、拒绝 不安全路径并清理写入中断产生的半文件。
- 新增模型、数据库、存储、迁移及 Schema Drift 测试;无需连接生产数据库即可 验证 PostgreSQL 方言的迁移 SQL。
DEMO-003
- 新增 PDF、DOCX、TXT、MD 单文件上传应用服务,完成文件名、扩展名、媒体类型、 空文件和流式大小限制校验。
- 上传使用 UUID 隔离的不可覆盖 storage key,并将原始文件与
uploaded状态的 Document 元数据关联保存。 - 数据库写入失败时自动回滚并删除已保存文件;新增四类文件、拒绝规则、大小限制 和失败补偿集成测试。
- Parser 触发与公开上传 REST API 分别留在 DEMO-004 和 DEMO-009,不在本任务 提前实现。
DEMO-004
- 新增统一的
ParsedDocument/ParsedBlock领域模型和 Parser Provider 接口, 使用 PyMuPDF、python-docx 及轻量文本解析器支持 PDF、DOCX、UTF-8 TXT、Markdown。 - PDF 保留一基页码,DOCX/Markdown 保留基础标题层级;基础 Cleaner 统一处理多余 空白、空行、异常换行和空块。
- 新增上传后同步触发解析的应用层编排,将版本化解析 JSON 作为可重建派生文件保存,
并通过数据库迁移增加
parsed_storage_key追踪结果;原始文件保持不可变。 - 解析完成后文档保持
processing,等待 DEMO-005/006 完成后续流水线;解析失败记录failed和有界错误信息,派生结果写库失败时执行文件补偿。 - 新增四类格式、页码/章节、清洗、解析持久化、禁止覆盖和失败状态测试。公开 REST API 仍按计划留在 DEMO-009。
DEMO-005
- 新增可注入
TokenCounter的structure_v1Chunk 策略,默认使用 450 tokens 上限和 75 tokens overlap;标题或章节变化形成硬边界,同章节段落优先组合,超长内容按 token 窗口切分。 - 默认轻量计数器按 CJK 字符、标点和保守 ASCII 子词估算 token,避免引入模型运行时; 精确模型 tokenizer 可通过既有接口注入,留待 DEMO-006 与 bge-large-zh 联调。
- 新增 canonical Chunk 元数据与只向前迁移,原子保存确定性
chunk_id、文档/文件、 一基页码范围、章节路径、顺序、token 数和策略版本;禁止静默覆盖同策略结果。 - 新增上传 → 解析/清洗 → Chunk 的同步流水线编排。Chunk 完成后仍保持
processing, 等待 DEMO-006 Embedding/Mochow;失败时不产生半套 Chunk,并保留原始文件。 - 新增完全合成的 Markdown 测试文档和 Golden Dataset Chunk 回归,覆盖章节追踪、 token 上限、overlap、页码范围、迁移、持久化、重复执行和失败状态。
DEMO-006
- 新增与厂商无关的
EmbeddingProvider/VectorStore契约及确定性 Fake,业务编排 不依赖 Mochow SDK 数据结构。 - 新增千帆 v2
bge-large-zhAdapter,使用 Bearer API Key,支持最多 16 条批量请求, Chunk 同时限制 450 tokens/2000 字符,并严格校验响应顺序、1024 维度和有限数值; 凭证使用SecretStr, 不进入错误消息或提交记录。 - 新增官方
pymochowAdapter,支持分批 Upsert 和按document_id + index_profile_id删除;Mochow 只保存向量与检索元数据,PostgreSQL 继续保存 canonical Chunk 和索引状态。 - 新增版本化
IndexProfile与chunk_index_states向前迁移,防止模型/Chunk 策略原地 覆盖;所有 Chunk 成功入库后文档才进入ready。 - 新增上传 → 解析/清洗 → Chunk → Embedding → Mochow Upsert 同步编排。Mochow 批次
或 canonical 状态写入失败时按文档/profile 清理可能的半批索引并记录
failed。 - 新增 Qianfan、Mochow 映射、配置脱敏、索引状态、失败补偿和 Golden Dataset 全链路
回归测试。真实凭证/网络集成未在默认测试中执行;专用 Mochow 表需按
docs/development/MOCHOW_SETUP.md预创建。
DEMO-007
- 新增
DenseSearchRequest/DenseSearchCandidate与DenseRetrievalService,完成 Query 清洗、同模型 Embedding、版本化index_profile_id过滤和默认 Top20 候选召回; 此阶段不加入 Reranker、最终 Source Result 或 REST API。 FakeVectorStore新增离线精确余弦检索,先按 profile 过滤再排序,并使用稳定的 UUID tie-break,支持无网络的单元/集成/Evaluation 回归。MochowVectorStore新增官方VectorTopkSearchRequest调用,固定检索embedding字段, 下推 profile 标量过滤,支持可配置 HNSWef,严格校验响应字段、UUID、有限分数和 Top-N 数量,异常不泄露 SDK 请求或凭证。- 新增 Golden Dataset Dense Retrieval 回归,完整覆盖上传 → 解析/清洗 → Chunk → Embedding/入库 → Query Embedding → Dense Top20,确认两个合成 Query 均召回预期文件和 章节。
- 默认自动化测试不连接真实千帆/Mochow;真实环境仍需按
docs/development/MOCHOW_SETUP.md注入凭证并验证网络、表 Schema 与索引状态。
DEMO-008
- 新增与厂商无关的
RerankerProvider/RerankResult契约及确定性 Fake,使用原始 candidate index 映射精排结果,业务服务不依赖千帆响应结构。 - 新增千帆 v2 Reranker Adapter(初始为
qwen3-reranker-0.6b,ARCH-004 已迁移至bce-reranker-base),调用/v2/rerank,严格限制 Query、 documents 和 Top-N,校验响应数量、唯一索引、回显文本、有限分数与降序关系;错误不会 回显请求内容或凭证。 - 新增
SearchService,完成 Dense Top20 → Reranker → Top5。Reranker 选中候选后按chunk_id回查 PostgreSQL canonical Chunk,再生成包含 document、filename、page、 section、chunk、content、Dense score 和 rerank score 的最终 Source Result。 - Source Enrichment 对缺失 Chunk、document_id 不一致和 stale vector content 采用失败 关闭,防止 Mochow 副本与 canonical 来源不一致时返回错误证据。
- 新增 Provider、配置脱敏、排序映射、canonical 回查、一致性失败和 Golden Dataset
全链路回归。默认测试不调用真实千帆;真实联调边界记录在
docs/development/RERANKER_SETUP.md。公开 Search REST API 留在 DEMO-009。
DEMO-009
- 新增
/api/v1/documents上传/列表、/api/v1/documents/{document_id}详情/直接删除和/api/v1/search,通过 OpenAPI 固化 multipart 上传、Document 状态和最小 Source Result 契约;API 响应不暴露 storage key、Index Profile 或厂商实现。 - 上传接口同步复用 DEMO-003~006 的完整入库流水线,并在完成后回读 PostgreSQL canonical
Document,确保返回最终
ready状态和数据库生成时间戳。 - 新增文档查询/删除应用服务。删除覆盖当前及历史已记录 Index Profile 的向量行、 ChunkIndexState、Chunk、Document、解析 JSON 和原始文件;向量清理失败时保留 canonical 数据,来源清理失败返回明确错误并记录 Demo 一致性边界。
- 业务依赖延迟创建,因此健康检查和 OpenAPI 启动不要求云端凭证;Provider 配置不完整时
业务接口返回
503,上游异常使用收敛后的错误响应,避免泄露凭证或厂商正文。 - 新增完全离线的 REST 全链路测试,覆盖上传、列表、详情、Dense/Reranker 检索、来源字段、 直接删除、OpenAPI 路径、输入校验、404、Provider 延迟加载及删除失败保护。
ARCH-001
- 接受 BOS、OceanBase Vector、千帆
bge-large-zh和bce-reranker-base作为新的 V1 Provider 基线;PostgreSQL 继续保存 canonical 数据,OceanBase 只保存可重建索引。 - 新增 ADR-009~ADR-011 和独立迁移计划,将 ARCH-002~ARCH-006 的范围、依赖、验收顺序 与安全边界写入任务清单。
- 保留 Demo 的 Dense Top20 → Reranker Top5、现有 Parser/Chunk、API/MCP 业务契约;不随迁移 引入 Top50、RRF、Marker/Pandoc、LLM 派生索引、ACL 或 Hybrid/BM25 扩展。
- 本任务只调整架构和产品文档,不修改运行时代码;旧系统地址、账号和凭据均未写入仓库, 真实验收只允许使用轮换后的 Secret 与受控测试资源。
ARCH-002
- 新增官方
bce-python-sdk驱动的BosObjectStorage,保持逻辑 key 与 Bucket/Prefix 分离, 覆盖 Put、流式 Open、HEAD Exists 和 Delete。 - 上传先使用可回卷临时流确定长度,再通过
If-None-Match: *原子拒绝覆盖;404/412 和 其他 SDK 异常映射为不泄露 Endpoint、响应正文或凭据的稳定存储错误。 - 新增
local|bos类型化配置和运行时工厂;BOS AK/SK 使用SecretStr,Bucket、Endpoint、 Prefix 和超时均由环境注入。Local 仍是测试/开发及 ARCH-005 前的默认实现。 - 新增完全离线的 BOS Adapter、配置、Provider wiring 测试和中文配置说明;未使用内部配置 清单中的真实地址或凭据,真实 BOS 联调留在 ARCH-006。
ARCH-003
- 新增官方
pyobvector驱动的OceanBaseVectorStore,覆盖批量 Upsert、按 Document/Profile 参数化删除和 Profile 条件下推的 Cosine ANN TopN;SDK 类型不进入业务服务。检索固定使用 OceanBase 4.6 的VECTOR_INDEX(... pre_filter),不依赖普通WHERE的自适应过滤,也不做 全局 TopK 后过滤。 - 将低值优先的
cosine_distance转为score = 1 - distance,并对向量维度、有限值、 非零范数、返回字段、UUID、Profile、距离范围和排序执行失败关闭校验。 - 新增
VECTOR(1024)、Cosine HNSW、Profile/Document 标量索引的预置 DDL;应用不自动执行 外部索引 DDL,PostgreSQL 继续保存 canonical 数据,OceanBase 表可重建。 - 新增
mochow|oceanbase类型化配置、SecretStr 密码和运行时工厂;Mochow 保持 ARCH-005 前的默认实现。全部 Adapter、配置、Schema 和 wiring 测试均离线运行,真实数据库验收留在 ARCH-006。
ARCH-004
- 将千帆 Reranker 运行基线从
qwen3-reranker-0.6b切换为已接受的bce-reranker-base;配置使用受限 Literal,业务 API、Provider 抽象和 Dense Top20 → Reranker Top5 行为保持不变。 - 按千帆
POST /v2/rerank官方约束复核并保留 Query 1600 字符、64 个候选、单文档 4096 字符、Top-N 及响应排序/索引/分数失败关闭校验;真实 API Key 不进入代码和测试。 - 更新 Adapter、环境示例、Provider wiring、配置与请求契约测试;Golden Dataset 继续使用
确定性 Fake 离线评估,但显式绑定
bce-reranker-base当前模型标识。真实 BCE 质量与延迟 统一留在 ARCH-006 使用轮换凭据验收。
ARCH-005
- 将正式运行默认值切换为 BOS、OceanBase Vector 和
bce-reranker-base,新 Profile ID 为demo-bge-large-zh-structure-v1-oceanbase-v1;Local/Fake 仍用于显式本地和离线测试。 - 新增 PostgreSQL canonical
index_profiles迁移与shadow / active / retired生命周期, 通过局部唯一索引保证至多一个 Active Profile;API 启动时优先解析数据库 Active Profile, 无记录的新部署才使用配置基线。 - 新增
ekp-index-rebuild build|verify|activate:从 canonical Chunk 分文档重建,确定性 Upsert, 重试时跳过完整文档并清理目标 Profile 的部分写入;激活前核对全部 ChunkIndexState,并在 PostgreSQL 事务内锁定 Chunk 写入、退役旧 Profile、激活新 Profile。 - 移除 Mochow 运行配置、公开 Adapter、测试、配置文档及
pymochow依赖;不自动删除旧 外部索引,保留受控回滚和运维退役边界。 - 新增重建/重试/完整性失败/单 Active/激活/迁移/CLI 脱敏测试及中文操作文档。真实资源 构建、BOS/OceanBase/Qianfan 连通性和 30~50 条脱敏查询验收仍属于 ARCH-006。
ARCH-006(已完成)
- Golden Dataset 已扩展为 32 条完全合成 Query,覆盖退款、技术支持、住宿标准和报销材料; Dense、Reranker、canonical Source Result 的离线回归全部通过。
- 新增
ekp-live-acceptance/make live-acceptance,实际覆盖上传、解析、Chunk、Embedding、 OceanBase Dense Top20、BCE Reranker Top5、canonical 来源核对及本次运行数据清理。 - live 命令强制要求
APP_ENV=test、专用live-acceptance/BOS Prefix、凭据授权确认、资源 授权确认和显式运行开关;当前环境下已验证会在创建 Provider 前失败关闭且不泄露细节。 - 根据最新配置清单和 test 环境只读探测,确认没有独立 PostgreSQL;目标为 OceanBase 4.3.5.4 MySQL 模式,同一数据库承载 canonical 关系数据和逻辑隔离的向量表。ADR-012 已 取代先前 PostgreSQL 部署假设,业务事实来源与可重建索引的逻辑边界保持不变。
- 已在目标 test 集群只读验证数据库连通、版本与兼容模式,并通过
EXPLAIN确认VECTOR_INDEX(... pre_filter)生成VECTOR INDEX ADAPTIVE SCAN (PRE-FILTER);未读取 业务正文或输出任何连接信息/凭据。 - canonical SQLAlchemy 默认已切换为
mysql+pymysql,数据库 URL 使用SecretStr,新增 有界连接池/超时配置;新增 forward-only migration,以生成列唯一索引保证 OceanBase 与 SQLite 下至多一个 Active Profile;PostgreSQL 驱动已移除。 - 配置清单中的 test 凭据仅按用户明确授权临时注入本次验收,不保存为
.env、不提交、 不连接 fat/prod;完成后仍记录为待轮换风险。 - 已在 test OceanBase 执行全部 forward-only migration,并对本项目表完成列、类型、默认值、
主键的 scoped schema drift 核对;OceanBase 扩展语法导致标准 MySQL 反射器不能可靠比较的
二级索引/唯一约束/外键,由 SQLite 全量 drift、真实唯一约束事务和 live 级联删除补充验证。创建
knowledge_chunks_v112 列专用向量表和 Cosine HNSW,确认 PRE-FILTER 执行计划。迁移前 已确认所有目标表均不存在,没有覆盖原有 31 张业务表;事务内双 Active 写入实测被唯一 索引拒绝并完整回滚。 - 已完成 OceanBase canonical → BOS →
bge-large-zh→ OceanBase Vector →bce-reranker-base→ canonical Source Result 正式验收:32 条查询的 Recall@1/3/5、MRR、 NDCG@5 均为1.0,P503787.61 ms、P954759.21 ms,通过 P9510000 ms门槛。 - 正式命令退出码为
0;两份合成文档、canonical Chunk/State、向量行与 BOS 对象均走随机 前缀清理,数据库复核live-Document/Chunk/Vector 残留均为0。首次 live 运行曾出现 一次瞬时失败,分阶段诊断及随后完整 32 查询均成功,仍需在后续稳定性任务关注 Provider 重试、限流和告警。
DEMO-010(已完成)
- 新增同源轻量 Admin Console,提供
/admin/upload、/admin/documents和/admin/search三个直接可访问页面;FastAPI 只负责静态文件路由,页面业务操作全部复用/api/v1,没有复制上传、文档管理或检索逻辑。 - 上传页支持 PDF、DOCX、TXT、Markdown 文件选择、处理状态和结果摘要;文档页展示文件名、 类型、上传时间、状态,支持详情与确认删除;Search Lab 显式展示 Rank、Filename、Page、 Section、Chunk Content、Dense Score 和 Rerank Score。
- 前端使用安全 DOM 文本节点渲染 API 数据,不注入 HTML,不展示 storage key、Index Profile、 Provider Endpoint 或凭据;只实现 Demo 规定的三个页面,没有引入 ACL/RBAC、任务、审计、 Compiled Knowledge、MCP、Hybrid/BM25 或额外前端构建工具链。
- 新增静态路由、资产、范围和 API First 契约测试;浏览器使用本地确定性 Provider 完成
README.md上传 → Ready → 列表/详情 → Top5 检索,并验证桌面和 390px 移动布局无横向 溢出、无前端警告或错误。删除的 UI 确认和服务端清理语义由现有 REST 全链路测试覆盖。 - 完整验证结果:Ruff Format/Lint、Mypy、JavaScript 语法、Git diff、依赖锁、Alembic Head/
离线升级均通过;Unit + Integration
150 passed,RAG Evaluation5 passed。本任务没有 修改检索算法或 Provider,不重复调用真实资源验收;ARCH-006 的 32 条真实查询结果继续 作为底层链路基线。 - 已知非阻塞风险保持不变:配置清单中的历史 test 凭据仍应轮换;真实 Provider 瞬时失败的 重试、限流与告警留待后续明确 Task。Demo Console 本身没有新增凭据或生产 Endpoint。