docs(tasks): define app and backend VLM integration

This commit is contained in:
QiuSW
2026-07-27 09:22:03 +08:00
parent 45d4d11fe5
commit 45d1436033
12 changed files with 357 additions and 11 deletions
+24 -4
View File
@@ -115,6 +115,23 @@ evidence/ # 截图、步骤日志、脱敏和上传
1. **需求提取**:参考图 + 标题 + SKU -> 搜索词、类目、属性、置信度、警告。
2. **候选评估**:候选截图/文本 + 原始约束 -> 匹配项、缺失项、拒绝原因、建议分。
正式数据流固定为 `Android App -> 肉包后端 -> VLM Provider`。生产采购 App 不选择
provider、不保存供应商 API Key,也不直连模型地址;它只调用 task-scoped AI API。
ADMIN 在管理 Web 维护一个供新 execution 使用的默认 OpenAI 兼容 provider 版本。
第一版只支持 `/v1/chat/completions` 多模态协议。
provider 配置采用追加版本:保存名称、HTTPS Base URL、model、timeout、retry 上限、
启用状态和非秘密审计字段。API Key 使用环境提供的 256 bit master key,通过 AEAD
随机 nonce 加密;AAD 绑定 provider/version。读取接口只返回 `has_secret`,永不返回
明文或密文。execution 在第一次 AI 调用时绑定 config/provider/model/prompt version,
后续调用不随默认配置变化。master key 缺失或解密失败时真实调用安全失败,但管理任务、
领取和非 AI 功能继续可用。
后端 provider transport 禁止重定向,并在解析和连接时阻断 loopback、私网、链路
本地、组播、云 metadata 和 DNS rebinding;生产只允许 HTTPS。无 Key 的 loopback
HTTP 只属于显式 Debug mock,不能从生产管理 Web 创建。连接测试只使用内置脱敏文字
和测试图片,不读取订单或任务资产。
模型输出是不可信建议,必须通过 schema 和确定性校验:
- `sku`、`quantity` 和 `max_budget` 使用原始任务值;数量和预算不进入模型 prompt。
@@ -137,12 +154,15 @@ T-103 的模型响应只允许
输出并转人工。最终领域结果再由确定性代码补回原 SKU、数量、空预算、人工复核原因和
`provider/model/prompt_version/reference_image_sha256`。
技术探针每次点击最多发出一次 VLM 请求,不沿用通用 Agent 的重试循环。该结构化
HTTP 客户端关闭连接自动重试、HTTP/HTTPS 重定向,整体调用超时为 75 秒;协程取消
技术探针每次点击最多发出一次 VLM 请求,不沿用通用 Agent 的重试循环。T-207 后端
默认不重试,管理员最多允许一次仅限确定未收到响应的临时网络失败;schema、4xx 和
安全错误绝不重试。该结构化 HTTP 客户端关闭连接自动重试和 HTTP/HTTPS 重定向,
整体调用超时为 75 秒;协程取消
会取消底层 HTTP call,成功响应正文上限为 64 KiB,非成功响应不读取正文。
远程 provider 只允许 HTTPS;HTTP 仅允许无 API Key 的 `localhost`、`127.0.0.1`
或 `::1` 本机 mock。端点不得包含 userinfo、query 或 fragment。标题和 SKU 在进入
远程 provider 只允许 HTTPS;HTTP 仅允许 Debug 下无 API Key 的 `localhost`、
`127.0.0.1` 或 `::1` 本机 mock。端点不得包含 userinfo、query 或 fragment。标题
和 SKU 在进入
prompt 前分别限制为 2048 和 512 个 UTF-8 字节。JPEG 在调用前复核媒体类型、20 MiB
上限、魔数和 SHA-256,按声明长度一次分配并精确读取,Android 解码后最长边限制为
2048 px。请求和响应正文、Base64、API Key 不写普通日志;加密密钥存储不可用且存在