2026-09-02 11:28:13 +08:00

198 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 项目进度
当前阶段:Provider 架构迁移
已完成:DEMO-001~DEMO-009、ARCH-001、ARCH-002、ARCH-003、ARCH-004、ARCH-005
进行中:无
阻塞:无
下一任务:ARCH-006
Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → ARCH-005 → ARCH-006`
执行;每个 Task 验证后独立推送并合并 `main`。全部迁移完成后再继续 DEMO-010。
## 任务记录
### 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_v1` Chunk 策略,默认使用 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-zh` Adapter,使用 Bearer API Key,支持最多 16 条批量请求,
Chunk 同时限制 450 tokens/2000 字符,并严格校验响应顺序、1024 维度和有限数值;
凭证使用 `SecretStr`,
不进入错误消息或提交记录。
- 新增官方 `pymochow` Adapter,支持分批 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 标量过滤,支持可配置 HNSW `ef`,严格校验响应字段、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。