157 lines
9.9 KiB
Markdown
157 lines
9.9 KiB
Markdown
# 项目进度
|
||
|
||
当前阶段:Provider 架构迁移
|
||
|
||
已完成:DEMO-001~DEMO-009、ARCH-001、ARCH-002
|
||
进行中:无
|
||
阻塞:无
|
||
|
||
下一任务:ARCH-003
|
||
|
||
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 `qwen3-reranker-0.6b` Adapter,调用 `/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。
|