f4cea4677a
JsonlFileSink 把五字段 trace 落 workdir/trace.jsonl(非阻塞·写失败不阻断生成);studio.py sink 接线;SAA 扩展段 schema(接口对称五核心+内容不对称 ext);管理面 3 只读端点 roles/traces/cost(惰性 import 保住「仅 import service.app 不牵 fastapi」红线)。测试 test_jsonl_sink 3 / test_admin_routes 6 全绿。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
89 lines
5.9 KiB
JSON
89 lines
5.9 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://wanxiang.ai/contracts/trace/saa-trace-event.schema.json",
|
|
"title": "SaaTraceEvent",
|
|
"description": "SAA(Spring AI Alibaba)16 节点廉价生成线的统一 trace 事件契约(H 族 · A2)。【这是什么】一条 trace 记录 = 一次生成轨迹里的一步,由 SAA Java adapter 产出。核心五字段(traceId / step / cost / verdict / timestamp)与 tier2-trace-event.schema.json 完全同名同义(H1 接口对称子集);ext 扩展段是 SAA 这一轨独有的,记录当前节点在 16 节点图上的位置与执行状态(H1 内容不对称:各轨各写各的,没有的字段绝不编造)。【为什么独立成约】两条异构生成线写进同一张 trace 表,靠的是「接口对称、内容不对称」。本 schema 定义 SAA 轨写进统一表的记录形状;tier2 那一轨的扩展段在 tier2-trace-event.schema.json 里,字段与本 schema 的 ext 不同名、也不要求对齐。【谁产】SAA Java 线的 trace adapter(game-cloud/game-module-aigc 或 studio 模块,待接线);本 schema 是字段口径约束,不是采集机制。【状态】spec 已立,SAA Java adapter 待产线接线(控制面 phase-1)。详见 contracts/trace/README.md 与 docs/architecture/架构/生成引擎/tier2细节图说-H-观测与成本.md 图 H1。",
|
|
"type": "object",
|
|
"required": ["traceId", "step", "timestamp", "ext"],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"traceId": {
|
|
"description": "公共核心子集字段(两条生成线同名同义必填)。一次生成的轨迹主键,贯穿整条生成任务链路;是对账 / 成本关联键,对接 tier2-verdict.schema.json 的 evidence.traceId。SAA 侧由 Java adapter 在构造时钉定,本次轨迹所有 step 共用同一个 traceId。",
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"step": {
|
|
"description": "公共核心子集字段。第几步(SAA 轨 = 第几个执行节点,0 起;对应 ext.nodeIndex。tier2 轨语义为 ReAct 第几轮 reply / 工具调用步,两者语义不同但字段名对称)。",
|
|
"type": "integer",
|
|
"minimum": 0
|
|
},
|
|
"cost": {
|
|
"description": "公共核心子集字段。这一步折成人民币的成本载体;仅在 SAA 节点真正发起模型调用时非空,其余节点步为 null。cost_rmb 由 cost.py 按 new-api quota 权威口径事后 best-effort 回填(成本权威源是 new-api 计费行,trace 不携金额估算)。",
|
|
"type": ["object", "null"],
|
|
"$ref": "#/$defs/cost"
|
|
},
|
|
"verdict": {
|
|
"description": "公共核心子集字段。这一步 / 这道门的裁决(可空)。SAA 轨当前在节点执行终态时填入(success / error / skipped),与 ext.nodeStatus 语义一致;门级裁决由裁决引擎 judge 另行回填,不在 adapter 映射阶段产生。",
|
|
"type": ["string", "null"]
|
|
},
|
|
"timestamp": {
|
|
"description": "公共核心子集字段。本步节点执行的发生时刻(ISO8601 字符串)。节点缺时间戳时为兜底空串。",
|
|
"type": "string"
|
|
},
|
|
"ext": {
|
|
"description": "SAA 扩展段(不对称段,各轨各写各的;tier2 轨的扩展段字段与此不同名也不要求对齐)。记录当前节点在 SAA 16 节点图上的位置(nodeIndex / nodeName)与执行状态(nodeStatus)。additionalProperties:false 锁死段名,防止 adapter 之外注入未约定字段。",
|
|
"$ref": "#/$defs/ext"
|
|
}
|
|
},
|
|
"$defs": {
|
|
"cost": {
|
|
"type": ["object", "null"],
|
|
"description": "成本载体(节点发起模型调用时非空)。tokens 由 adapter 实填(从模型调用 response 抓 input_tokens / output_tokens);cost_rmb 由 cost.py 按 new-api quota 事后回填(权威口径,trace 不携金额估算)。",
|
|
"additionalProperties": false,
|
|
"required": ["tokens"],
|
|
"properties": {
|
|
"tokens": {
|
|
"description": "本次模型调用的 token 用量。in / out 由 adapter 实填;cached 预留缓存命中 token(当前 adapter 未填)。",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": ["in", "out"],
|
|
"properties": {
|
|
"in": { "description": "输入 token 数。", "type": "integer", "minimum": 0 },
|
|
"out": { "description": "输出 token 数。", "type": "integer", "minimum": 0 },
|
|
"cached": { "description": "缓存命中 token 数(可选,预留;当前 adapter 未实填)。", "type": "integer", "minimum": 0 }
|
|
}
|
|
},
|
|
"cost_rmb": {
|
|
"description": "本步折算人民币(可选)。adapter 不填,由 cost.py 读 new-api logs.quota 按 traceId 关联后 best-effort 回填。",
|
|
"type": "number",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"ext": {
|
|
"type": "object",
|
|
"description": "SAA 扩展段对象。三个必填字段描述当前节点在 16 节点图上的位置与执行状态。additionalProperties:false 锁死字段集。",
|
|
"additionalProperties": false,
|
|
"required": ["nodeIndex", "nodeName", "nodeStatus"],
|
|
"properties": {
|
|
"nodeIndex": {
|
|
"description": "当前节点在 SAA 16 节点执行图中的位置(0 起整数;与顶层 step 同义但独立落盘,便于按节点序号切片分析)。",
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"maximum": 15
|
|
},
|
|
"nodeName": {
|
|
"description": "SAA 节点的可读名称(如 game_concept_generator / code_writer / asset_patcher 等;由 Java adapter 按 SAANode.name 填入,便于在 trace 里直接定位是哪个节点步)。",
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"nodeStatus": {
|
|
"description": "节点执行状态(终态才填;running 表示节点仍在执行中——仅在 adapter 需要记录中间态时使用)。该值同时被填进顶层 verdict 作这一步裁决。",
|
|
"type": "string",
|
|
"enum": ["pending", "running", "success", "error", "skipped"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|