把模型能力接入业务的第一步通常很简单前端提交自然语言服务端调用模型再把文本回答返回。这种接口适合问答、摘要和短文本生成却不适合所有需求。例如“说明昨晚告警的原因”可以在一次请求中完成“分析一周日志并形成报告”可能耗时较长“根据分析结果重启服务”则不仅是推理问题还涉及身份、权限、审批、幂等和审计。如果这些场景都塞进同步接口常见后果包括客户端超时后无法确认任务是否继续执行、重复点击导致重复提交、模型文本被误当作可直接执行的命令以及无法回答“谁在何时批准了什么操作”。更稳妥的做法不是把模型当作拥有业务权限的执行者而是把它定位为受约束的决策输入模型可解释意图、生成计划、归纳证据业务服务负责校验、授权和执行。围绕这一边界可以将 API 分成三层。三层边界响应、作业与执行第一层同步响应 API同步接口面向预计能在请求生命周期内完成的只读任务例如知识问答、参数解释、告警摘要。它应返回明确的业务对象而不是把上游模型的原始响应直接透传给调用方。一个合适的响应至少包括请求标识、结果文本、使用的策略标识以及可选的证据引用。即使暂时没有检索系统也应预留citations字段以免未来修改响应契约。第二层异步作业 API涉及多份数据、批量分析、文件处理或外部工具调用的任务应通过创建作业来处理。客户端获得job_id后轮询、订阅回调或从消息通道接收状态变化。关键点是将“创建请求”和“实际处理”拆开POST /v1/jobs只负责校验和持久化工作进程负责后续执行。这样服务重启、客户端断连与处理重试都不会天然等同于任务丢失。建议将状态控制为有限集合queued - running - succeeded - failed - waiting_approval - approved - running - rejected状态迁移必须由服务端控制。尤其不要允许客户端把任意作业直接改为approved或succeeded。第三层受控执行 API执行 API 处理的是具有副作用的动作例如提交变更、重启受管服务、创建工单或调整配置。它不应接受一段自由文本命令而应只接受经过验证的动作名称和结构化参数。模型可以提出计划restart_service、目标服务名、原因和风险提示但服务端必须基于动作白名单、资源范围和调用者角色重新验证。对于高风险动作还应要求独立审批。这一层的核心原则是模型输出不是授权凭证结构化校验也不是权限校验。前者防止语义漂移后者防止越权两者都不可省略。先定义稳定的数据契约以下示例使用 FastAPI 展示接口形态。示例中的内存存储仅用于说明流程生产环境应换成具备持久化和并发控制能力的数据库或队列。fromenumimportEnumfromuuidimportuuid4frompydanticimportBaseModel,FieldfromfastapiimportFastAPI,Header,HTTPException appFastAPI()jobs:dict[str,dict]{}classJobType(str,Enum):incident_analysisincident_analysisweekly_reportweekly_reportclassCreateJobRequest(BaseModel):type:JobType scope:strField(min_length1,max_length200)request_id:strField(min_length8,max_length80)classExecutionRequest(BaseModel):action:strresource:strreason:strField(min_length1,max_length1000)approval_id:strapp.post(/v1/jobs,status_code202)defcreate_job(body:CreateJobRequest,x_user_id:strHeader()):forjobinjobs.values():ifjob[request_id]body.request_idandjob[user_id]x_user_id:return{job_id:job[id],status:job[status],reused:True}job_idstr(uuid4())jobs[job_id]{id:job_id,request_id:body.request_id,user_id:x_user_id,type:body.type,scope:body.scope,status:queued}return{job_id:job_id,status:queued,reused:False}app.get(/v1/jobs/{job_id})defget_job(job_id:str,x_user_id:strHeader()):jobjobs.get(job_id)ifnotjoborjob[user_id]!x_user_id:raiseHTTPException(status_code404,detailjob not found)returnjobrequest_id是调用方提供的幂等键。在真实系统中它应与用户或租户标识建立唯一约束而不能只依赖进程内遍历。对于网络超时客户端使用相同request_id重试服务端返回已创建的作业而非再次入队。把模型接入限制在“计划生成”环节模型接口应由专门的适配层调用避免路由处理函数散落供应商格式、密钥读取和重试逻辑。配置以环境变量注入密钥不进入源码、镜像层或日志。importosimporthttpx MODEL_BASE_URLos.environ[MODEL_BASE_URL]MODEL_API_KEYos.environ[MODEL_API_KEY]MODEL_NAMEos.environ[MODEL_NAME]asyncdefgenerate_plan(incident:dict)-dict:payload{model:MODEL_NAME,messages:[{role:system,content:仅返回 JSONsummary、evidence、proposed_action、parameters。不得执行任何操作。},{role:user,content:str(incident)}]}headers{Authorization:fBearer{MODEL_API_KEY}}asyncwithhttpx.AsyncClient(timeout30)asclient:responseawaitclient.post(f{MODEL_BASE_URL}/chat/completions,jsonpayload,headersheaders)response.raise_for_status()returnresponse.json()若团队需要通过兼容接口统一不同模型接入可将 HaerAPIhttps://www.haerapi.com作为候选接入对象之一并在接入前核对其当前接口格式、认证方式、地域处理要求和故障处置方案。无论使用哪一种模型服务适配层都应完成三件事设置连接与总超时为可安全重试的调用定义边界记录脱敏后的请求关联标识、模型配置标识和错误类别。不要默认所有失败都能重试认证失败、参数错误与策略拒绝通常需要直接返回明确错误而非无限重放。将计划变成受控动作下面的示例说明执行前的最小校验。真正的资源权限还应由目标系统或统一授权系统复核。ALLOWED_ACTIONS{restart_service,create_ticket}app.post(/v1/executions,status_code202)defcreate_execution(body:ExecutionRequest,x_user_id:strHeader()):ifbody.actionnotinALLOWED_ACTIONS:raiseHTTPException(status_code400,detailunsupported action)ifnotapproval_is_valid(body.approval_id,x_user_id,body.action,body.resource):raiseHTTPException(status_code403,detailvalid approval required)execution_idstr(uuid4())append_audit_event({event:execution_requested,execution_id:execution_id,actor:x_user_id,action:body.action,resource:body.resource,approval_id:body.approval_id})enqueue_execution(execution_id,body.model_dump())return{execution_id:execution_id,status:queued}approval_is_valid至少应检查审批是否未过期、审批人是否有权限、审批内容是否与当前动作及目标资源一致。只校验“存在一个 approval_id”是不够的否则同一个审批可能被挪用于不同资源。可执行的落地顺序列出所有模型驱动场景按“只读回答、长耗时处理、有副作用动作”归类。先定义三类 API 的请求、响应、错误码和状态机再编写调用模型的代码。为创建作业和创建执行分别设置幂等键并在持久化层建立唯一约束。建立动作白名单和参数模式将自由文本限制在说明字段不能成为执行指令。为高风险动作加入审批状态并让审批内容绑定动作、资源、有效期和申请人。记录审计事件请求者、作业状态变化、计划摘要、审批标识和执行结果。日志中应避免记录密钥、完整提示词中的敏感字段或原始业务数据。针对超时、重复提交、工作进程中断、审批过期和目标系统拒绝分别编写测试用例。常见问题为什么不让模型直接调用运维工具模型输出存在不确定性且上下文可能包含不可信文本。直接授予工具权限会把“理解用户意图”和“决定是否有权执行”混为一谈。将模型限制为生成结构化计划可让授权逻辑保持确定、可测试和可审计。异步作业完成后如何通知客户端可采用轮询、Webhook、服务端事件或消息系统具体取决于客户端类型和基础设施。无论采用何种通知方式GET /v1/jobs/{id}都应是权威状态来源通知可能重复、延迟或丢失不能作为唯一事实。JSON 格式的模型输出是否可靠不应假定可靠。服务端需要进行 JSON 解析、字段校验、枚举校验和长度限制校验失败时可在限定次数内请求修复或转为人工处理。修复次数与重试策略应由团队按成本和风险设定不能把无限重试当成兜底。审批后模型重新分析原审批还有效吗若重新分析改变了动作、资源、参数或风险说明原审批通常不应自动复用。可对待执行计划计算规范化摘要或哈希并将其写入审批记录执行时比对一致性。具体哈希方案需结合字段稳定性和合规要求设计。总结面向模型能力的 API 设计重点不在于把一次对话调用包装成 HTTP 路由而在于区分响应、任务与执行三种责任。同步层追求清晰交互异步层解决长任务的可恢复性执行层保证权限、审批和审计不被模型输出绕过。当模型被放在受控计划生成的位置系统即使更换模型、调整提示词或扩展工具也能保持业务边界稳定。先固定状态机、数据契约和授权规则再优化模型效果通常比从“让模型直接做更多事”开始更容易形成可维护的工程体系。