Compare commits

..
10 changed files with 282 additions and 16 deletions
+3 -3
View File
@@ -1,6 +1,6 @@
# 那拉提文旅智能问答
Vue 3 + TypeScript + Vite 前端;FastAPI + Pydantic + SQLAlchemy 后端;PostgreSQL + pgvector。当前后端提供知识管理、来源、文档、人工审核、关键词/向量/RRF 检索、文本与向量发布、历史记录及认证/角色权限,问答仍为占位接口。
Vue 3 + TypeScript + Vite 前端;FastAPI + Pydantic + SQLAlchemy 后端;PostgreSQL + pgvector。当前后端提供知识管理、来源、文档、人工审核、关键词/向量/RRF 检索、文本与向量发布、历史记录及认证/角色权限,`/api/chat` 提供条目级关键词证据检索,不生成模型答案。
## 启动数据库
需要可用的 Docker Engine(Windows 可使用 Docker Desktop),在项目根目录运行:
@@ -48,7 +48,7 @@ Vite 通常使用 http://localhost:5173。
- 注册/登录/退出、当前会话、资料修改、改密与管理员用户列表,详见 [认证接口契约](docs/AUTH_API.md)
- GET `/api/health`
- GET `/api/ready`:检查数据库连接
- POST `/api/chat`:占位接口,尚未接入检索和 LLM
- POST `/api/chat`:已核验条目关键词检索,问题1–500字符;返回 retrieval_only/no_evidence 和来源,详见 [CHAT_API.md](docs/CHAT_API.md)
- GET `/api/knowledge`
- POST `/api/knowledge`
- GET `/api/knowledge/page`、GET/PATCH/DELETE `/api/knowledge/{id}`
@@ -107,7 +107,7 @@ Vite 通常使用 http://localhost:5173。
前端包括问答、知识库管理、来源与更新、实验评估四个页面。实验评估页面没有虚构数据;所有页面明确标记当前功能状态。
注意:当前已实现本地 Embedding、文本/向量快照、精确向量及 RRF 混合检索;`/api/chat` 仍是占位接口,生成模型实际调用暂缓,网络搜索、后台更新任务和真实领域评测尚未实现。管理接口由服务端认证与角色校验;审核表单的核验人仍是人工输入字段。已完成隔离环境的浏览器 Cookie/CSRF、角色与真实检索核心流程验收,见 [浏览器验收记录](docs/BROWSER_ACCEPTANCE.md) 与 [导出/采集时间复核](docs/EXPORT_BROWSER_ACCEPTANCE.md);完整生产部署、Docker 数据库与 HTTPS 验收仍待完成。`.env` 不要提交到 Git。
注意:当前已实现本地 Embedding、文本/向量快照、精确向量及 RRF 混合检索;`/api/chat` 已接入独立关键词检索,生成模型实际调用暂缓,网络搜索、后台更新任务和真实领域评测尚未实现。管理接口由服务端认证与角色校验;审核表单的核验人仍是人工输入字段。已完成隔离环境的浏览器 Cookie/CSRF、角色与真实检索核心流程验收,见 [浏览器验收记录](docs/BROWSER_ACCEPTANCE.md) 与 [导出/采集时间复核](docs/EXPORT_BROWSER_ACCEPTANCE.md);完整生产部署、Docker 数据库与 HTTPS 验收仍待完成。`.env` 不要提交到 Git。
### 后端测试和迁移回滚
+1 -4
View File
@@ -26,9 +26,6 @@ def chat(payload: ChatRequest, db: Session = Depends(get_db)) -> ChatResponse:
"因此系统仅返回可追溯证据,不生成或改写答案。"
),
status="retrieval_only",
sources=[
{"title": hit.title, "source_url": hit.source_url}
for hit in result.results
],
sources=[{"title": hit.title, "source_url": hit.source_url} for hit in result.results],
retrieval_run_id=result.run_id,
)
+6 -3
View File
@@ -1,11 +1,14 @@
from typing import Literal
from uuid import UUID
from pydantic import BaseModel, Field
from pydantic import BaseModel
from app.schemas.catalog import Input
from app.schemas.retrieval import QueryText
class ChatRequest(BaseModel):
question: str = Field(min_length=1, max_length=2000)
class ChatRequest(Input):
question: QueryText
class SourcePreview(BaseModel):
+4 -2
View File
@@ -1,14 +1,16 @@
from datetime import datetime
from typing import Literal
from typing import Annotated, Literal
from uuid import UUID
from pydantic import BaseModel, Field
from app.schemas.catalog import Category, Input
QueryText = Annotated[str, Field(min_length=1, max_length=500)]
class RetrievalRequest(Input):
query: str = Field(min_length=1, max_length=500)
query: QueryText
mode: Literal["keyword"] = "keyword"
top_k: int = Field(default=5, ge=1, le=20)
category: Category | None = None
+161
View File
@@ -0,0 +1,161 @@
"""Retrieval-only chat integration; synthetic evidence, never a generation call."""
import copy
import pytest
from fastapi.testclient import TestClient
from sqlalchemy import func, select, text
from sqlalchemy.orm import Session
from test_catalog import document, source
from test_retrieval import add_item
from test_runtime import server
from app.models.rag import RagContext
from app.models.retrieval import RetrievalRun
from app.services import retrieval
def test_overlong_chat_question_is_rejected_at_the_http_boundary(client):
with TestClient(
client.app, base_url="https://testserver", raise_server_exceptions=False
) as public:
response = public.post("/api/chat", json={"question": "q" * 501})
assert response.status_code == 422, response.text
@pytest.mark.parametrize(
"payload",
[
{},
{"question": ""},
{"question": " \t\n "},
{"question": None},
{"question": 123},
{"question": "q" * 2000},
{"question": "q" * 2001},
{"question": "alpha", "model": "not-accepted"},
{"question": "alpha", "messages": []},
],
)
def test_invalid_chat_input_creates_no_retrieval_or_context(client, migrated_database, payload):
response = client.post("/api/chat", json=payload)
assert response.status_code == 422, response.text
assert all("input" not in error for error in response.json()["detail"])
with Session(migrated_database) as db:
assert db.scalar(select(func.count()).select_from(RetrievalRun)) == 0
assert db.scalar(select(func.count()).select_from(RagContext)) == 0
def test_chat_query_boundary_normalization_and_public_history_permissions(client):
response = client.post("/api/chat", json={"question": "q" * 500})
assert response.status_code == 200, response.text
assert response.json()["status"] == "no_evidence"
client.cookies.clear()
public = client.post("/api/chat", json={"question": " alpha "})
assert public.status_code == 200
assert public.json()["status"] == "no_evidence" and public.json()["sources"] == []
assert client.get(f"/api/retrieval/runs/{public.json()['retrieval_run_id']}").status_code == 401
def test_chat_sources_match_audited_snapshot_and_history_stays_immutable(client, migrated_database):
approved = add_item(client, title="verified alpha", content="alpha synthetic evidence")
add_item(client, status="pending", title="pending alpha", content="alpha unreviewed")
add_item(client, status="rejected", title="rejected alpha", content="alpha rejected")
deleted = add_item(client, title="deleted alpha", content="alpha deleted")
assert (
client.delete(
f"/api/knowledge/{deleted['id']}?expected_version={deleted['version']}"
).status_code
== 204
)
result = client.post("/api/chat", json={"question": " alpha "}).json()
assert result["status"] == "retrieval_only" and "不生成" in result["answer"]
history = client.get(f"/api/retrieval/runs/{result['retrieval_run_id']}").json()
assert history["query"] == "alpha" and history["mode"] == "keyword"
assert [h["knowledge_id"] for h in history["results"]] == [approved["id"]]
assert result["sources"] == [
{"title": h["title"], "source_url": h["source_url"]} for h in history["results"]
]
saved = copy.deepcopy(history)
assert (
client.patch(
f"/api/knowledge/{approved['id']}",
json={"expected_version": approved["version"], "content": "revised alpha"},
).status_code
== 200
)
assert client.post("/api/chat", json={"question": "alpha"}).json()["status"] == "no_evidence"
assert client.get(f"/api/retrieval/runs/{history['run_id']}").json() == saved
assert (
client.post(
"/api/rag/contexts",
json={"retrieval_run_id": history["run_id"], "completion": {"model": "contract-model"}},
).status_code
== 422
)
with Session(migrated_database) as db:
assert db.scalar(select(func.count()).select_from(RagContext)) == 0
@pytest.mark.parametrize("change", ["source", "document"])
def test_chat_cannot_reuse_evidence_after_catalog_revision(client, change):
src = source(client)
doc = document(client, src["id"])
add_item(client, document_id=doc["id"], content="alpha synthetic catalog evidence")
assert client.post("/api/chat", json={"question": "alpha"}).json()["status"] == "retrieval_only"
path, version, fields = (
(f"sources/{src['id']}", src["version"], {"source_url": "https://example.com/new"})
if change == "source"
else (f"documents/{doc['id']}", doc["version"], {"content": "revised synthetic document"})
)
assert (
client.patch("/api/" + path, json={"expected_version": version, **fields}).status_code
== 200
)
result = client.post("/api/chat", json={"question": "alpha"}).json()
assert result["status"] == "no_evidence" and result["sources"] == []
def test_chat_capacity_failure_is_not_a_successful_empty_answer(
client, migrated_database, monkeypatch
):
add_item(client, content="alpha synthetic capacity evidence")
monkeypatch.setattr(retrieval, "MAX_ITEMS", 0)
response = client.post("/api/chat", json={"question": "alpha"})
assert response.status_code == 503 and "sources" not in response.json()
with Session(migrated_database) as db:
assert db.scalar(select(func.count()).select_from(RetrievalRun)) == 0
def test_chat_failed_history_insert_does_not_leave_partial_rows(client, migrated_database):
with migrated_database.begin() as db:
db.execute(
text("ALTER TABLE retrieval_runs ADD CONSTRAINT reject_chat_run CHECK(false) NOT VALID")
)
assert client.post("/api/chat", json={"question": "alpha"}).status_code == 409
with Session(migrated_database) as db:
assert db.scalar(select(func.count()).select_from(RetrievalRun)) == 0
def test_chat_retrieval_history_survives_real_http_restart(migrated_database):
with server(migrated_database) as client:
assert client.post("/api/chat", json={"question": "q" * 501}).status_code == 422
item = add_item(client, content="alpha real HTTP synthetic evidence")
response = client.post("/api/chat", json={"question": " alpha "})
assert response.status_code == 200
result = response.json()
history = client.get(f"/api/retrieval/runs/{result['retrieval_run_id']}").json()
assert history["results"][0]["knowledge_id"] == item["id"]
assert history["query"] == "alpha"
with server(migrated_database) as client:
assert client.get(f"/api/retrieval/runs/{result['retrieval_run_id']}").json() == history
exported = client.post(
"/api/retrieval/exports",
json={"run_ids": [result["retrieval_run_id"]], "include_contexts": True},
)
assert exported.status_code == 200
client.cookies.clear()
assert (
client.post("/api/chat", json={"question": "alpha"}).json()["status"]
== "retrieval_only"
)
+1 -1
View File
@@ -14,7 +14,7 @@ FastAPI + Pydantic
|-- 来源获取 -> 人工核验 -> 文本切分 -> 生成向量 -> 发布版本
```
当前后端实现健康/数据库就绪检查、来源与文档管理、知识增删改查、分页筛选、人工审核、历史快照、认证会话/角色权限、文本/向量快照及独立关键词/向量/RRF 检索;问答仍为占位接口。数据库由 Alembic 显式迁移并启用 pgvector,DeepSeek RAG 待明确恢复后实现。前端已接入登录/注册、个人中心、账户设置、会话恢复、路由守卫和角色菜单,以及来源、文档的创建、编辑、软删除、分页搜索与历史快照;实验页不伪造数据,知识审核与浏览器 Cookie/PostgreSQL 联调仍需验收。
当前后端实现健康/数据库就绪检查、来源与文档管理、知识增删改查、分页筛选、人工审核、历史快照、认证会话/角色权限、文本/向量快照及独立关键词/向量/RRF 检索;`/api/chat` 为独立条目关键词检索适配,返回检索状态与来源,不调用生成模型(见 [CHAT_API.md](CHAT_API.md))。数据库由 Alembic 显式迁移并启用 pgvector,DeepSeek RAG 待明确恢复后实现。前端已接入登录/注册、个人中心、账户设置、会话恢复、路由守卫和角色菜单,以及来源、文档的创建、编辑、软删除、分页搜索与历史快照;实验页不伪造数据,知识审核与浏览器 Cookie/PostgreSQL 联调仍需验收。
## 阶段 2 数据边界
+30
View File
@@ -0,0 +1,30 @@
# 检索式聊天接口
`POST /api/chat` 是已核验知识的条目级关键词检索适配,不调用生成模型。它与问答页面直接使用的 chunk/RRF 接口不同,也不会创建 Responses 准备快照。生成模型与真实服务接入继续延期。
## 请求
```json
{"question":"那拉提示例关键词"}
```
接口公开可用,无需登录;只接受 question。服务端去除首尾空白后校验1–500个字符,与底层 RetrievalRequest 共用同一字段约束;字符数不代表模型token数。缺失、空白、错误类型、超长输入或额外字段(包括 model、messages、凭据)均返回422,不写检索记录。只有停用词或标点、没有有效检索词时同样返回422。错误不包含原始输入值。
原适配曾允许2000字符,内层检索只允许500字符,导致501–2000字符请求返回500。现在该范围在HTTP入参处明确返回422,不截断问题,也不绕过原检索限制。
## 响应与证据
成功返回 answer、status、sources 和 retrieval_run_id。answer 为固定的检索状态说明,**不是生成式回答**。
- status=retrieval_only:返回最多5条来源预览(title/source_url),来自同一条目关键词检索历史的排名结果。说明中的命中总数可以大于来源预览数;完整排名、正文片段、来源/知识版本、配置、语料指纹和耗时保存在原检索记录中。
- status=no_evidence:没有命中的有效已核验依据,sources为空;仍保存该次真实无命中检索的run ID。
待审核、拒绝、软删除、来源/文档失效或修订后等待重新审核的条目不作为来源。资料修订影响后续请求,不重写已经保存的历史快照。没有LLM调用量、生成答案或费用字段,不能把固定说明用于领域质量评分。
检索历史及JSONL导出仍要求管理员权限;公开获取run ID不授予历史读取权限。该run的mode=keyword、证据粒度为knowledge_item,不能传入只接收chunk检索的 `POST /api/rag/contexts`。需要Responses准备时先使用chunks/vector/hybrid检索。
容量超限/数据库不可用保留503,历史保存约束冲突返回409;错误不会伪装成200无命中,也不会保存部分历史。仅成功完成检索与历史事务后返回来源。无额外数据库迁移。
## 验证边界
测试使用合成条目、真实隔离PostgreSQL和默认应用HTTP生命周期,覆盖500字符边界、501字符HTTP失败复现与修正、参数拒绝不写记录、公开调用与历史权限、审核筛选、资料修订/历史不变、容量与事务失败,以及进程重启后的历史和导出。没有模型调用或新增浏览器验收。
+1 -1
View File
@@ -2,7 +2,7 @@
本阶段按用户要求先实现通用请求格式,生成模型选择和真实调用延期。新准备请求采用非流式 **Responses API**(服务端点为 `<base_url>/responses`):`model/instructions/input/max_output_tokens`,从结构化 `output` 读取 assistant 文本。依据 [OpenAI Responses 迁移说明](https://developers.openai.com/api/docs/guides/migrate-to-responses)、[DeepSeek Responses 兼容表](https://api-docs.deepseek.com/guides/responses_api/) 与[百炼 Responses 文档](https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-responses)。当前仍为纯组包和解析,不绑定实际服务地址、密钥或模型,不发出 HTTP 生成请求。
本阶段提供管理员上下文准备与历史接口、完整证据快照、固定提示词及纯响应解析器。`POST /api/chat` 仍保留原占位状态,尚未成为生成式问答接口;准备记录固定为 `kind=prepared_request, model_called=false`,不能作为实际模型回答、耗时、费用或领域实验结果。
本阶段提供管理员上下文准备与历史接口、完整证据快照、固定提示词及纯响应解析器。`POST /api/chat` 是独立的条目级关键词检索适配,返回检索状态和来源,尚未成为生成式问答接口(见 [CHAT_API.md](CHAT_API.md));准备记录固定为 `kind=prepared_request, model_called=false`,不能作为实际模型回答、耗时、费用或领域实验结果。
## 准备与读取
+10 -2
View File
@@ -11,9 +11,9 @@
| T05 | 知识库 | 设计 sources/documents/chunks/version 表 | 范涵宇 | 已完成(迁移、发布快照和接口已合入;待 Docker 联调) |
| T06 | 检索 | 实现关键词检索基线 | 范涵宇 | 已完成(已核验知识 BM25 与检索历史已合入) |
| T07 | 向量 | 评估 Embedding 并实现 pgvector | 范涵宇 | 已完成(本地模型、精确向量和 RRF 已合入;待真实领域评测) |
| T08 | RAG | 集成 LLM 与来源展示 | 范涵宇 | 协议基础已合入(Responses 请求/解析调整已在独立分支通过验证,待审;生成模型选型与实际调用延期) |
| T08 | RAG | 集成 LLM 与来源展示 | 范涵宇 | Responses 协议已合入(请求/解析与旧快照兼容已完成;生成模型选型与实际调用延期) |
| T09 | 实验 | 构建可核验问题集及评分规范 | 杨星萱 | 待办 |
| T10 | 工程 | 补充测试、Alembic、鉴权与部署 | 范涵宇(主)、全员 | 进行中(迁移、认证、CSRF、224项回归及浏览器核心流程已通过;Docker/HTTPS/部署待验收) |
| T10 | 工程 | 补充测试、Alembic、鉴权与部署 | 范涵宇(主)、全员 | 进行中(迁移、认证、CSRF及浏览器核心流程已通过;聊天边界修正和312项分支回归待审,Docker/HTTPS/部署待验收) |
## 2026-10-15 首次联调记录
@@ -126,3 +126,11 @@
- 本轮 `pytest -q backend/tests/test_rag.py backend/tests/test_exports.py` **113 passed**;完整 `pytest -q backend/tests` **294 passed, 1 skipped**。skip 为显式启用的真实 Embedding 专项,本轮不运行模型。ruff检查/格式检查及前端类型/生产构建通过;未修改页面交互,不宣称新增浏览器验收。
- PR #44 合入后同步最新 dev,保留两份阶段记录并解决本文件追加冲突。此次同步后重新执行前端时区6项、会话3项及类型/生产构建,均通过;backend树与此前294项回归时一致,本次未重复运行全量后端测试,也未新增模型调用或浏览器验收。
## 2026-10-17 T10:检索式聊天边界与后端验收
- PR #45 的 head/merge 均已核对进入 dev,再从最新 dev 创建 `fix/backend-chat-validation`。新合入 PR #46 已实现 `/api/chat` 的检索式适配,本轮补上后端边界修正和集成验收,不重复实现检索、不接入生成模型。
- 已复现501字符问题返回500:外层ChatRequest允许2000字符,内层RetrievalRequest只允许500字符。现在两者共用QueryText与输入规范,问题去首尾空白后1–500字符,超长/空白/错误类型/额外字段在HTTP边界返回422,不静默截断,也不写检索历史。
- 补充有效审核来源筛选、资料修订后重新审核、公开聊天/私有历史权限、历史与导出持久化、容量503及写入409完整回滚验证;真实HTTP重启后检索历史保持一致。Chat仅生成固定检索状态说明,条目级记录不能传给chunk级Responses准备。完整契约见 [CHAT_API.md](CHAT_API.md)。
- 专项 `pytest -q backend/tests/test_chat.py backend/tests/test_retrieval.py` **35 passed**;完整 `pytest -q backend/tests` **312 passed, 1 skipped**,skip为显式启用的真实Embedding专项,本轮未运行模型。ruff检查/格式检查、diff检查和最新前端类型/生产构建通过。API路径、响应字段和数据库迁移不变;README/架构文档更正已过期的聊天占位说明。无新增浏览器验收或领域分数。
@@ -0,0 +1,65 @@
# 阶段 2 知识收集清单(计划)
> 阶段:2026-10-19 至 2026-10-23(阶段 2:知识管理)
> 目标:收集并登记首批 30–50 条可核验资料,完成初步分类与来源核验。
> 维护人:杨星萱(知识库、实验与文档负责人)
## 一、阶段 1 知识交付物汇总(截至 2026-10-18)
| 交付物 | 位置 | 状态 |
|---|---|---|
| 资料台账模板 | [material-ledger.md](material-ledger.md) | 基础版已合入 `dev`;“更新时间”字段与测试条目 K-0002 依赖合并请求 #51,未合入前不得按已具备处理。 |
| 审核规则 | [review-rules.md](review-rules.md) | 草案已合入 `dev`,待团队确认后定稿。 |
| 联调验收记录模板 | [acceptance-record.md](acceptance-record.md) | 已合入 `dev`。 |
| 字段核对反馈 | `field-feedback.md`(依赖 #51) | 其中 `source_id`、`collected_at`、`notes` 三项建议待范涵宇、吉海燕确认。 |
## 二、收集目标与口径
- 总量:30–50 条,覆盖红色文化、旅游资源、民宿服务、交通出行四类。
- 每条资料必须来源可回访、事实可核验;未核验保持 `pending`,不得进入正式检索。
- 只登记真实资料;不编造来源、事实或数据。演示/测试条目必须明确标注,且不得与真实资料混淆。
- 首版不承诺实时房态、实时价格或自动联网核验;此类内容不纳入本阶段收集范围。
## 三、四类收集方向与数量分配
| 类别 | 建议数量 | 收集方向 | 来源优先级 |
|---|---:|---|---|
| 红色文化 | 8–12 条 | 边疆红驿相关历史背景、红色纪念地、戍边/英烈事迹、红色场馆介绍 | 政府/文旅局/纪念馆官方 > 权威媒体 |
| 旅游资源 | 10–15 条 | 那拉提景区概况、景点介绍、游览路线、开放时间、票务/预约说明(静态)、适宜季节 | 景区官网/文旅局 > 权威媒体 |
| 民宿服务 | 6–10 条 | 民宿类型、服务内容、位置、入住须知(静态说明) | 官方平台/文旅局 > 权威媒体 |
| 交通出行 | 6–10 条 | 抵达交通方式、班车/自驾路线、景区内交通、天气与安全提示 | 交通部门/文旅局 > 权威媒体 |
## 四、来源类型与核验要点
1. 优先采集文旅局、景区官网、政府公告、交通部门等官方来源;权威媒体可作为补充。
2. 一般网站与自媒体仅可作线索,不能单独作为 `verified` 的依据,除非能追溯到原始官方来源。
3. “独立来源”是指不同发布主体的原始材料,或可追溯到不同原始材料的权威发布;转载同一公告的多个页面不视为独立来源。
4. 关键事实须至少由一个独立来源交叉印证,方可标记为 `verified`;详细口径以 [审核规则](review-rules.md) 定稿为准。
5. 记录资料版本、获取日期;“更新时间”仅在 #51 合并后填写,便于后续向量重建与数据集说明。
## 五、字段与登记要求
- 沿用 [资料台账](material-ledger.md) 已有字段:标题、类别、来源名称、URL、获取日期、正文摘要、真实性判断、核验日期、核验人、状态、备注。
- “更新时间”字段在 #51 合并后纳入必填口径;在此之前不得用自定义列替代正式字段。
- 状态仅使用 `pending` / `verified` / `rejected`。每条先登记为 `pending`;仅将 `verified` 条目交给范涵宇入库。
## 六、执行顺序
1. 优先收集官方来源的景区概况与红色文化资料。
2. 补充交通与民宿的静态说明。
3. 逐条完成来源、关键事实与时效性核验;信息缺失或来源存疑时保持 `pending`。
4. 按批次提交台账与 `verified` 清单,并记录联调结果。
## 七、阶段验收标准
本阶段结束时,应提交下列可复核交付物:
1. 30–50 条台账记录,按四类统计数量,并区分真实资料和明确标注的测试资料。
2. 每条记录的来源 URL 可访问检查结果;不可访问或无法回访的记录保持 `pending` 或标记 `rejected`。
3. `pending` / `verified` / `rejected` 的数量统计,以及可交给后端入库的 `verified` 清单。
4. 对已入库 `verified` 条目的联调验收记录,使用 [联调验收记录模板](acceptance-record.md) 记录环境、操作、结果和证据位置。
## 八、待定事项与依赖
- #51 合并前:`source_id` 选择、`collected_at` 是否必填、`notes` 是否新增,以及“更新时间”字段均尚未定稿。
- 以上数据库与前端改动由范涵宇、吉海燕评估确认;确认结果应同步更新本清单、台账和接口文档。