From 23686b5cb0f15f92831a0cdd91d443f7e218ea3f Mon Sep 17 00:00:00 2001 From: yumoqing Date: Sat, 5 Sep 2026 21:29:56 +0800 Subject: [PATCH] =?UTF-8?q?docs(skill):=20model-auto-config=E8=A1=A5?= =?UTF-8?q?=E4=B9=9D=E6=AD=A5=E5=85=A8=E9=93=BE=E5=B7=A5=E4=BD=9C=E6=B5=81?= =?UTF-8?q?+=E6=96=B9=E6=B3=95=E8=AE=BA(=E9=98=B2=E7=BC=96=E9=80=A0/?= =?UTF-8?q?=E9=AA=8C=E8=AF=81=E9=97=AD=E7=8E=AF/=E6=8E=92=E6=9F=A5?= =?UTF-8?q?=E5=A5=97=E8=B7=AF/=E4=BC=9A=E8=AF=9D=E7=BA=A7=E9=9A=94?= =?UTF-8?q?=E7=A6=BB=E9=93=81=E5=BE=8B)+use=5Flast=5Fextract=E9=94=9A?= =?UTF-8?q?=E5=AE=9A=E5=A7=BF=E5=8A=BF;auto-api-pricing-config=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=E6=96=B0=E5=B7=A5=E5=85=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../common/auto-api-pricing-config/SKILL.md | 2 +- .../common/model-auto-config/SKILL.md | 80 +++++++++++++++---- 2 files changed, 67 insertions(+), 15 deletions(-) diff --git a/skills_library/pipelines/platform_general/common/auto-api-pricing-config/SKILL.md b/skills_library/pipelines/platform_general/common/auto-api-pricing-config/SKILL.md index 607b8b5..d1c7d07 100644 --- a/skills_library/pipelines/platform_general/common/auto-api-pricing-config/SKILL.md +++ b/skills_library/pipelines/platform_general/common/auto-api-pricing-config/SKILL.md @@ -2,7 +2,7 @@ name: auto-api-pricing-config description: 从API文档/报价文档自动生成uapi接口配置(headers/data/params/response)和定价(pricing YAML)。内部agent配置接口或报价时必读。 capability: auto_api_pricing -tools: [fetch_model_doc, extract_llm_api_spec, apply_llm_config, platform_llm_status] +tools: [fetch_model_doc, extract_llm_api_spec, apply_llm_config, apply_model_pricing, test_model_call, check_model_accounting, platform_llm_status] --- # 接口与报价自动配置（文档 → uapi + pricing） diff --git a/skills_library/pipelines/platform_general/common/model-auto-config/SKILL.md b/skills_library/pipelines/platform_general/common/model-auto-config/SKILL.md index d3bc590..0fcef5c 100644 --- a/skills_library/pipelines/platform_general/common/model-auto-config/SKILL.md +++ b/skills_library/pipelines/platform_general/common/model-auto-config/SKILL.md @@ -1,28 +1,48 @@ --- name: model-auto-config -description: 通读模型API文档自动生成模型治理配置（供应商/端点/适配模板/模型/定价）。内部agent收到文档URL配置模型时必读并严格执行。 +description: 通读模型API文档自动生成模型治理配置（供应商/端点/适配模板/模型/定价/测试/记账检查）。内部agent收到文档URL配置模型时必读并严格执行。 capability: model_auto_config -tools: [fetch_model_doc, extract_llm_api_spec, apply_llm_config, platform_llm_status] +tools: [fetch_model_doc, extract_llm_api_spec, apply_llm_config, apply_model_pricing, test_model_call, check_model_accounting, platform_llm_status] --- -# 模型自动配置（从 API 文档到落库） +# 模型自动配置（从 API 文档到落库到记账验证） 内部 agent 的核心能力：用户给一个供应商的模型 API 文档（或定价文档）URL， -自动完成模型治理全套配置。**定价只允许来自文档原文，禁止编造。** +自动完成模型治理全套配置 + 测试 + 记账核对。**定价只允许来自文档原文，禁止编造。** -## 工作流（严格按序） +## 工作流（九步全链，严格按序） -1. **抓取**：`fetch_model_doc(url)` → 纯文本。失败/内容不足如实说明，不凭记忆编。 -2. **提取**：`extract_llm_api_spec(doc_text)` → 结构化规格。重点核对： +1. **抓取**：`fetch_model_doc(url)` → 纯文本（末尾自动带 [出处URL] 行）。失败/内容不足如实说明，不凭记忆编。 +2. **提取**：`extract_llm_api_spec(doc_text)` → 结构化规格。**成功后规格自动锚定到本会话缓存** + （会话级隔离，返回里有 `__anchored__` 提示）。重点核对： - `endpoints[].base_url / region`（domestic 国内 / international 国际） - - `protocol`：能走 `/chat/completions` 的一律 `openai_compat` + - `protocol`：能走 `/chat/completions` 的一律 `openai_compat`；提交+轮询的填 `dashscope_async` - `models[].capability`：必须在能力字典内（见硬规则） - - `models[].description`：价格按文档原文记录，单位如实标注（如「元/百万tokens」「元/秒」），禁止换算推导 -3. **确认**：把端点、协议、每个模型的能力/定价摘要给用户确认后再落库。 -4. **落库**：`apply_llm_config(spec)`（幂等：供应商按名复用、模型按 - (vendor, vendor_model_id) 复用——已存在只更新描述，不重复建）。 -5. **定价挂接**：文档里的价格 → 在定价平台建 pricing_program（+timing YAML， - 价格照原文）并把 ppid 挂到模型（apply 不再写价格，模型表已无价格字段）。 + - `models[].sync_mode`：提交后需轮询的填 async + - `pricing.items[]`：每条带 factor/unit_price/unit/dimensions/doc_quote（文档原文定价句） + - `doc_url`：照抄 [出处URL] 行 +3. **确认**：把端点、协议、每个模型的能力/定价原文/出处摘要给用户确认后再落库。 +4. **落库**：`apply_llm_config` 传 **{"use_last_extract": true}**——取本会话锚定规格。 + 用户要求改名等只加 overrides 白名单覆盖项（如 {"overrides":{"vendor_name":"阿里云百炼"}}）。 + **绝对禁止把规格 JSON 复制/转述进 spec 参数——转述必编造结构（见方法论·防编造）。** + 幂等：供应商按名复用、模型按 (vendor, vendor_model_id) 复用。 +5. **定价**：`apply_model_pricing` 同样传 **{"use_last_extract": true}**（pricing+doc_url 已锚定）。 + 建定价方案+时序YAML并挂 ppid，出处URL+文档原文写入描述。 +6. **测试**：`test_model_call(model_name, prompt, params)` 真实调用走完整治理链。 + 前置：供应商账号已配 api_key（没配如实告知用户去补，禁止伪造结果）。 + 生成类模型 params 传 image_file/resolution/duration 等；返回 task_ref/usage/media（生成物本地URL）。 +7. **记账检查**：`check_model_accounting(task_ref)` 查三态 + 独立复算金额： + - accounted 且 amount_match=true → 全链通过，汇报金额 + - created → 等 60~120 秒再查（出账循环 60 秒一轮） + - failed → 按 reason/hint 处置（未映射产品→告知用户在产品管理导入产线模型） +8. **复核**：`platform_llm_status` 看模型/定价/供应商状态分布。 +9. **汇报**：配置/定价/测试/记账四段结果 + 出处 URL + 遗留事项（模板需人工核对项等）。 + +## 工具报错自救规则 +- 报「spec 结构不符/缺少 xxx」→ **不要改写结构重试**，改用 use_last_extract=true； + 本会话没锚定就重新走 fetch→extract（锚定是会话级的，跨会话不可见） +- 报「能力分类未登记」→ 如实转告用户需先加能力分类（人工评审门，不要绕过） +- 报「media_audit/runtime_note/需人工核对」警告 → 原样转告用户，不假装完成 ## 硬规则 @@ -106,6 +126,38 @@ t2i 出 `image`。模板不用为同一类能力写多套参数名。 真实可行动（repr 异常，含类型），重试记录进应用日志。 - 机构策略配置了 `utility_model_id` 则提取用辅助（便宜）模型，未配回落主链。 +## 方法论（2026-09-05 实战沉淀——怎么把这件事做对） + +### 防编造（最重要） +- **大 JSON 永不转述**：extract 输出的规格已锚定会话缓存，apply 只传 + `{"use_last_extract": true}` + 白名单 overrides。历史教训：让 LLM 把规格复制进 + spec 参数，三轮全编造出 vendor{}/api_profile{}/rate_limits{} 等契约外字段。 +- **价格零编造**：每条价格必须能对应到 doc_quote（文档原文逐字句）；文档没写 + 就没有，如实报告「文档未提供价格」。 +- **测试结果零伪造**：test_model_call 没跑成/没 api_key 就如实报，禁止描述 + 「应该能通」。判断标准：没有真实工具输出支撑的结论一律不许说。 + +### 验证闭环（每步都要证据） +- 落库后回读核验（查库确认字段值），不拿「写入没报错」当成功。 +- 定价后用真实引擎试算（check_model_accounting 的 recomputed_amount 就是独立 + 复算），金额与文档价格×用量手工对得上才算过。 +- 测试必须真实调用走完整治理链（门禁→上游→结算→流水），不接受纸面推演。 +- 记账检查等出账循环（60秒一轮）跑完再下结论；created 不是失败，是还没轮到。 + +### 排查套路（工具/链路报错时） +1. 先看报错原文定位是哪一环（门禁/上游/模板/记账），不猜。 +2. 模板类错误：把渲染结果打出来对照期望 JSON（历史案例：媒体数组收尾花括号 + 顺序错 `}}]`→`}]}`，渲染断裂在 column 361）。 +3. 记账类 failed：按 note 原因对号——未挂ppid→apply_model_pricing；未映射产品→ + 产品管理导入；金额不符→核对 usages 维度值与定价 YAML 的维度值是否逐字一致 + （480P≠480，字符串必须精确匹配）。 +4. 超时类：端点默认60秒，长任务传 _timeout（上限900）。 + +### 会话级隔离（缓存类操作的铁律） +- 一切会话态缓存（规格锚定等）键必须含 session_id（+user_id+pipeline_id）， + 三段缺一不可；无 session_id 拒绝缓存。跨会话数据永不可见——别的会话提取的 + 规格，本会话必须重新提取，不许「借用」。 + ## 验证 配置完成后调 `platform_llm_status` 复核模型/定价/供应商，把结果摘要回给用户。