From 272c9f0fae8a2b1556cd13602147cf9b30b7ce8b Mon Sep 17 00:00:00 2001 From: D-robotics Date: Wed, 11 Nov 2026 15:49:08 +0800 Subject: [PATCH] =?UTF-8?q?JEV=5FSIDECAR=5FAPI:=20team=20usage=20guide=20(?= =?UTF-8?q?external=20URL=20+=20Bearer=20auth=20+=E9=80=82=E7=94=A8?= =?UTF-8?q?=E8=BE=B9=E7=95=8C)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- JEV_SIDECAR_API.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 JEV_SIDECAR_API.md diff --git a/JEV_SIDECAR_API.md b/JEV_SIDECAR_API.md new file mode 100644 index 0000000..3977907 --- /dev/null +++ b/JEV_SIDECAR_API.md @@ -0,0 +1,59 @@ +# jev 打分服务调用指南(团队共享 · FAT) + +> 模型: jev r41 (Laya mmBERT-base + LoRA), 文档级相关度打分, 输出校准概率 +> 部署: d-cloud FAT 推理服务 `jev-r41-sidecar` (svc-6uz682ztqn), API Key 鉴权 + +## 接口 + +### POST /score — 单条打分 + +```bash +BASE="https://dcloud-ns6hy2.inference-fat.d-robotics.cc/AIStudio/v1/inference/api/svc-6uz682ztqn" +KEY="sk-****" # 向 dingbin.wang 申请, 不要提交进 git (网关只认 Authorization: Bearer, 不认 X-API-Key) + +curl -X POST "$BASE/score" \ + -H "Authorization: Bearer $KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "S100 的默认调试串口波特率是多少", + "doc_text": "RDK S100 使用 UART0 作为调试串口, 默认波特率 921600..." + }' +``` + +返回: +```json +{ + "p_win": [0.99, 0.71, 0.12], // 每个滑动窗口的相关度概率 + "p_mean": 0.607, // 窗口均值 (主排序依据) + "p_max": 0.99, // 窗口最大值 + "p_final": 0.643, // 温度校准后的最终分 (展示/阈值用) + "n_win": 3 // 文档被切的窗口数 +} +``` + +### POST /score_batch — 批量打分 + +```json +{"items": [{"query": "...", "doc_text": "..."}, {"query": "...", "doc_text": "..."}]} +``` + +### GET /health — 健康检查 + +## 打分语义 + +- 输出的是「query 与文档的相关度概率」(0~1), 经温度校准 +- 排序用途: 按 `p_mean` 降序; 阈值用途: `p_final` +- 经验阈值 (RDK 知识库场景): >0.7 强相关, 0.4-0.7 待定, <0.3 不相关 +- 文档自动滑窗 (800 token/窗, 最多 4 窗), 长文档无需预切 + +## 适用边界 (实测, 重要) + +- ✅ 主题相关度: "这篇文档讲的是不是这个问题的话题" — 强项 +- ❌ 型号/实体细粒度区分: "RDK S100 串口(921600)" vs "RDK S600 串口(1500000)" 两篇都会得 0.98 — **模型分不清型号**, 型号过滤要在打分前后自己做 (标题/URL 匹配) +- ⚠️ 完全无关的短文本 (<50字) 校准不稳, 打分对象应是知识库文档块 + +## 注意 + +- ⚠️ key 不要写进代码仓库, 用环境变量 +- 单条打分 CPU ~1s (4 窗长文档), 批量请用 score_batch +- 服务部署在 FAT 环境, 仅供测试/评测, 不接生产流量