AI 时代的 API：大模型如何重塑接口设计

过去十年API 沿着 REST → GraphQL → gRPC 的路径演进核心始终围绕「结构化契约、精准调用、数据读写」展开。而大模型的普及正在打破这一范式接口不再只是数据的出入口更成为推理能力、生成能力与工具编排的载体。本文从三个核心维度拆解大模型时代 API 设计的底层变化并附可落地的工程实现。一、范式重构从「命令式调用」到「意图式交互」传统 API 的本质是「契约驱动」客户端必须严格按照接口文档传入指定字段、枚举值、分页参数差一个字符就会返回 400。这种设计在确定性系统里高效可靠但面对复杂业务场景时会导致参数爆炸、调用方学习成本高、版本迭代僵硬。大模型引入的第一个核心变化是让 API 从「接收精确指令」转向「理解用户意图」。接口不再强制要求结构化输入而是通过自然语言解析层将模糊需求映射为内部可执行的结构化参数。设计思路外层暴露自然语言入口接收用户的非结构化描述中间层通过大模型做意图识别、参数提取、合法性校验内层仍然调用原有业务 RPC/REST 接口保证执行确定性代码实现意图解析 API 封装fromfastapiimportFastAPI,HTTPExceptionfrompydanticimportBaseModelimportopenaiimportjson appFastAPI()classIntentRequest(BaseModel):query:struser_id:strclassOrderQueryParams(BaseModel):order_id:strNonestatus:strNonestart_date:strNoneend_date:strNonepage:int1page_size:int20defparse_intent_with_llm(query:str)-OrderQueryParams:用大模型从自然语言中提取订单查询参数promptf 从用户查询中提取订单查询参数输出严格的JSON格式字段如下 - order_id: 订单号提取不到则为null - status: 订单状态枚举值 pending/paid/shipped/completed/cancelled - start_date, end_date: 日期范围格式 YYYY-MM-DD提取不到则为null - page: 页码默认1 - page_size: 每页条数默认20 用户查询{query}只输出JSON不要其他文字。 responseopenai.ChatCompletion.create(modelgpt-3.5-turbo,messages[{role:user,content:prompt}],temperature0)try:datajson.loads(response.choices[0].message.content.strip())returnOrderQueryParams(**data)exceptException:raiseHTTPException(status_code400,detail无法解析查询意图)app.post(/api/v1/orders/query)defquery_orders(request:IntentRequest):意图式订单查询接口支持自然语言输入paramsparse_intent_with_llm(request.query)# 下游仍然调用传统的结构化订单查询接口# result order_service.query(params, request.user_id)return{parsed_params:params.dict(),message:参数解析完成已转发至业务接口,query:request.query}这种设计的价值在于业务侧无需维护数十个面向不同场景的细分接口一个意图入口即可覆盖绝大多数查询需求前端也无需再做复杂的表单校验和参数拼接直接透传用户输入即可。二、能力升级从「数据读写」到「生成与推理」传统 API 的能力边界是 CRUD创建、读取、更新、删除。而大模型 API 带来了两类全新能力生成式输出与函数调用Function Calling。与之对应接口设计必须解决两个工程问题流式响应、工具扩展。1. 流式响应成为标配生成式内容文本、代码、结构化数据通常需要几秒到几十秒的生成时间。传统的一次性响应会导致前端长时间空白、超时风险高、用户体验差。SSEServer-Sent Events成为大模型 API 的标准交付方式。fromfastapi.responsesimportStreamingResponseimporttimeapp.post(/api/v1/generate/report)defgenerate_report(topic:str):流式生成业务报告defreport_generator():full_promptf请生成一份关于{topic}的数据分析报告分三个部分现状、问题、建议。streamopenai.ChatCompletion.create(modelgpt-3.5-turbo,messages[{role:user,content:full_prompt}],streamTrue)forchunkinstream:ifchunk.choices[0].delta.content:yieldfdata:{chunk.choices[0].delta.content}\n\nyielddata: [DONE]\n\nreturnStreamingResponse(report_generator(),media_typetext/event-stream)2. Function Calling让 API 具备「自我扩展」能力大模型不再只是输出内容还可以根据用户意图决定调用哪些后端工具。API 设计从「固定功能集合」转向「能力插件化」。接口层需要维护工具注册表、参数校验、执行沙箱。importinspectfromtypingimportDict,Callable# 工具注册表tool_registry:Dict[str,Callable]{}defregister_tool(name:str,description:str,parameters:dict):工具注册装饰器defdecorator(func):tool_registry[name]{func:func,definition:{name:name,description:description,parameters:parameters}}returnfuncreturndecorator# 注册具体工具register_tool(nameget_user_balance,description查询用户账户余额,parameters{type:object,properties:{user_id:{type:string,description:用户ID}},required:[user_id]})defget_user_balance(user_id:str):# 实际业务逻辑查数据库、调账户服务return{user_id:user_id,balance:12580.68,currency:CNY}defexecute_tool(tool_name:str,arguments:dict):执行工具调用iftool_namenotintool_registry:raiseValueError(f未知工具:{tool_name})tooltool_registry[tool_name]returntool[func](**arguments)# 使用时将所有工具定义传给大模型由模型决策调用哪个工具defchat_with_tools(user_query:str):tools_def[{type:function,function:t[definition]}fortintool_registry.values()]responseopenai.ChatCompletion.create(modelgpt-3.5-turbo-0613,messages[{role:user,content:user_query}],toolstools_def)messageresponse.choices[0].messageifmessage.tool_calls:forcallinmessage.tool_calls:argsjson.loads(call.function.arguments)resultexecute_tool(call.function.name,args)return{tool_called:call.function.name,result:result}return{answer:message.content}这种架构下新增业务能力不再需要新增 API 路由只需注册一个工具函数即可。大模型会自动判断何时调用、如何传参接口的扩展性得到数量级提升。三、架构演进从「无状态请求」到「有状态 Agent」传统 API 是无状态的每次请求独立上下文靠 Token、Session 维持轻量关联。而大模型驱动的业务场景天然是多轮对话、多步推理、多工具协作的这要求 API 从「单次请求处理」进化为「有状态的 Agent 编排」。核心设计要点会话状态持久化每轮对话的历史消息、工具调用结果、中间变量都需要存储状态机驱动执行思考 → 工具调用 → 结果回填 → 再思考 → 最终输出中断与续跑能力长任务支持暂停、恢复、人工介入代码实现极简 Agent API 架构importuuidfromtypingimportList,Dict# 内存版会话存储生产环境可用 Redis/MySQLsession_store:Dict[str,List[Dict]]{}app.post(/api/v1/agent/chat)defagent_chat(session_id:strNone,message:str):有状态 Agent 对话接口# 初始化或恢复会话ifnotsession_id:session_idstr(uuid.uuid4())session_store[session_id][{role:system,content:你是一个智能业务助手可以调用工具帮助用户。}]messagessession_store[session_id]messages.append({role:user,content:message})# 第一轮模型决策是否调用工具tools_def[{type:function,function:t[definition]}fortintool_registry.values()]responseopenai.ChatCompletion.create(modelgpt-3.5-turbo-0613,messagesmessages,toolstools_def)assistant_msgresponse.choices[0].message messages.append(assistant_msg)# 循环执行工具调用直到无需调用whileassistant_msg.tool_calls:fortool_callinassistant_msg.tool_calls:func_nametool_call.function.name func_argsjson.loads(tool_call.function.arguments)resultexecute_tool(func_name,func_args)# 将工具结果回填到对话历史messages.append({role:tool,tool_call_id:tool_call.id,name:func_name,content:json.dumps(result,ensure_asciiFalse)})# 再次调用模型基于工具结果生成最终回答second_responseopenai.ChatCompletion.create(modelgpt-3.5-turbo-0613,messagesmessages,toolstools_def)assistant_msgsecond_response.choices[0].message messages.append(assistant_msg)# 保存会话状态session_store[session_id]messagesreturn{session_id:session_id,answer:assistant_msg.content,rounds:len([mforminmessagesifm[role]user])}大模型 API 的设计原则总结下来大模型重塑 API 并不是要推翻 REST、gRPC 等现有体系而是在其之上叠加一层「智能交互层」。底层业务接口仍然追求稳定、高效、结构化上层面向用户的接口则走向自然化、生成化、Agent 化。三个核心方向可以作为团队演进的路线图输入层升级从结构化参数到意图解析降低接入成本能力层扩展从数据 CRUD 到生成工具调用拓宽接口边界架构层进化从无状态请求到有状态 Agent支持复杂多步任务工程落地时不必一步到位可以从某一个场景切入比如客服查询、报表生成先验证意图解析或流式输出的价值再逐步向完整的 Agent 架构演进。