# Embedding 与 Rerank：实际接口记录的离线重放

记录日期：2026-10-08。资料为虚构商店，不是 apizt 或真实商家的业务规则。

## 下载材料

网页中的请求、响应和 record 直接来自本次真实 API 调用；knowledge-fixture.json 保存原始文档 ID 与标准查询。check-retrieval.py 只读文件，不使用凭据、网络或新付费请求。

Embedding 实测：text-embedding-3-small，POST /v1/embeddings，3段文档 + 3个查询一次批量发送，encoding_format=float；六个向量均为1536维，3问的首位来源匹配shipping/returns/invoice。usage prompt_tokens=139，total_tokens=139。

Rerank 实测：qwen3-rerank，POST /v1/rerank，3个原始候选、top_n=3；results按returns、shipping、invoice排序，原始index分别1、0、2。usage prompt_tokens=138，completion_tokens=0。无输出token并不代表免费。

后台已按测试令牌、型号、完成时间和输入token匹配两项费用记录。Rerank费用列显示USD0.000006（六位小数），billing_status为matched_console_display。Embedding费用列显示USD0.000000，金额低于显示精度，精确账本金额未确认，因此billed_usd仍为null、billing_status为matched_display_below_precision；显示为零不代表免费。费用与匹配依据见实际record。这只覆盖本次路由，目录、价格展示、token usage和账单是不同证据。

## 重放命令

把知识库、检查器及对应请求响应下载到同一目录：

```bash
python3 check-retrieval.py embedding embedding-request.json embedding-response.json knowledge-fixture.json
python3 check-retrieval.py rerank rerank-request.json rerank-response.json knowledge-fixture.json
```

Embedding输出应有6个向量、1536维、3个passed=true。脚本按data[].index重排，而非假定data数组顺序；非法模型、重复/越界index、数量不齐、非有限值、零向量或维度不齐会拒绝。

Rerank输出包含original_index与document_id，保留真实分数。脚本检查top_n、唯一index、原始候选顺序和分数有限且按返回降序。分数不是事实正确率，离线检查也不替代实际业务回答验收。

## 与正式知识库的距离

- 这次是短候选接口验证，不是全部分组、客户端、框架部署或质量基准。
- Embedding只测试float与默认维度，未测base64编码、dimensions透传、长文本、最大批量或并发。
- Rerank未发送instruct，也未测试长文截断、空候选和最大候选数量。其他供方接口字段不能自动套用。
- 三个查询都有资料支持，没有测试无答案拒答；正式知识库应另补相近文档、否定条件和无答案用例。
- 这次Rerank直接对固定候选排序；原始输入顺序不是Embedding召回排名，不能称为召回率提升实测。
- 生成答案需独立Chat请求，并对原文与引用核查；Rerank最高分不是退款审批或业务授权。

## 索引迁移清单

保留model、实际dimension、encoding、distance、normalization、文本prefix、chunk版本、文档版本、source_id和原文。换模型或文本规则后，在新索引重建并验收，保留旧索引到回归通过。同维度不等于同向量空间；不要截断数组凑数据库维度。

新请求如果超时，先标记unknown并核对实际日志，不自动重复POST。应用侧独立控制凭据、请求上限和成本；本下载检查器无自动调用逻辑。