新客户端使用 /api/v1;挂载在 /jev 等前缀下时将前缀加在所有路径前。机器可读合同由 /api/openapi.json 提供。本文路由已按服务实现核对;完整请求约束以对应版本的 OpenAPI 为准,实际验证范围见 发布检查记录。
请求和响应使用 JSON。版本字段是精确字符串;未定义字段、非有限数字和非法动作会被拒绝。不要把模型服务地址或密钥放入 URL 查询参数。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/v1/games |
游戏 ID、规则和可用引擎信息 |
| GET | /api/v1/models |
当前浏览器的模型连接公开信息 |
| GET / POST | /api/v1/connections |
列举 / 创建临时连接 |
| DELETE | /api/v1/connections/{model_id} |
释放临时连接 |
| GET | /api/v1/connections/{model_id}/requests |
浏览器直连的长轮询队列 |
| POST | /api/v1/connections/{model_id}/results |
浏览器直连回传模型响应 |
| POST | /api/v1/decisions |
标准公开观测上的单次模型决策 |
| POST | /api/v1/sessions |
创建游戏会话 |
| GET / DELETE | /api/v1/sessions/{session_id} |
观察 / 释放会话 |
| POST | /api/v1/sessions/{session_id}/steps |
提交动作、模型决策或时间推进 |
| GET | /api/v1/sessions/{session_id}/replay |
导出当前会话动作追踪 |
| GET / PUT | /api/v1/leaderboards/{benchmark} |
读取 / 替换 Benchmark 榜单 |
连接和游戏会话属于创建它们的浏览器会话。编程客户端需要在后续请求中保留服务设置的 Cookie;owner 隔离用于资源归属。默认域名部署不要求网站登录,也可单独启用可选 BasicAuth。榜单默认只读;配置 JEV_ADMIN_TOKEN 后,写入使用 X-Jev-Admin-Token: <admin-token>,并兼容 Authorization: Bearer <admin-token>。启用可选网站 BasicAuth 时使用前者,避免 Authorization 头冲突。管理令牌与模型服务密钥用途不同。每个写入请求体最大 4 MiB。
GET /api/v1/models 同时返回本站 oneshot-hosted 与当前浏览器自己的连接。本站连接带 transport: "server"、managed: true,所有浏览器可调用,浏览器不能删除、轮询或向其伪造结果。请求接口与其他模型相同,input.model 必须使用返回的 served_model。只有服务进程读取 DASHSCOPE_API_KEY,注册接口仍拒绝密钥或服务器端点字段。详见 HOSTED_MODEL.md。
下面用 Cookie jar 保留连接所有权;每次调用都带 -b / -c,不要为每个请求创建新的 Cookie jar。示例不连接真实付费模型。
jev_api=http://127.0.0.1:8080
jev_cookie_jar=$(mktemp)
curl --fail-with-body -sS -c "$jev_cookie_jar" -b "$jev_cookie_jar" \
"$jev_api/api/v1/games"
curl --fail-with-body -sS -c "$jev_cookie_jar" -b "$jev_cookie_jar" \
-H 'Content-Type: application/json' \
--data '{"model_id":"my-model","name":"My Model","served_model":"my-served-model","adapter":"decision","transport":"browser"}' \
"$jev_api/api/v1/connections"
curl --fail-with-body -sS -c "$jev_cookie_jar" -b "$jev_cookie_jar" \
"$jev_api/api/v1/models"上述模型注册只提交公开元信息;执行模型决策还需浏览器持续处理该连接的请求队列。通常由页面负责完整链路。手动试玩无需模型连接,将游戏 ID 替换为清单中的真实 ID 后创建会话,后续使用返回的 session_id、revision 和候选动作:
curl --fail-with-body -sS -c "$jev_cookie_jar" -b "$jev_cookie_jar" \
-H 'Content-Type: application/json' \
--data '{"game":"GAME_ID","seed":42}' \
"$jev_api/api/v1/sessions"
curl --fail-with-body -sS -c "$jev_cookie_jar" -b "$jev_cookie_jar" \
-H 'Content-Type: application/json' \
--data '{"revision":0,"action":"ACTION_ID"}' \
"$jev_api/api/v1/sessions/SESSION_ID/steps"GAME_ID、SESSION_ID、ACTION_ID 为占位符,ACTION_ID 使用当前 decision.question.options 返回的候选 ID。以上手动动作不调用模型。
上述示例针对本地回环地址。访问启用了入口登录的域名时,额外使用 curl --user "$JEV_SITE_USER",由 curl 交互提示输入密码;不要把明文密码放入命令行参数或记录脚本。
首次进入 Playground 默认选择精选第一项贪吃蛇;精选顺序与默认选择共用同一配置。页面间切换保留当前游戏和对局。
前端首次进入、切换游戏、Restart 和终局“再来一局”均开始完整新局,不沿用种子输入框中的局面。棋盘恢复标准摆法;需要发牌、生成地图或方块序列的游戏仍正常随机生成,但进度、得分和行动历史从初始值开始。只有底部“按种子重开 / 换一个种子”显式使用种子,下一次普通 Restart 会回到标准开局模式。
- 棋盘入口
POST /api/game/new不传seed(或传null)表示标准开局。显式数字种子包括0仍用于合法预走的可复现局面。 - 国际象棋前端通过
POST /api/v1/sessions传{"game":"chess","seed":0}创建标准 32 子开局;非零种子保留合法开局前缀。通用会话接口的默认种子及 RL 调用合同不变。 - 其他游戏的普通重开不提交输入框种子;世界游戏调用无种子的
reset()。显式样例回放仍使用样例自身初始状态,不叠加种子。 - 种子与开局模式属于界面和复现信息,不注入模型的隐藏信息。实时游戏继续沿用原有时钟机制。
模型有三个不同字段:model_id 是本服务的稳定 ID,name 是榜单上的显示名称,served_model 是模型接口实际接受并返回的身份。重命名显示文字不改变模型身份。
创建请求只登记浏览器连接的公开元信息:
{
"model_id": "my-model",
"name": "My Model",
"served_model": "my-served-model",
"adapter": "openai",
"transport": "browser",
"json_mode": true,
"timeout_seconds": 120
}transport 固定为 browser,后端连接接口不接受 endpoint 或 api_key。完整请求地址与密钥在前端填写并只留在页面内存中,密钥仅发送给所填模型服务,不发送给 Jev 后端。页面轮询自己连接的决策队列,直接向模型服务发送请求,再把标准决策结果交回后端。关闭或刷新页面会中断此链路,需要重新连接。
页面中填写的请求地址应为完整 HTTP(S) URL,不能包含 URL 用户名、密码、查询或片段;例如 OpenAI 兼容接口包含完整 /v1/chat/completions 路径。模型接口须使用与 Jev 页面不同的 origin,避免密钥发送到游戏站点。模型服务必须允许当前页面来源的 CORS 请求,HTTPS 页面应连接 HTTPS 模型接口。Jev 后端没有代替浏览器发送模型请求的路径。
轮询 GET /connections/{model_id}/requests 每次最多等待 10 秒,返回 {"requests":[...]},其中每项是 jev.decision.v1 请求。回传到 POST /connections/{model_id}/results,请求体为 {"request_id":"...","result":{...标准响应...}};失败时用 error 代替 result,值只能是 connection_failed、invalid_response、timeout 或 cancelled。不要回传含密钥或上游敏感正文的错误内容。
adapter 为 decision 时使用下节的结构化合同,为 openai 时使用 Chat Completions JSON。接口返回的 model 必须与 served_model 相同;不同服务对模型别名的返回方式不同,应填写实际返回的名称。
自建模型服务接收以下 jev.decision.v1 JSON。observation 只包含公开观测;请求中的 question.options 是本次全部合法候选,模型必须选择其中一个 ID。
{
"schema_version": "jev.decision.v1",
"request_id": "decision-0001",
"model": "my-served-model",
"game": "example_game",
"observation": {"turn": 3, "visible_board": [[0, 1], [0, 0]]},
"question": {
"id": "decision",
"instructions": "Choose one legal action.",
"options": [
{"id": "left", "label": "Move left"},
{"id": "right", "label": "Move right"}
]
}
}example_game 仅用于说明 JSON 结构。实际游戏 ID 从 /api/v1/games 读取,状态与动作由对应引擎生成。
响应:
{
"schema_version": "jev.decision.v1",
"request_id": "decision-0001",
"model": "my-served-model",
"action": "right",
"probabilities": {"left": 0.2, "right": 0.8},
"usage": {"prompt_tokens": 82, "completion_tokens": 12}
}request_id 与 model 必须与请求完全相同。probabilities 可省略或为 null;如果提供,必须覆盖全部且仅有合法候选,取值在 0–1 之间,总和与 1 的误差不超过 1e-7。返回概率应来自模型服务可测量的候选分布,不用生成文本的自报置信度代替。
向浏览器连接下发决策时,用 POST /api/v1/decisions 包裹上述请求;后端排队等待该浏览器返回结果,不会自行访问模型服务:
{
"model_id": "my-model",
"input": {
"schema_version": "jev.decision.v1",
"request_id": "decision-0001",
"model": "my-served-model",
"game": "example_game",
"observation": {"turn": 3},
"question": {
"instructions": "Choose one legal action.",
"options": [{"id": "left", "label": "Move left"}, {"id": "right", "label": "Move right"}]
}
}
}请求使用 model、messages、temperature、max_tokens、stream: false。默认附带 response_format: {"type":"json_object"};模型服务不支持该字段时关闭连接的 json_mode。
模型应在 choices[0].message.content 中返回可解析的 JSON 字符串,例如 {"action":"right"}。服务响应顶层需要返回匹配的 model。此适配器不把 JSON 中自报的 probabilities 转成真实候选概率;没有可测量概率时相应指标保持缺失。
创建请求:
{"game": "实际游戏 ID", "seed": 42}会话返回 schema_version: "jev.session.v1"、session_id、game、seed、revision、公开 state、terminal 和可决策时的 decision。调用方只能依照当前返回的候选提交动作。
动作请求形态:
{"revision": 0, "action": "当前合法动作 ID"}也可以让已连接模型决策:
{"revision": 0, "model_id": "my-model"}action 与 model_id 互斥。revision 使用上次观察到的版本,避免两个请求覆盖同一状态。实时游戏的无动作推进可使用 ticks(0–120);具体时钟、终局和动作持续时间由共享引擎定义,不能通过省略动作冻结实时规则。
benchmark 支持 jevbench、decisionindex、harnessjevbench和 datajevbench。文件使用 jev.leaderboard.v1,每次导入是对应榜单的完整快照;保留需要显示的所有模型行。
{
"schema_version": "jev.leaderboard.v1",
"benchmark_id": "jevbench",
"title": "JevBench",
"version": "my-evaluation-v1",
"metric": "accuracy",
"score_scale": [0, 1],
"higher_is_better": true,
"axis_scale": [0, 1],
"rows": [
{
"model_id": "my-model",
"model_name": "My Model",
"score": 0.81,
"status": "complete",
"metrics": {"accuracy": 0.81, "brier": 0.18, "ece": 0.04},
"samples": 100,
"errors": 0,
"evaluated_at": "2026-10-16T00:00:00Z",
"protocol": "my-protocol-v1",
"axes": [
{"id": "planning", "label_en": "Planning", "label_zh": "规划", "score": 0.8, "samples": 40},
{"id": "reasoning", "label_en": "Reasoning", "label_zh": "推理", "score": 0.82, "samples": 60}
]
}
]
}该例为格式示例,非真实模型成绩。score_scale 控制总分范围,axis_scale 控制雷达轴范围;每条记录必须符合对应范围。模型 ID 在同一榜单内唯一,轴 ID 在同一模型内唯一。null 表示没有指标,不应写成 0。双语切换使用 label_zh 与 label_en。
修改榜单会保留上一版 JSON 归档,不需要原始训练样本或模型 checkpoint。JevBench、DecisionIndex、HarnessJevBench 与 DataJevBench 的总分使用各自指标定义。Harness 的总分为 Hard mean task score,ACC 优先显示 strict_task_accuracy;DataJevBench 使用 ACC 总分及 D1–D6 雷达维度。
在服务器上运行 python scripts/import_leaderboard.py results.json --leaderboard-dir ./leaderboard 可使用同一合同和归档逻辑进行本地导入,无需 Web 管理令牌。该命令不调用模型服务,失败时不会把输入内容回显到错误消息中;默认目录遵循 JEV_LEADERBOARD_DIR,未配置时使用仓库 leaderboard/。它替换指定榜单的完整快照,已存在的上一版保留在目录内的 history/。具体文件约定见 榜单数据目录。
| HTTP 状态 | 调用方处理 |
|---|---|
401 / 403 |
检查管理员认证、浏览器 Cookie 或连接所有权 |
404 |
资源不存在,重新查询游戏/连接/会话清单 |
409 |
ID 冲突、会话版本冲突或任务状态不允许当前操作 |
422 |
修改请求字段或非法动作,勿原样无限重试 |
429 |
并发或连接数限制,降低并发并稍后重试 |
502 |
模型响应不符合合同或上游错误,核对模型名与返回结构 |
503 / 504 |
模型连接失效、超时或暂不可用,重新连接或恢复服务 |
上游响应文本和鉴权头不作为公共错误信息返回。客户端也不应把模型密钥写入自己的日志或评测数据。
UNO的版本化会话在 state.handoff=true 时不提供合法动作或模型观测。对 POST /api/v1/sessions/{session_id}/steps 发送当前 revision 和 reveal: true 可显示下一席位。交接请求不能同时包含 action、model_id 或 ticks。兼容页面继续使用 /api/showcases/reveal。