那拉提文旅智能问答

Vue 3 + TypeScript + Vite 前端；FastAPI + Pydantic + SQLAlchemy 后端；PostgreSQL + pgvector。当前后端提供知识管理、来源、文档、人工审核和历史记录，问答仍为占位接口。

启动数据库

需要可用的 Docker Engine（Windows 可使用 Docker Desktop），在项目根目录运行：

docker compose up -d db

开发数据库默认仅绑定 127.0.0.1:5432。请在正式使用前修改默认密码。

启动后端（Windows 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 已存在时不要覆盖）：

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，原状态保存在导入日志中。

启动前端（另开终端）

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。

审核请求示例（仅为占位测试数据）：

{
  "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 后执行：

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。

团队协作文档

目标 Gitea 仓库：https://gitea.kronecker.cc/saint/border-red-post-nalati。

本地 Embedding 评估（可选）

已提供独立 CPU 评估工具、固定版本 BGE Provider 和合成测试集。安装、实际资源/编码结果、指标定义及局限见本地模型评估。模型包与缓存不属于默认 FastAPI 运行依赖；当前评估不改变正式 API 或写入业务数据库。

7.1 KiB Raw Blame History Unescape Escape