如果你最近在关注大模型工具调用Tool Calling这个方向可能会发现一个明显的趋势过去那种依赖复杂、黑盒的代理框架或者让模型直接生成 JSON 字符串的方式正在被一种更直接、更可控的“代码优先”模式所取代。简单说就是让模型直接生成可执行的 Python 代码来调用工具而不是生成一个需要二次解析的中间格式如 JSON。这不仅仅是风格问题。有研究对比了 14 个主流模型在工具调用任务上的表现结果发现采用“代码优先”策略时其中 11 个模型的性能都优于传统的 JSON 模式。这意味着对于大多数开发者而言想要更稳定、更准确地让 AI 模型使用外部工具写代码比拼 JSON 字符串更靠谱。这篇文章就围绕这个“代码优先”的趋势展开。我会结合实际的开发场景拆解清楚为什么代码比 JSON 更优背后的逻辑是什么。从 JSON 模式切换到代码模式具体要怎么改有哪些关键步骤。在实际项目中如何设计一个既灵活又健壮的“代码优先”工具调用流程。针对不同复杂度的任务有哪些现成的代码模式和最佳实践可以参考。无论你是正在构建 AI 应用的后端工程师还是希望更深入了解大模型交互模式的研究者理解这个转向都能帮你避开不少坑写出更可靠的 AI 功能模块。1. 为什么“代码优先”能赢从 JSON 的坑说起要理解为什么代码更好得先看看我们之前用 JSON 模式时经常遇到哪些头疼的问题。1.1 JSON 模式的典型痛点模糊、易错、难调试在传统的工具调用流程里我们通常这样设计给模型一个工具列表包括名称、描述、参数 schema然后要求模型严格按这个 schema 生成一个 JSON 对象。比如{ tool: get_weather, parameters: { city: 北京, date: 2024-05-27 } }这个流程听起来清晰但在实际运行中问题一大堆格式脆弱性模型生成的 JSON 字符串多一个逗号、少一个引号、或者嵌套格式不对整个解析就崩了。你需要额外写健壮的 JSON 解析和修复逻辑。意图模糊模型可能生成{tool: search, query: 北京天气}但你的工具可能叫search_web。这种名称不匹配需要复杂的模糊匹配或重试逻辑。参数类型混乱Schema 里定义date是字符串但模型可能生成明天或2024/05/27与你后端 API 期待的YYYY-MM-DD格式不符导致调用失败。调试黑洞当调用失败时你很难快速定位是模型生成的问题还是你的解析器问题或是工具 API 本身的问题。日志里就是一串字符串缺乏结构化的执行上下文。这些问题导致整个工具调用的链路非常脆弱成功率高度依赖模型的“格式遵守能力”而不是“任务理解能力”。1.2 代码模式的核心优势精确、结构化、可执行“代码优先”的思路完全不同。它不要求模型输出一个待解析的 JSON而是要求模型直接生成一段调用工具的可执行代码。通常这段代码是 Python 函数调用或一小段脚本。举个例子对于“查询北京明天天气”这个用户请求模型不再输出 JSON而是直接生成# 模型生成的代码 from tools import weather result weather.get_forecast(city北京, date2024-05-28) print(result)这种转变带来了几个立竿见影的优势执行即验证生成的代码可以直接在一个受控的沙箱或环境中运行。语法错误如缺少冒号、缩进错误会在运行前就被 Python 解释器捕获这比解析 JSON 字符串的容错性高得多。意图明确代码中的函数名weather.get_forecast、参数名city,date都是明确的标识符。模型必须从你提供的工具库中准确选择这大大降低了名称歧义。类型安全Python 是强类型语言尤其在配合类型提示时。虽然动态类型允许一定灵活性但生成weather.get_forecast(city123)这样的代码其荒谬性对模型和开发者都更明显也更容易在运行前通过静态检查或沙箱预检发现。上下文丰富代码可以包含导入语句、变量赋值、简单的逻辑判断如 if-else、错误处理try-except的雏形。这为模型提供了更丰富的表达空间使其能更好地规划多步工具调用。调试友好当代码执行失败时你会得到标准的 Python 错误回溯Traceback能清晰地指向是哪一行、哪个函数、哪个参数出了问题。这比解析一个格式错误的 JSON 字符串要直观得多。研究中所指的“11个模型更优”衡量的指标通常包括工具选择准确率、参数填充正确率、以及端到端任务完成率。代码模式在这些指标上表现更好本质上是因为它将“格式遵守”这个不确定性问题转化为了“代码生成”这个模型更擅长的问题得益于代码训练数据的大量存在并且通过执行环境获得了即时、准确的反馈。2. 从 JSON 到代码一个最小可行改造示例理论说完了我们来看具体怎么改。假设我们有一个简单的“天气查询”和“计算器”工具。2.1 传统 JSON 模式下的实现首先定义工具 Schema 并封装调用# 工具函数定义 def get_weather(city: str, date: str) - str: # 模拟实现 return f{city}在{date}的天气是晴朗25℃。 def calculator(expression: str) - str: try: # 警告实际中直接eval有安全风险此处仅作演示 result eval(expression) return f{expression} {result} except Exception as e: return f计算错误: {e} # 提供给模型的工具描述JSON Schema格式 tools_schema [ { name: get_weather, description: 获取指定城市在指定日期的天气预报。, parameters: { type: object, properties: { city: {type: string, description: 城市名称}, date: {type: string, description: 日期格式为YYYY-MM-DD} }, required: [city, date] } }, { name: calculator, description: 计算一个数学表达式的结果。, parameters: { type: object, properties: { expression: {type: string, description: 数学表达式如23*4} }, required: [expression] } } ] # 模拟模型生成JSON这里用硬编码代替实际LLM调用 model_json_output {tool: get_weather, parameters: {city: 上海, date: 2024-05-27}} # 解析并调用 import json try: parsed json.loads(model_json_output) tool_name parsed[tool] params parsed[parameters] if tool_name get_weather: result get_weather(**params) elif tool_name calculator: result calculator(**params) else: result f未知工具: {tool_name} print(result) except json.JSONDecodeError as e: print(fJSON解析失败: {e}) except KeyError as e: print(fJSON格式缺少必要字段: {e})这个流程很经典但也很脆弱。如果model_json_output变成{tool: get_weather, parameters: {city: 上海}}缺少引号json.loads直接就会报错。2.2 改造为“代码优先”模式现在我们改变思路。我们不再要求模型输出 JSON而是要求它输出 Python 代码。首先我们需要为模型创建一个“代码生成”的上下文# 1. 创建工具模块的清晰说明 tools_code_context # 可用的工具函数 # from my_tools import get_weather, calculator # get_weather(city: str, date: str) - str # 功能获取指定城市在指定日期的天气预报。 # 参数 # - city: 字符串城市名称例如 北京。 # - date: 字符串日期格式必须为 YYYY-MM-DD例如 2024-05-27。 # 返回字符串格式的天气信息。 # calculator(expression: str) - str # 功能计算一个数学表达式的结果。 # 参数 # - expression: 字符串数学表达式例如 2 3 * 4。 # 返回字符串格式的计算结果或错误信息。 # 请根据用户请求生成调用上述工具的Python代码。 # 只生成代码不要生成任何额外的解释文本。 # 确保代码语法正确可以直接运行。 # 示例用户请求计算一下3的平方加上4的平方。 # 模型应生成代码 # from my_tools import calculator # result calculator(3**2 4**2) # print(result) # 2. 将工具函数放在一个明确的模块中模拟 # 文件my_tools.py # 内容就是上面的 get_weather 和 calculator 函数 # 3. 模拟模型生成代码代替JSON user_request 查询上海明天2024-05-28的天气。 # 假设这是模型生成的代码 generated_code from my_tools import get_weather result get_weather(city上海, date2024-05-28) print(result) # 4. 安全地执行生成的代码 # 重要在实际生产中必须在严格受限的沙箱环境中执行 # 此处为演示使用 exec 并限制全局/局部命名空间。 allowed_globals {__builtins__: {}} # 限制内置函数 allowed_locals { get_weather: get_weather, # 只暴露允许的工具 calculator: calculator, } try: # 执行生成的代码 exec(generated_code, allowed_globals, allowed_locals) except SyntaxError as e: print(f生成的代码有语法错误: {e}) except NameError as e: print(f代码尝试使用了未授权的函数或变量: {e}) except Exception as e: print(f代码执行过程中发生错误: {e})这个流程的核心变化在于输出格式从 JSON 字符串变成了 Python 代码字符串。验证方式从 JSON 解析验证变成了 Python 语法检查 沙箱执行。错误反馈错误信息从“JSON解析失败”变成了具体的 Python 异常如SyntaxError或NameError定位问题容易得多。2.3 关键改造步骤总结重构工具暴露方式将你的工具函数组织成清晰的、可导入的 Python 模块如my_tools.py并为其编写清晰的文档字符串Docstring。这是模型生成正确代码的基础。重写系统提示词Prompt在给模型的指令中明确要求生成可执行的 Python 代码并提供详细的函数签名、参数说明和调用示例。强调“只生成代码不要额外文本”。建立代码执行沙箱这是安全的核心。绝不能直接exec()用户或模型生成的任意代码。必须使用沙箱技术如restrictedpython,PyPy沙箱或在 Docker 容器内运行来严格限制可访问的模块、函数和资源。设计执行与结果捕获机制沙箱执行代码后你需要捕获其输出如print的内容或返回值。通常你会让生成的代码将结果赋值给一个特定变量如final_result然后从沙箱的局部变量中提取它。实现错误处理与重试捕获执行时可能出现的各种异常语法错误、运行时错误、超时等并设计重试逻辑。例如如果代码有拼写错误可以将错误信息反馈给模型让它修正代码后重新生成。3. 构建健壮的“代码优先”工具调用系统一个玩具示例跑通只是第一步。要用于实际项目我们必须考虑安全性、复杂任务处理和稳定性。3.1 安全第一必须使用沙箱执行直接exec或eval模型生成的代码是极度危险的。模型可能生成import os; os.system(rm -rf /)这样的代码。必须使用沙箱。一个相对简单且安全的方案是使用docker容器来隔离执行环境import docker import tempfile import os def execute_code_in_docker(code: str, timeout_seconds10) - (str, str): 在 Docker 容器中安全执行 Python 代码。 返回: (标准输出, 标准错误) client docker.from_env() # 1. 准备一个临时的 Python 脚本文件 with tempfile.NamedTemporaryFile(modew, suffix.py, deleteFalse) as f: # 在代码开头注入我们允许的工具 safe_code f # 注入安全工具 from my_safe_tools import get_weather, calculator # 用户/模型生成的代码 {code} f.write(safe_code) temp_file_path f.name try: # 2. 启动一个干净的 Python 容器挂载工具模块和脚本 container client.containers.run( imagepython:3.9-slim, # 使用官方精简镜像 commandfpython /tmp/script.py, volumes{ os.path.abspath(my_safe_tools.py): {bind: /my_safe_tools.py, mode: ro}, temp_file_path: {bind: /tmp/script.py, mode: ro} }, working_dir/, detachTrue, mem_limit100m, # 限制内存 cpu_period100000, cpu_quota50000, # 限制 CPU network_disabledTrue, # 禁用网络除非工具需要 ) # 3. 等待执行完成或超时 try: result container.wait(timeouttimeout_seconds) exit_code result[StatusCode] logs container.logs(stdoutTrue, stderrTrue).decode(utf-8) stderr container.logs(stdoutFalse, stderrTrue).decode(utf-8) except Exception as e: container.kill() container.remove() return , f执行超时或错误: {e} finally: container.remove() # 4. 返回结果 # 可以根据 exit_code 判断是否成功 return logs, stderr finally: # 清理临时文件 os.unlink(temp_file_path) # 使用示例 generated_code result get_weather(city北京, date2024-05-27) stdout, stderr execute_code_in_docker(generated_code) if stderr: print(f执行出错: {stderr}) else: print(f执行结果: {stdout})这个方案将代码执行隔离在了一个资源受限、无网络可选、一次性使用的 Docker 容器中即使代码恶意其破坏也被限制在容器内。对于生产环境你可能需要更成熟的沙箱服务或 K8s Job。3.2 处理复杂任务多步调用与规划用户请求往往不是一步就能完成的。例如“查一下北京和上海明天的天气然后告诉我哪里更暖和。”这需要模型进行规划生成多步代码。我们的系统需要支持模型生成包含多个工具调用和逻辑判断的代码块# 模型可能生成的复杂代码示例 generated_complex_code from my_tools import get_weather # 获取北京天气 weather_beijing get_weather(city北京, date2024-05-28) # 获取上海天气 weather_shanghai get_weather(city上海, date2024-05-28) # 简单解析结果假设返回字符串包含温度 # 注意实际中需要更健壮的解析这里仅为演示 def extract_temp(weather_str): # 假设格式为“...25℃。” import re match re.search(r(\d)℃, weather_str) return int(match.group(1)) if match else None temp_bj extract_temp(weather_beijing) temp_sh extract_temp(weather_shanghai) if temp_bj is not None and temp_sh is not None: if temp_bj temp_sh: result f北京 ({temp_bj}℃) 比上海 ({temp_sh}℃) 更暖和。 elif temp_sh temp_bj: result f上海 ({temp_sh}℃) 比北京 ({temp_bj}℃) 更暖和。 else: result f北京和上海温度相同都是 {temp_bj}℃。 else: result 无法从天气信息中提取温度进行比较。 print(result) 为了支持这种复杂代码你需要提供更强大的基础工具比如提供parse_temperature_from_text(text: str) - int这样的工具减少模型自己写正则表达式的负担和错误。在 Prompt 中鼓励规划在系统指令中明确告诉模型“你可以生成包含多个步骤、变量赋值和简单逻辑判断如 if-else的 Python 代码来解决复杂问题。”增强错误恢复能力复杂代码更容易出错。当沙箱执行失败时你需要将完整的错误信息Traceback反馈给模型让它修正代码。这构成了一个“生成-执行-反馈-修正”的循环。3.3 稳定性保障重试、超时与回退任何依赖外部模型的服务都必须考虑稳定性。语法错误重试如果生成的代码有SyntaxError这通常是“低级错误”可以直接将错误信息反馈给模型要求它修正。重试1-2次通常能解决。运行时错误重试如果是NameError使用了未定义的函数、TypeError参数类型错误或工具调用本身的异常也需要重试。此时反馈的信息应包括错误类型和具体消息。超时控制必须在沙箱层面设置执行超时如上面的 Dockertimeout参数防止模型生成死循环代码。JSON 模式回退尽管“代码优先”更优但可以将其作为首选策略同时保留传统的 JSON 模式作为降级方案Fallback。如果代码模式连续失败多次可以切换回 JSON 模式尝试一次。这能提高系统的整体鲁棒性。4. 不同场景下的代码模式最佳实践“代码优先”不是一种固定的写法可以根据任务复杂度演变出不同模式。4.1 模式一简单函数调用适用于单步任务这是最基础的模式适用于“调用一个工具完成一件事”的场景。Prompt 设计要点你是一个助手可以通过调用预定义的Python工具函数来帮助用户。 工具函数如下 - search_web(query: str) - str: 执行网络搜索并返回摘要。 - send_email(to: str, subject: str, body: str) - bool: 发送邮件。 请根据用户请求生成**唯一一段**直接调用工具的Python代码。 只生成代码不要任何解释。 确保使用正确的函数名和参数。期望的模型输出result search_web(queryPython最新版本特性) print(result)4.2 模式二带逻辑的代码块适用于多步与判断适用于需要条件判断、循环或组合多个工具结果的场景。Prompt 设计要点你可以生成包含多个步骤的Python代码来解决复杂问题。 可用的工具get_stock_price(symbol), calculate_change(price1, price2)。 你可以使用if/else, for循环变量赋值等基础Python语法。 请生成完整的、可独立运行的代码片段。期望的模型输出用户请求“对比一下AAPL和MSFT今天的股价变化”price_aapl get_stock_price(AAPL) price_msft get_stock_price(MSFT) # 假设函数返回字典 {current: 180, previous_close: 175} change_aapl calculate_change(price_aapl[current], price_aapl[previous_close]) change_msft calculate_change(price_msft[current], price_msft[previous_close]) if change_aapl change_msft: conclusion AAPL今日涨幅更大。 elif change_msft change_aapl: conclusion MSFT今日涨幅更大。 else: conclusion 两者涨幅相同。 output fAAPL变化: {change_aapl:.2%}, MSFT变化: {change_msft:.2%}. {conclusion} print(output)4.3 模式三工具类与方法链面向对象风格如果你的工具本身是面向对象设计的可以让模型生成使用类和方法的代码。Prompt 设计要点你可以使用 DataAnalyzer 类来处理数据。 初始化: analyzer DataAnalyzer(data_path) 方法: - .load() - 加载数据 - .clean() - 清洗数据 - .summary() - 生成摘要 - .plot(kindhist) - 绘制图表 请生成按顺序调用这些方法的代码。期望的模型输出analyzer DataAnalyzer(sales_data.csv) analyzer.load() analyzer.clean() summary analyzer.summary() print(summary) analyzer.plot(kindline)4.4 与现有框架结合LangChain 和 LlamaIndex你不需要从头造轮子。现有的 AI 应用框架正在快速适配“代码优先”模式。LangChain其Tool接口和Agent体系结构可以支持。你可以创建一个PythonREPLTool的变体但更安全的做法是自定义一个工具其_run方法接收模型生成的代码字符串然后在安全沙箱中执行它并将结果返回给 Agent。LlamaIndex其QueryEngine和ToolSpec也可以集成。你可以设计一个CodeExecutionToolSpec将代码生成和执行作为其中一个工具节点。核心思路是将“代码生成与执行”本身包装成一个超级工具Meta-Tool集成到现有框架的流程中。这样你既利用了框架在流程编排、记忆、检索方面的能力又在其内部采用了更优的代码调用策略。5. 评估、监控与迭代切换到“代码优先”模式后如何评估其效果定义核心指标代码生成成功率生成的代码无语法错误、无未授权导入的比例。工具调用准确率生成的代码调用了正确工具的比例。参数填充正确率工具参数值符合预期的比例。端到端任务完成率用户请求被最终正确解决的比例。平均修复次数需要模型根据错误反馈重新生成代码的平均次数。建立监控记录每一次交互用户请求、生成的代码、执行结果成功/失败及错误信息、最终输出。对失败案例进行分类语法错误、工具不存在、参数错误、逻辑错误、超时等。持续迭代 Prompt 和工具设计分析常见错误类型优化系统 Prompt。例如如果模型经常用错参数顺序就在 Prompt 中更强调参数名。如果模型经常尝试自己实现复杂逻辑如解析 HTML而失败率很高考虑将这个逻辑封装成一个新的、更强大的工具提供给模型。定期用积累的失败案例作为测试集评估改进效果。最后几个关键提醒安全是底线沙箱不是可选项是必选项。即使牺牲一点便利性也必须保证执行环境隔离。从简单开始不要一开始就追求复杂的多步代码生成。先确保单工具、无逻辑的代码调用能稳定工作。Prompt 即 API给你的工具函数起清晰、一致的名字写详细的文档字符串。这直接决定了模型生成代码的质量。拥抱混合模式对于极其简单、结构固定的调用如“播放歌曲XXX”传统的结构化输出JSON可能仍然更简洁。可以采用规则判断简单请求走 JSON复杂请求走代码。“工具调用转向代码优先”不是一个空洞的结论而是一个有扎实数据支撑14个模型中11个更优且能显著提升应用可靠性的工程实践。它的本质是将大模型更擅长代码生成的能力与程序世界精确、结构化的执行环境相结合从而绕开了传统方法中“格式对齐”这个薄弱环节。开始尝试时你可能会觉得比直接解析 JSON 麻烦。但一旦跑通安全执行和错误处理的闭环你会发现整个系统的可调试性和健壮性都上了一个台阶。对于严肃的 AI 应用开发来说这个投入是值得的。