mirror of
https://github.com/CJackHwang/ds2api.git
synced 2026-05-06 17:35:30 +08:00
67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# 原始流数据样本目录
|
||
|
||
该目录只保留**上游真实 SSE 原始流**，用于本地回放、字段分析和回归测试。
|
||
|
||
## 默认永久样本
|
||
|
||
仓库当前保留两份 canonical 默认样本：
|
||
|
||
- `guangzhou-weather-reasoner-search-20260404`：包含 `reference:N` 引用标记的天气搜索流，用于验证引用清理与正文输出。
|
||
- `content-filter-trigger-20260405-jwt3`：真实命中的 `CONTENT_FILTER` 风控流，用于验证终态处理与拒答格式。
|
||
|
||
默认回放工具会优先读取 [`manifest.json`](./manifest.json) 中的 `default_samples`，以稳定固定回放集。
|
||
更完整的协议级行为结构说明见 [docs/DeepSeekSSE行为结构说明-2026-04-05.md](../../docs/DeepSeekSSE行为结构说明-2026-04-05.md)。
|
||
|
||
## 自动采集接口
|
||
|
||
本地启动服务后，可以直接调用专用接口自动落盘一份 raw-only 样本：
|
||
|
||
```bash
|
||
POST /admin/dev/raw-samples/capture
|
||
```
|
||
|
||
这个接口会：
|
||
|
||
- 接收一个普通的 OpenAI chat completions 请求体
|
||
- 走项目内同一条处理链
|
||
- 自动保存请求元信息 `meta.json`
|
||
- 自动保存上游原始流 `upstream.stream.sse`
|
||
|
||
采集接口的响应体仍然是项目当次的实际输出，但它不会再写入样本目录。这样样本树始终只保留原始流，后续回放时再按需本地生成派生结果。
|
||
|
||
## 目录规范
|
||
|
||
每个样本一个子目录，且只保留下面两类文件：
|
||
|
||
- `meta.json`：样本元信息（问题、模型、采集时间、备注）
|
||
- `upstream.stream.sse`：完整原始 SSE 文本（`event:` / `data:` 行）
|
||
|
||
## 回放与对比
|
||
|
||
回放工具会读取 `upstream.stream.sse`，在本地自动生成当前解析结果，并把派生结果写到 `artifacts/raw-stream-sim/<run-id>/<sample-id>/`，例如：
|
||
|
||
- `replay.output.txt`：本次回放生成的最终可见文本
|
||
- `report.json`：本次回放的结构化报告，包含事件数、chunk 数、终态、引用泄露检查等信息
|
||
|
||
运行全部 canonical 样本：
|
||
|
||
```bash
|
||
./tests/scripts/run-raw-stream-sim.sh
|
||
```
|
||
|
||
运行单个样本并和已有基线比对：
|
||
|
||
```bash
|
||
./tests/scripts/compare-raw-stream-sample.sh markdown-format-example-20260405-spacefix
|
||
```
|
||
|
||
如果你已经有历史基线目录，也可以把它作为第二个参数传进去，脚本会对比当前回放结果和基线输出。
|
||
|
||
## 扩展方式
|
||
|
||
1. 抓取一次真实请求。
|
||
2. 直接调用 `/admin/dev/raw-samples/capture`，或者手工新建 `<sample-id>/` 目录并放入 `meta.json` + `upstream.stream.sse`。
|
||
3. 运行回放工具或对比脚本，生成本地派生结果并检查是否回归。
|
||
|
||
> 注意：样本可能包含搜索结果正文与引用信息，请勿放入敏感账号/密钥。
|