116 lines
7.1 KiB
Markdown
116 lines
7.1 KiB
Markdown
# 那拉提文旅智能问答
|
||
|
||
Vue 3 + TypeScript + Vite 前端；FastAPI + Pydantic + SQLAlchemy 后端；PostgreSQL + pgvector。当前后端提供知识管理、来源、文档、人工审核和历史记录，问答仍为占位接口。
|
||
|
||
## 启动数据库
|
||
需要可用的 Docker Engine（Windows 可使用 Docker Desktop），在项目根目录运行：
|
||
```bash
|
||
docker compose up -d db
|
||
```
|
||
开发数据库默认仅绑定 127.0.0.1:5432。请在正式使用前修改默认密码。
|
||
|
||
## 启动后端（Windows PowerShell）
|
||
```powershell
|
||
cd backend
|
||
py -3.12 -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
pip install -r requirements.txt
|
||
if (!(Test-Path .env)) { Copy-Item .env.example .env }
|
||
alembic upgrade head
|
||
uvicorn app.main:app --reload
|
||
```
|
||
API 文档：http://127.0.0.1:8000/docs
|
||
|
||
Linux / macOS 可使用以下等价命令（需要 Python 3.11+；`.env` 已存在时不要覆盖）：
|
||
```bash
|
||
cd backend
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
test -f .env || cp .env.example .env
|
||
alembic upgrade head
|
||
uvicorn app.main:app --reload --host 127.0.0.1
|
||
```
|
||
|
||
配置始终从 `backend/.env` 读取，环境变量优先。必须先迁移再启动；应用启动只检查数据库版本，不再执行 `create_all`。旧版 `knowledge_items` 会被非破坏性接管；首次迁移前仍须备份。迁移会保留原条目及导入快照，不推测缺失的采集时间。旧版 `verified` 条目因缺少完整审核记录，会转为 `pending`，原状态保存在导入日志中。
|
||
|
||
## 启动前端（另开终端）
|
||
```powershell
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
Vite 通常使用 http://localhost:5173。
|
||
|
||
## 已有接口
|
||
- GET `/api/health`
|
||
- GET `/api/ready`：检查数据库连接
|
||
- POST `/api/chat`：占位接口，尚未接入检索和 LLM
|
||
- GET `/api/knowledge`
|
||
- POST `/api/knowledge`
|
||
- GET `/api/knowledge/page`、GET/PATCH/DELETE `/api/knowledge/{id}`
|
||
- POST `/api/knowledge/{id}/review`、GET `/api/knowledge/{id}/history`
|
||
- GET/POST `/api/sources`、GET/PATCH/DELETE `/api/sources/{id}`、GET `/api/sources/{id}/history`
|
||
- GET/POST `/api/documents`、GET/PATCH/DELETE `/api/documents/{id}`、GET `/api/documents/{id}/history`
|
||
|
||
### 阶段 2 接口约定
|
||
|
||
- 所有日期均为带时区的 ISO 8601。输入拒绝未知字段，标题/正文不能全为空白，网址只接受 HTTP(S)；可选网址空字符串按未填写处理。
|
||
- `GET /api/knowledge` 保留数组响应，支持 `q`、`category`、`verification_status`、`limit`（默认 100，最大 200）和 `offset`。新页面应使用 `/api/knowledge/page`，避免把首批条目数量当作总数。
|
||
- 分页响应为 `{items, total, page, page_size}`；`page` 从 1 开始，`page_size` 默认 20、最大 100。来源、文档、知识分页和各类历史接口均支持分页。
|
||
- 来源分页支持 `q`；文档分页支持 `q`、`source_id`、`category`；知识分页支持 `q`、`category`、`verification_status`、`source_id`、`document_id`。`q` 为字面文本子串搜索，尚非论文中的关键词检索基线。
|
||
- 创建知识沿用 `title/category/content/source_url`，新增可选 `source_id/document_id/collected_at`；状态固定为 `pending`。关联文档时自动解析其来源，填写的来源或网址若冲突会报错。直接来源链接的旧调用仍受支持。
|
||
- 来源创建字段：`name`、可选 `source_url`、`notes`。文档创建字段：`source_id/title/content/collected_at`，可选 `category/notes`。文档来源归属固定，换来源需新建文档。
|
||
- PATCH 请求必须携带读取时获得的 `expected_version`，并至少提交一个修改字段；DELETE 使用查询参数 `expected_version`。版本过期返回 409，防止覆盖他人修改。
|
||
- 审核请求字段见下方示例。`verification_status` 只允许 `pending/verified/rejected`；核验人和说明必填。通过审核前必须有来源网址及真实采集时间。这里只记录人工结论，不会自动核实网页。
|
||
- 修改条目、关联来源或关联文档都会将相关知识转为 `pending`，清除当前审核字段并记录失效原因。历史快照保留当时的条目、来源和文档。
|
||
- 删除采用软删除；被有效文档或知识引用的来源、被有效知识引用的文档不能删除（409）。已删除记录不出现在列表，但历史仍可查看。
|
||
- 错误响应使用 `detail`：参数错误 422、记录不存在 404、版本/引用冲突 409、数据库暂不可用 503。
|
||
|
||
审核请求示例（仅为占位测试数据）：
|
||
```json
|
||
{
|
||
"expected_version": 1,
|
||
"verification_status": "verified",
|
||
"reviewer": "test-reviewer",
|
||
"verification_notes": "示例审核说明，实际使用须填写真实核验依据"
|
||
}
|
||
```
|
||
|
||
响应新增 `version/updated_at/is_deleted` 及关联、采集、审核字段；完整类型以 `/openapi.json` 和 `/docs` 为准。前端现有录入与数组列表可继续使用；来源、文档、审核及完整分页页面仍需按接口联调。
|
||
|
||
前端包括问答、知识库管理、来源与更新、实验评估四个页面。实验评估页面没有虚构数据；所有页面明确标记当前功能状态。
|
||
|
||
注意：当前 API 尚未接入 Embedding、RAG、网络搜索、后台更新任务或用户认证；本地 Embedding 评估工具单独见下方。审核人是本机开发环境输入字段，不是认证身份。服务保持仅本机访问；正式部署能力留到后续阶段。`.env` 不要提交到 Git。
|
||
|
||
### 后端测试和迁移回滚
|
||
|
||
在 `backend` 目录安装 `requirements-dev.txt` 后执行：
|
||
```bash
|
||
ruff check .
|
||
ruff format --check .
|
||
pytest -q
|
||
```
|
||
|
||
测试需要真实 PostgreSQL + pgvector：设置 `TEST_DATABASE_URL`（`postgresql+psycopg://...`），或另行 `pip install pgserver` 使用可选的本机临时实例。`pgserver` 仅用于测试，不是应用运行依赖；外部测试数据库账号需有建 Schema 权限且已启用 vector 扩展。每个测试使用独立 Schema，不会清空业务表。测试使用的占位正文和审核人不代表真实资料。
|
||
|
||
迁移命令为 `alembic upgrade head`，可重复执行。需要撤回阶段 2 时，先备份，再执行 `alembic downgrade 0001_baseline`；它保留基础知识字段，但会删除新增来源、文档、审核字段与历史记录，软删除的基础条目也会重新可见。恢复完整数据应使用备份。不要在有业务数据的数据库执行 `downgrade base`。
|
||
|
||
## 团队协作文档
|
||
|
||
- [项目章程](docs/PROJECT_CHARTER.md)
|
||
- [开发计划](docs/DEVELOPMENT_PLAN.md)
|
||
- [阶段 1 详细开发计划](docs/PHASE_1_DEVELOPMENT_PLAN.md)
|
||
- [共同开发规范](docs/CONTRIBUTING.md)
|
||
- [系统架构](docs/ARCHITECTURE.md)
|
||
- [任务分工](docs/TASKS.md)
|
||
- [三人团队工作计划](docs/TEAM_WORKPLAN.md)
|
||
- [技术决策](docs/DECISIONS.md)
|
||
|
||
目标 Gitea 仓库：`https://gitea.kronecker.cc/saint/border-red-post-nalati`。
|
||
|
||
|
||
## 本地 Embedding 评估（可选）
|
||
|
||
已提供独立 CPU 评估工具、固定版本 BGE Provider 和合成测试集。安装、实际资源/编码结果、指标定义及局限见 [本地模型评估](docs/LOCAL_EMBEDDING_EVALUATION.md)。模型包与缓存不属于默认 FastAPI 运行依赖；当前评估不改变正式 API 或写入业务数据库。
|