58 lines
5.9 KiB
Markdown
58 lines
5.9 KiB
Markdown
# 共同开发任务板
|
||
|
||
> 实名分工见 [团队工作计划](TEAM_WORKPLAN.md)。每项任务仍须在 Gitea Issue 中补充预计完成时间、验收记录和关联合并请求。
|
||
|
||
| 编号 | 模块 | 任务 | 负责人 | 状态 |
|
||
|---|---|---|---|---|
|
||
| T01 | 前端 | 验证 Vue 页面启动、补充截图 | 吉海燕 | 进行中（生产构建已通过，待浏览器启动验证） |
|
||
| T02 | 后端 | 验证 FastAPI `/docs`、`/api/health` | 范涵宇 | 进行中（`/api/health` 已通过，待数据库就绪后验证完整启动和 `/docs`） |
|
||
| T03 | 数据库 | 启动 PostgreSQL 并验证知识入库 | 范涵宇 | 受阻（Docker Desktop/WSL 引擎尚未就绪） |
|
||
| T04 | 文档 | 明确接口字段、知识来源审核规则 | 杨星萱 | 待办 |
|
||
| T05 | 知识库 | 设计 sources/documents/chunks/version 表 | 范涵宇 | 待办 |
|
||
| T06 | 检索 | 实现关键词检索基线 | 范涵宇 | 待办 |
|
||
| T07 | 向量 | 评估 Embedding 并实现 pgvector | 范涵宇 | 待办 |
|
||
| T08 | RAG | 集成 LLM 与来源展示 | 范涵宇 | 待办 |
|
||
| T09 | 实验 | 构建可核验问题集及评分规范 | 杨星萱 | 待办 |
|
||
| T10 | 工程 | 补充测试、Alembic、鉴权与部署 | 范涵宇（主）、全员 | 待办 |
|
||
|
||
## 2026-10-15 首次联调记录
|
||
|
||
- 已创建本机 `backend/.venv`（Python 3.12）并安装后端依赖；该目录由 Git 忽略。
|
||
- 已安装前端依赖，`npm run build` 通过。构建中发现并修复了问答来源 URL 可为 `null` 时的 TypeScript 类型不一致。
|
||
- 已使用临时 Uvicorn 服务（关闭数据库生命周期初始化）验证 `GET /api/health` 返回 `200` 和预期状态数据，验证后服务已关闭。
|
||
- 本机 Docker CLI 已安装，但 Docker Desktop 引擎无法启动，且 WSL 尚未处于可用状态。因此尚未执行 PostgreSQL 容器启动、知识条目新增/读取、默认生命周期启动和浏览器端联调。
|
||
- 后续操作：重启 Windows 后启动 Docker Desktop；确认 `docker version` 能显示 Server 信息，再在项目根目录运行 `docker compose up -d db`，随后继续 T02、T03 和 T01 的剩余验收。
|
||
|
||
## 2026-10-15 后端阶段 1–2 分支验收
|
||
|
||
分支：`feat/backend-knowledge-management`。以下为分支验收结果，须经既定审阅流程合入后再关闭任务；不覆盖前述其他环境的历史记录。
|
||
|
||
| 范围 | 已完成的验证 | 剩余事项 |
|
||
|---|---|---|
|
||
| T02 | 默认生命周期真实启动 Uvicorn；HTTP `/docs`、健康检查、数据库就绪检查通过 | 合并请求审阅、团队环境复核 |
|
||
| T03 | 真实 PostgreSQL 16 测试实例完成迁移、知识录入和读取；后端进程重启后数据仍可读取 | 当前主机 Docker 守护进程未运行，启动需管理员权限；Compose 容器与浏览器端联调待复核 |
|
||
| T05（阶段 2 范围） | 来源、文档、知识关联、版本、人工审核、软删除和历史快照；验证旧基础表迁移保留数据 | `chunks` 和索引版本留到检索阶段；字段与前端、资料负责人共同确认 |
|
||
| T10（部分） | Alembic 迁移、并发版本检查、PostgreSQL 自动化测试、启动说明 | 登录鉴权、限流、生产部署留到后续工程阶段 |
|
||
|
||
验证环境：Python 3.11；使用可选 `pgserver` 启动独立 PostgreSQL 16.2 测试实例并启用 pgvector。该方式用于验证 SQL 和接口，不等同于 Docker 容器验收。
|
||
|
||
实际命令与结果（在 `backend/` 执行）：
|
||
|
||
- `ruff check .`：通过。
|
||
- `ruff format --check .`：通过。
|
||
- `pytest -q`：22 passed；依赖库产生一条 TestClient 弃用提示，不影响本轮用例。
|
||
- 覆盖：新库迁移、已有基础表接管、重复升级、阶段 2 降级后基础正文保留、ORM 与迁移结构一致、审核前置条件、正文/来源/文档变更后重新审核、历史快照、软删除引用保护、筛选与分页、并发写入冲突、跨域预检、真实 HTTP 与服务重启持久化。
|
||
|
||
所有测试正文、来源和审核人均为占位数据，临时数据库不入库。当前问答仍是占位接口，未开展论文对照实验。Issue、合并请求和最终批准结论须补入 Gitea 后按团队规则归档。
|
||
|
||
## 2026-10-16 T07：本地 Embedding 与资源评估
|
||
|
||
- 用户选择先评估本地开源模型与本机资源；从最新 `dev` 独立创建 `feat/backend-local-embedding-evaluation`，不依赖仍待审的 #6/#7/#8。
|
||
- 实现不在普通启动流程加载模型的 Provider、固定 revision 与空间身份、维度/有限数/L2 校验、真实 token 上限拒绝及独立 CPU 评估 CLI。可选依赖和模型缓存与默认后端环境分开。
|
||
- 固定 BGE small/base 中文模型，CPU 线程 2、batch 8、各输入形状预热一次后重复 5 次。单查询中位数分别 8.927/52.912 ms，独立进程峰值 RSS 531.2/865.5 MiB；两者实际运行、向量校验与超限拒绝通过。
|
||
- 项目资料台账目前只有占位行，本轮采用事先固定的 12 文本/10 问题合成样本，仅验证流程。small 的合成 Hit@1/Recall@3/MRR@3 为 0.90，base 为 1.00；不是实际文旅质量或论文结论，保留 small 的错误案例，不据此冻结正式默认模型。
|
||
- 固定配置、完整指标定义、输入哈希、复现命令和限制见 [本地模型评估](LOCAL_EMBEDDING_EVALUATION.md)。原始运行报告、权重、虚拟环境只保存在本机 Git 元数据目录，不入库。
|
||
- 向量数据库/空间隔离、索引构建、向量/RRF 检索、真实已核验问题集和浏览器/部署验收仍待后续推进；本轮没有把这些标记为完成。
|
||
|
||
- 本独立分支实际验证：`ruff check .`、`ruff format --check .` 通过；`pytest -q` **44 passed**，包含当前 dev 的 PostgreSQL/HTTP 基线与新增轻量契约/指标用例。small/base 另由独立模型环境真实执行；可选依赖在新建空环境中完成 CPU wheel 安装与后续依赖解析验证。先前 #7/#8 的 70/91 项结果属于各自分支，不混同为本独立分支的测试计数。
|