# Grounded Chat 运行与引用验证手册

本手册验证“正式检索 → 证据约束回答 → 引用事件”的单轮问答闭环。默认 synthetic profile
不会调用百炼；非 synthetic profile 才经内部 `model-gateway` 调用 `deepseek-v4-flash`。

## 1. 前置服务

```bash
docker compose up -d --build web
docker compose --profile tools run --rm seed-demo-offline
curl -sS http://127.0.0.1:8000/health/ready
```

浏览器入口为 <http://127.0.0.1:8000/chat>，接口文档位于
<http://127.0.0.1:8000/docs>。

## 2. 直接验证 SSE

```bash
curl -sS -N -X POST http://127.0.0.1:8000/api/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data '{
    "knowledge_base_id":"3acd3785-970b-55f7-a669-9eb4695e27eb",
    "question":"花岗斑岩铜矿化有哪些典型蚀变特征？",
    "vector_top_k":20,
    "rerank_top_n":5,
    "max_tokens":512
  }'
```

成功流必须严格满足：

```text
meta(seq=1)
retrieval(seq=2)
delta(seq=3..n)
citations
usage
done
```

`done` 或 `error` 必须且只能出现一个。每个事件都是 JSON，`seq` 单调递增。`retrieval`
先返回本次授权范围内的证据和检索耗时；`citations` 只允许引用同一轮 source map 中的
`[S1]...[Sn]`。页面把回答、文件名和片段全部按纯文本显示，不执行 HTML。

## 3. 回答模式

| 模式 | 含义 | 是否调用云模型 |
|---|---|---|
| `grounded` + `synthetic_extractive` | 用已批准 synthetic 证据生成确定性摘录答案 | 否 |
| `grounded` + `cloud_grounded` | 模型回答包含通过校验的本轮引用 | 是 |
| `retrieval_only` | 模型没有给出合法引用，服务端退回安全证据摘录 | 云调用可能失败或输出不合格 |
| `refused` | 当前授权检索没有足以支持回答的证据 | 否 |
| `error` | 生成供应商或流契约失败；事件中不回显供应商正文 | 视失败阶段而定 |

文档片段在 Prompt 中被序列化为“不可信证据数据”，其中出现的命令、Prompt injection 或
凭证索取指令均不能成为系统指令。模型输出会在公开前检查引用；越界、畸形和大小写伪造标签
会被删除。引用 ID 合法只证明它来自本轮授权 source map，不自动证明自然语言声明在语义上
完全受到该证据支持；后者必须进入人工标注和引用精确率评测。

## 4. 取消与失败

React 页面的“停止生成”会中止当前 fetch，后端取消会继续传播到内部模型流。当前接口是单次
POST SSE，不保存会话，也不支持 `Last-Event-ID` 重放；持久会话、断线重放和 durable
completion 是后续扩展，不得把本切片描述成完整多轮聊天系统。

生成前的检索/授权错误仍返回 `application/problem+json`。流开始后的错误只能用终态
`event: error` 表达，不能再修改 HTTP 状态码。

## 5. 真实百炼验证

先运行 `provider-smoke` 并确认 Embedding、Rerank、Chat 三项均成功，再对百炼验证知识库发起
问答。synthetic 离线成功不能代替真实模型验收。API 和前端永远不持有百炼 Key；只有隔离的
`model-gateway` 持 Key 和公网出口。