超时不等于任务失败
本地等待超时,只说明本次观察结束。保存任务标识,后续继续查询已有任务,避免生成重复产物。

在企业内部,让 AI 发挥作用。
把 AI 能力,接入产品与业务。
从接口调用到工具连接,了解 AI 能力的接入方式。
关注大模型、基础框架,以及让智能持续运行的工程方法。
围绕产品、技术与交付,探索共同服务客户的方式。
面向开发者的框架、工具与示例,让技术可以被理解和复用。
来自壹典的动态、技术思考与产业观察。
关注教育、人才与知识分享,记录我们长期投入的方向。
理解输入、任务与结果之间的约定,让模型能力进入你的产品与工作流。
模型 API · MCP · ID Axis
接入不是从挑选参数开始,而是先确定业务需要的输入、产物和验收方式。一次设计生成、一次图生 3D 与一次指标生产,遵循相似的调用过程,拥有不同的结果标准。
按任务类型确定输入与输出。
从服务端创建请求,保存任务标识。
处理终态,校验产物,再进入业务。
以下路径、字段与状态用于说明接入方式,接入时以约定版本为准。示例域名不提供在线服务。
# Set the agreed base URL and a server-side credential first.
# The .invalid host is a placeholder, not a live service.
export IDENIFE_BASE_URL="https://api.example.invalid"
export IDENIFE_API_KEY="<server-side-credential>"
curl --request POST "$IDENIFE_BASE_URL/v1/tasks" \
--header "Authorization: Bearer $IDENIFE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"capability": "design.generate",
"input": {
"prompt": "Design a low, elegant electric GT in liquid silver.",
"constraints": {
"view": "front_three_quarter",
"material": "satin_metal"
}
},
"output": {
"format": "png"
}
}'任务被接受,只代表已进入处理流程。保存 task_id 后查询任务;收到 succeeded 再读取 result。
浏览器负责产品体验,业务服务负责身份、权限与调用。让前端调用你自己的业务接口,再由服务端连接模型能力,可以统一管理凭证与访问范围。
| 字段 / 约定 | 作用 | 处理方式 |
|---|---|---|
Authorization | 服务端身份 | 使用约定的凭证方式。凭证存放在服务端环境配置或密钥管理服务中。 |
Content-Type | application/json | 请求体按约定结构编码;文件上传与任务创建分开约定。 |
request_id | 请求追踪 | 将返回的请求标识关联到业务日志;记录状态和错误码,避免记录完整凭证与敏感输入。 |
正式接入还应明确:凭证如何签发与轮换、是否按项目授权、请求限额如何反馈。不要把演示中的 Bearer 写法理解为所有部署都采用同一套鉴权方式。
把“选哪种能力”“给什么条件”“需要什么产物”分开表达。业务服务可以复用任务管理逻辑,具体能力保留自己的输入校验与验收标准。
输入清楚,结果才有共同的判断依据。
| 能力标识 | 主要输入 | 结果形态 |
|---|---|---|
design.generate | 设计要求、材料与视角条件 | 概念图像与资产描述 |
image.to_3d | 输入图像资产、输出格式 | 三维网格与材质资产 |
data.metrics | 数据集引用、指标口径与维度 | 指标定义与结构化结果 |
图像与数据集通过约定的资产引用传入。文件大小、媒体类型、访问有效期与数据权限应在创建任务前检查;三维网格输出也不等同于参数化 CAD 实体。
查看各项模型与能力耗时任务适合拆成“提交、观察、取回结果”。页面不需要一直阻塞等待;任务标识连接业务记录、执行状态与最终产物。
已接收,等待处理
正在执行能力
产物已就绪
failed / cancelled失败与取消都是终态。保留原因与任务标识,由业务逻辑决定下一步;不要无条件重新提交。
// Illustrative server-side TypeScript; adapt to the agreed contract.
async function waitForTask(taskId: string, signal: AbortSignal) {
const baseUrl = process.env.IDENIFE_BASE_URL;
const key = process.env.IDENIFE_API_KEY;
if (!baseUrl || !key) throw new Error("Missing configuration");
for (let attempt = 0; attempt < 20; attempt++) {
signal.throwIfAborted();
const response = await fetch(
baseUrl + "/v1/tasks/" + encodeURIComponent(taskId),
{ headers: { Authorization: "Bearer " + key }, signal }
);
if (!response.ok) throw new Error("HTTP " + response.status);
const task = await response.json();
if (task.status === "succeeded") return task.result;
if (["failed", "cancelled"].includes(task.status)) {
throw new Error(task.error?.code ?? task.status);
}
await new Promise<void>((resolve, reject) => {
const stop = () => {
clearTimeout(timer);
reject(signal.reason);
};
const timer = setTimeout(() => {
signal.removeEventListener("abort", stop);
resolve();
}, 1500);
signal.addEventListener("abort", stop, { once: true });
});
}
throw new Error("Polling budget exceeded; preserve taskId");
}本地等待超时,只说明本次观察结束。保存任务标识,后续继续查询已有任务,避免生成重复产物。
限流时遵循服务端的等待提示并设置重试预算。创建请求是否可重试、是否支持幂等键,必须先由接口约定明确。
业务不应从一段自由文本里猜测任务是否完成。状态、产物与异常分开返回,才能让展示、归档、重试与人工处理各自有据可依。
{
"task_id": "task_demo_design_001",
"status": "succeeded",
"result": {
"artifacts": [
{
"id": "asset_demo_001",
"type": "image",
"format": "png",
"uri": "asset://demo/electric-gt.png"
}
],
"capability": "design.generate"
},
"request_id": "req_demo_001"
}400 / 422检查请求结构与业务条件401 / 403检查凭证与资源权限429等待后再试,控制并发5xx记录请求标识,按策略恢复HTTP 状态与重试语义参考 RFC 9110
模型 API 负责调用能力,MCP 负责以协议暴露工具和资源,ID Axis 负责组织推理与任务执行。三者可以组合,但不能互相替代。
本组示例以 MCP 2025-11-25 为协议参考。客户端先协商能力,再通过 tools/list 发现工具,通过 tools/call 提交参数;资源读取使用 resources/read。
工具输入应遵循其 Schema。工具执行错误与协议错误分别处理;工具描述不授予业务权限。
MCP · ToolsID Axis 统一组织多智能体推理、任务上下文、可用工具、执行预算与结果处理,让多步工作在明确边界内持续推进。
涉及业务写入时,应在执行层检查权限与必要确认。恢复任务前,需要区分“尚未执行”与“已执行但未收到结果”。
了解执行架构代码能返回结果,只是开始。正式接入需要对权限、异常、产物与观察方式形成共同约定,让能力在你的业务环境中持续工作。
服务端保管凭证,区分环境与业务权限;文件和结果的访问范围可控。
环境配置 · 权限清单创建、查询、超时与终态都有对应逻辑,页面关闭后仍能根据任务标识恢复查看。
状态转换 · 恢复流程区分输入问题与暂时性故障;重试设上限,避免不确定状态下重复创建有副作用的任务。
异常样例 · 重试策略验证格式、必要字段和资产可访问性;工业设计结果接入后续人工与工程校核流程。
验收规则 · 回归样例关联请求与任务标识,记录排队、执行和失败情况;约定保留周期与问题排查方式。
追踪日志 · 运行记录本页示例版本: illustrative-v1