这次我们来看一个关于大模型工具调用范式转变的研究发现。核心结论很直接在测试的14个主流大模型中有11个在“代码优先”的工具调用方式下表现更优超过了传统的“JSON模式”调用。这意味着如果你正在开发基于大模型的AI代理或助手并且需要模型调用外部工具如搜索、计算、API那么用代码尤其是Python来描述工具和使用方式可能比精心设计JSON Schema更有效。这个发现对开发者来说很实用。它不涉及复杂的模型训练或高昂的硬件成本而是一种使用策略的优化。无论你用的是云端API如GPT-4、Claude还是本地部署的开源模型都可以尝试这种方法来提升工具调用的准确性和可靠性。本文将重点拆解“代码优先”是什么、为什么有效、以及如何在你自己的项目中实践包括环境准备、代码示例和效果对比。1. 核心能力速览能力项说明研究核心对比大模型工具调用的两种范式“代码优先” vs “JSON模式”。关键结论在14个被测模型中11个模型在“代码优先”范式下工具调用能力更优。技术本质将工具的描述名称、参数、说明和使用逻辑用结构化的代码如Python类与函数而非纯JSON格式来定义和提示。适用模型广泛适用于具备代码理解能力的文本生成大模型包括闭源和开源模型。硬件门槛无特殊要求。性能提升取决于模型本身的推理能力不增加额外计算负担。启动方式非独立工具是一种提示工程Prompt Engineering和API调用策略。接口能力可直接集成到现有的大模型API调用流程中修改提示词和少量预处理逻辑即可。批量任务支持。可应用于需要自动化、批量进行工具调用的AI代理场景。适合场景AI Agent开发、复杂任务自动化、需要稳定调用外部API或函数的应用。2. 适用场景与使用边界“代码优先”的工具调用策略主要适用于以下场景和人群适合谁AI Agent/助手开发者正在构建能够自动调用搜索、计算、数据库查询等工具的智能体。提示工程师需要优化大模型在复杂任务中的表现特别是涉及多步骤推理和工具使用的场景。全栈/后端工程师希望将大模型能力更可靠地集成到现有业务系统和工作流中。能解决什么问题工具调用不准模型错误理解JSON Schema中的参数要求导致调用失败或参数错误。复杂逻辑表述困难用JSON难以清晰表达工具使用的条件、循环或异常处理逻辑。提示词冗长低效复杂的JSON结构使得提示词臃肿可能干扰模型的核心推理。提升开发体验对于开发者而言用熟悉的代码Python来定义工具比编写和调试复杂的JSON更直观。不适合什么场景模型完全不懂代码如果使用的模型对代码理解能力极弱“代码优先”将失去优势。极度简单的工具调用仅有一两个固定参数的工具传统JSON模式可能已足够简洁。严格受限的上下文长度代码描述可能比精简的JSON占用更多Token在上下文窗口非常紧张时需权衡。合规与边界该方法仅改变与模型交互的“描述方式”不涉及模型本身的黑盒操作或数据窃取。在定义工具时需确保工具本身的用途合法合规避免描述可用于攻击、侵权或破坏系统的功能。应用于生产环境前应在测试环境中充分验证其稳定性和准确性。3. 环境准备与前置条件实施“代码优先”工具调用不需要特殊的部署环境它主要依赖于你的现有大模型服务。以下是通用的准备清单大模型访问权限闭源模型确保你拥有如 OpenAI GPT系列、Anthropic Claude、Google Gemini 等模型的API Key和有效的调用权限。开源本地模型确保你的本地或自有服务器已成功部署了如 Llama 3、Qwen、DeepSeek 等支持代码理解能力的模型并配置好推理接口如 OpenAI 兼容的 API 端点。开发环境Python 环境推荐 Python 3.8。这是“代码优先”的核心因为我们将用Python代码作为工具描述语言。包管理工具pip或conda。代码编辑器VS Code, PyCharm 等。必要的Python库大模型SDK根据你使用的模型选择例如openai,anthropic,litellm等。基础工具包requests(用于调用外部API类工具)、json、re等。一个清晰的测试目标准备一个具体的、需要调用工具才能完成的任务。例如“查询北京今天的天气然后计算如果下雨我开车和坐地铁哪种方式更省时间”4. “代码优先”范式详解与部署思路“部署”在此处指的是将这种范式集成到你的项目代码库中。核心是重构你与模型交互的提示词Prompt和工具定义部分。4.1 传统JSON模式回顾在OpenAI的Function Calling或类似机制中我们通常以JSON数组的形式向模型描述工具。[ { type: function, function: { name: get_weather, description: 获取指定城市的天气信息, parameters: { type: object, properties: { location: { type: string, description: 城市名称如北京 }, date: { type: string, description: 日期格式YYYY-MM-DD默认为今天 } }, required: [location] } } } ]然后将这个JSON数组作为tools参数传递给模型API。模型需要理解这个JSON结构并选择调用。4.2 “代码优先”模式定义“代码优先”模式放弃将工具定义为纯粹的JSON Schema而是将其编写成一段结构化的、注释清晰的伪代码或真实代码片段并放入系统提示词System Prompt或用户消息中。核心思路你不是在告诉模型“有一个工具它的JSON结构长这样”而是在告诉模型“这里有一些可用的Python函数它们的签名和功能如下你可以在思考中决定是否及如何调用它们”。下面是一个“代码优先”的工具定义示例# 可用工具定义 (Available Tools Definition) # 你可以在思考中决定调用以下函数来获取信息或执行操作。 # 调用时请遵循函数的参数说明。 import datetime from typing import Optional def get_weather(location: str, date: Optional[str] None) - str: 获取指定城市的天气信息。 Args: location (str): 城市名称例如“北京”、“上海”。 date (Optional[str], optional): 查询日期格式为 ‘YYYY-MM-DD‘。默认为今天。 Returns: str: 返回天气情况的文本描述例如“北京2023-10-27晴15-22°C”。 Example: get_weather(“北京”) “北京2023-10-27晴15-22°C” get_weather(“上海”, “2023-10-28”) “上海2023-10-28多云18-24°C” # 函数体内部实现对外部API的调用此部分对模型不可见仅作说明。 # 实际调用时模型只需生成包含函数名和参数的代码块或指令。 pass def calculate_travel_time(distance_km: float, transport_mode: str) - float: 根据距离和交通方式计算行程时间。 Args: distance_km (float): 距离单位公里。 transport_mode (str): 交通方式可选 ‘driving‘, ‘subway‘, ‘biking‘。 Returns: float: 预计时间单位分钟。 Example: calculate_travel_time(10, “driving”) 25.5 # 内部实现逻辑... pass4.3 如何集成到API调用中你不需要真的让模型去执行这段Python代码除非你构建了代码执行环境。通常的做法是将上述代码文本作为系统提示词的一部分让模型在上下文中知晓这些“可用函数”。在用户提问后期望模型在回复中以清晰的格式如标记代码块输出它想要调用的函数及参数。你的后端程序解析模型的回复提取出函数名和参数。你的后端程序真正执行对应的函数调用真实API或进行计算。将函数执行的结果作为新的上下文信息再次发送给模型让模型基于结果生成最终回答给用户。这个过程与JSON模式的“Function Calling”在流程上相似但交互的“语言”从JSON变成了更自然的代码注释和类型提示。5. 功能测试与效果验证我们设计一个测试任务来对比两种模式的效果。任务“帮我查一下杭州明天下午是否适合户外跑步如果下雨推荐一个室内的健身活动。”5.1 测试环境搭建假设我们使用 OpenAI 的gpt-4o-mini模型进行测试。import openai import json import re # 设置你的API Key client openai.OpenAI(api_keyyour-api-key-here) # 真实工具函数模拟 def get_weather(location: str, date: str None) - str: # 模拟API返回 weather_data { 杭州: { 2024-05-28: 小雨18-24°C, 2024-05-29: 多云20-28°C } } date date or 2024-05-29 return f{location}{date}{weather_data.get(location, {}).get(date, 数据缺失)} def recommend_indoor_activity(weather_condition: str) - str: if 雨 in weather_condition: return 推荐室内活动瑜伽、健身环大冒险、跳绳或室内游泳。 else: return 天气良好户外跑步更佳。5.2 JSON模式测试我们按照传统方式定义工具并调用。def test_json_mode(): tools_json [ { type: function, function: { name: get_weather, description: 获取城市天气, parameters: { type: object, properties: { location: {type: string}, date: {type: string} }, required: [location] } } }, { type: function, function: { name: recommend_indoor_activity, description: 根据天气情况推荐室内活动, parameters: { type: object, properties: { weather_condition: {type: string} }, required: [weather_condition] } } } ] response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 帮我查一下杭州明天下午是否适合户外跑步如果下雨推荐一个室内的健身活动。}], toolstools_json, tool_choiceauto, ) # 解析模型返回的工具调用请求 tool_calls response.choices[0].message.tool_calls print(JSON模式 - 模型返回的工具调用:, json.dumps([tc.function.model_dump() for tc in tool_calls], indent2, ensure_asciiFalse)) # 执行测试 test_json_mode()预期结果与判断模型应正确返回一个调用get_weather的请求参数包含location: “杭州”。成功的关键是参数准确且能根据返回的天气结果决定是否继续调用第二个工具。5.3 代码优先模式测试我们将工具定义以代码注释形式放入系统提示词。def test_code_first_mode(): system_prompt 你是一个智能助手可以调用以下Python工具来帮助用户。请根据用户问题思考是否需要调用工具并在回复中清晰地写出你要调用的代码。 可用工具 python def get_weather(location: str, date: str None) - str: \ 获取指定城市的天气信息。 Args: location: 城市名如‘杭州‘。 date: 日期格式‘YYYY-MM-DD‘默认明天。 Returns: 天气描述字符串。 \ pass def recommend_indoor_activity(weather_condition: str) - str: \ 根据天气情况推荐室内活动。 Args: weather_condition: 天气描述字符串应包含‘晴‘、‘雨‘、‘多云‘等关键词。 Returns: 活动推荐字符串。 \ pass当你决定调用工具时请在你的回复中用以下格式包裹调用代码# 工具调用 result get_weather(‘杭州‘, ‘2024-05-29‘) # 调用结束我会执行你写的代码并将结果告诉你。请基于结果进行下一步分析或回答。 response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: system_prompt}, {role: user, content: 帮我查一下杭州明天下午是否适合户外跑步如果下雨推荐一个室内的健身活动。} ], ) assistant_reply response.choices[0].message.content print(代码优先模式 - 模型回复原文:) print(assistant_reply) print(\n *50) # 尝试从回复中提取代码块 code_block_pattern rpython\n(.*?)\n matches re.findall(code_block_pattern, assistant_reply, re.DOTALL) if matches: print(提取到的代码块:) for code in matches: print(code) else: # 如果没有标准代码块查找包含函数调用的行 print(未找到标准代码块尝试查找函数调用行...) for line in assistant_reply.split(\n): if get_weather in line: print(line)执行测试test_code_first_mode()**预期结果与判断**模型应在回复中生成类似 get_weather(‘杭州‘, ‘2024-05-29‘) 的代码调用。成功的关键是模型生成的调用语法正确参数格式、函数名并且能根据你的后续提示模拟执行结果进行逻辑判断决定是否调用第二个函数。 ### 5.4 效果对比验证点 运行上述测试后可以从以下几个维度对比效果 1. **调用准确性**模型是否选择了正确的工具参数是否完整、格式是否正确 2. **逻辑连贯性**在“代码优先”模式下模型是否更倾向于在回复中展示其“思考过程”例如“我需要先获取天气然后判断...”这有助于调试。 3. **复杂任务处理**对于需要多个工具顺序调用或有条件分支的任务“代码优先”的描述是否让模型更容易理解执行流程 4. **抗干扰性**在提示词中加入一些无关信息时哪种模式下的模型更不容易被干扰 根据原研究结论在多数模型上“代码优先”模式在这些维度上表现更稳健。 ## 6. 接口API与批量任务集成 “代码优先”范式可以无缝集成到现有的AI Agent框架或批量任务处理系统中。 ### 6.1 构建一个简单的代码优先Agent服务 下面是一个使用FastAPI构建的简易服务端示例它接收用户问题采用“代码优先”提示词与模型交互解析模型输出的代码执行对应工具并返回最终结果。 python # app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel import openai import re import sys from typing import Dict, Any import json app FastAPI() client openai.OpenAI(api_keyyour-api-key) # 工具函数库 (实际实现) tool_lib { “get_weather”: get_weather, # 引用前面定义的函数 “recommend_indoor_activity”: recommend_indoor_activity, “calculate”: lambda x, y, op: eval(f”x {op} y”), # 示例计算工具 } # 代码优先的系统提示词模板 CODE_FIRST_SYSTEM_PROMPT “”” 你是一个AI助手可以调用以下Python工具 python {工具定义代码}请根据用户问题如果需要调用工具就在回复中写出完整的Python调用代码块用python包裹。我会执行它。 “””class UserQuery(BaseModel): question: str model: str “gpt-4o-mini”def extract_and_execute_code(reply: str, context: Dict[str, Any]) - Any: “””从模型回复中提取并执行Python代码安全地处理。””” code_pattern r”python\n(.*?)\n” matches re.findall(code_pattern, reply, re.DOTALL) if not matches: return None code_to_run matches[0] # 非常关键在实际生产环境中这里必须使用沙箱或严格的白名单机制来执行代码防止任意代码执行。 # 此处为演示仅做简单匹配执行。 for func_name, func in tool_lib.items(): if func_name in code_to_run: # 使用正则表达式提取参数这是一个简化示例生产环境需要更严谨的解析器 # 例如匹配 get_weather(‘杭州‘) arg_pattern rf”{func_name}((.*?))” arg_match re.search(arg_pattern, code_to_run) if arg_match: args_str arg_match.group(1) # 简易参数解析实际应用建议使用ast.literal_eval try: args eval(f”({args_str},)”) if args_str else () result func(*args) return result except Exception as e: return f”工具执行错误: {e}” return “未找到可执行的有效工具调用。”app.post(“/ask”) async def ask_agent(query: UserQuery): # 1. 构建包含工具定义的完整提示词 tools_code “”” def get_weather(location: str, date: str None) - str: \“\“\“获取天气\“\“\“ pass def calculate(a: float, b: float, operator: str) - float: \“\“\“计算operator in [‘‘, ‘-‘, ‘*‘, ‘/‘]\“\“\“ pass “”” system_msg CODE_FIRST_SYSTEM_PROMPT.format(工具定义代码tools_code)# 2. 调用大模型 try: response client.chat.completions.create( modelquery.model, messages[ {“role”: “system”, “content”: system_msg}, {“role”: “user”, “content”: query.question} ], temperature0.1, ) assistant_reply response.choices[0].message.content # 3. 提取并执行代码 tool_result extract_and_execute_code(assistant_reply, {}) # 4. 将结果返回给用户或可以再次喂给模型生成最终回复 return { “original_reply”: assistant_reply, “tool_execution_result”: tool_result, “final_answer”: f”根据工具执行结果‘{tool_result}‘答案是…” if tool_result else assistant_reply } except Exception as e: raise HTTPException(status_code500, detailstr(e))ifname “main”: import uvicorn uvicorn.run(app, host“0.0.0.0”, port8000)启动服务后即可通过 POST /ask 接口进行问答。 ### 6.2 批量任务处理 对于批量处理任务列表可以构建一个任务队列。 python # batch_processor.py import asyncio import aiohttp import json from typing import List async def process_batch_questions(questions: List[str], api_url: str “http://localhost:8000/ask): “””并发处理一批问题。””” async with aiohttp.ClientSession() as session: tasks [] for q in questions: task asyncio.create_task( session.post(api_url, json{“question”: q, “model”: “gpt-4o-mini”}) ) tasks.append(task) responses await asyncio.gather(*tasks, return_exceptionsTrue) results [] for q, resp in zip(questions, responses): if isinstance(resp, Exception): results.append({“question”: q, “error”: str(resp)}) else: result_data await resp.json() results.append({“question”: q, “result”: result_data}) return results # 示例批量问题 batch_questions [ “杭州明天天气如何”, “计算一下 125 乘以 38 等于多少”, “如果明天下雨上海适合去公园吗” ] # 运行批量处理需在异步环境中 # asyncio.run(process_batch_questions(batch_questions))7. 资源占用与性能观察“代码优先”范式本身不增加额外的显存或算力消耗其性能影响主要体现在以下方面Token消耗代码描述通常比等价的、高度压缩的JSON Schema占用更多的Token。这会导致单次请求成本略微增加对于按Token收费的API成本会上升。有效上下文长度减少在有限的上下文窗口内能容纳的历史对话轮次或工具数量会变少。观察方法在API响应中查看usage.prompt_tokens字段对比两种提示词模式下的差异。推理时间更长的提示词可能略微增加模型的推理时间Latency但这通常不是瓶颈。主要瓶颈仍是模型自身的计算速度。开发与维护成本优势对于开发者用熟悉的代码和类型提示来定义工具可读性和可维护性更高调试更方便。劣势需要编写一个轻量级的“代码解释器”或“调用提取器”来解析模型的输出这比直接使用SDK内置的tool_calls解析要复杂一些。建议在决定采用“代码优先”前可以在你的典型任务上做一个简单的A/B测试权衡Token增加带来的成本/上下文压力与工具调用准确率提升带来的收益。8. 常见问题与排查方法问题现象可能原因排查方式解决方案模型不生成代码调用1. 系统提示词不够清晰。2. 模型能力不足以理解代码指令。3. 温度temperature参数过高导致输出随机。1. 检查系统提示词确保指令明确如“请写出调用代码”。2. 换用代码能力更强的模型如GPT-4, Claude 3, DeepSeek-Coder。3. 将temperature设为较低值如0.1或0。优化提示词加入更具体的输出格式要求。使用思维链Chain-of-Thought提示引导模型先思考再写代码。代码调用格式解析失败1. 模型输出的代码格式不统一如无代码块、注释位置不同。2. 正则表达式或解析逻辑有缺陷。1. 打印出模型的原始回复检查其格式。2. 测试解析函数是否能处理多种常见输出变体。1. 在提示词中严格规定输出格式例如“必须使用python代码块包裹”。2. 使用更健壮的解析库如ast模块配合安全评估或直接让模型以指定JSON格式输出调用指令。工具执行参数错误1. 模型生成的参数类型错误如字符串没加引号。2. 参数数量或顺序与函数定义不符。1. 检查提取到的参数字符串。2. 对比工具函数的签名。1. 在工具定义的注释中提供明确的类型和示例。2. 在解析后、执行前加入参数验证和类型转换逻辑。多轮对话中工具调用混乱1. 历史消息过长模型遗忘工具定义。2. 多轮后模型输出格式漂移。1. 检查上下文Token数量。2. 观察历史消息中工具定义的完整性。1. 在每轮或关键轮次将工具定义再次附加到系统提示词中。2. 实现对话状态管理在需要调用工具的新一轮开始时重置或强化工具定义提示。本地小模型效果差7B/13B等参数较小的本地模型代码理解能力有限。测试模型在简单代码生成任务上的表现。1. 考虑使用专门微调过的代码模型。2. 简化工具定义使用极其简单的伪代码。3. 回退到JSON模式或更简单的文本指令模式。9. 最佳实践与使用建议从简单开始先用一个工具、一个简单任务验证“代码优先”在你的目标模型上是否有效再逐步复杂化。提示词工程明确指令在系统提示词开头就声明角色和能力。“你是一个可以调用Python工具来解决问题的AI助手。”格式化要求严格要求输出格式例如“将调用代码放在python代码块中”。提供示例在提示词中给出一到两个完整的“用户问题-模型思考-代码调用”的示例Few-shot Learning效果提升显著。安全第一绝对不要在未经验证和安全隔离的情况下直接eval()或exec()模型生成的任意代码。必须使用白名单机制只允许执行预定义好的、安全的函数并对参数进行严格校验和清洗。混合使用不必完全抛弃JSON模式。对于参数结构固定、描述简单的工具JSON可能更简洁。可以将“代码优先”用于逻辑复杂的工具或核心流程JSON用于辅助工具。持续评估建立评估基准定期测试不同提示策略下工具调用的成功率和质量。用数据驱动决策。利用类型提示Python的类型提示Type Hints和文档字符串Docstrings是极佳的工具描述语言模型能很好地理解它们。“代码优先”工具调用范式为提升大模型Agent的可靠性提供了一种新思路。它利用了现代大模型在代码理解上的强大能力将工具交互从“数据格式约定”提升到了“语义描述与逻辑表达”的层面。对于面临复杂工具调用挑战的开发者而言值得花时间进行实验和评估。建议你选择一个当前效果不满意的工具调用场景用本文提供的方法进行对比测试很可能获得意想不到的改进。