最佳实践

设计模式

1. 单一职责

每个工具只做一件事：

// ✅ 好：职责清晰
{ "name": "get_weather", "description": "获取天气" }
{ "name": "get_stock_price", "description": "获取股价" }

// ❌ 差：职责混乱
{ "name": "get_info", "description": "获取天气或股价" }

2. 清晰的描述

工具描述是模型理解的关键：

// ✅ 好：描述具体
{ "description": "搜索互联网上的公开信息，返回相关网页链接和摘要" }

// ❌ 差：描述模糊
{ "description": "搜索" }

3. 合理的参数设计

{
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "搜索关键词，多个词用空格分隔"
      },
      "date_range": {
        "type": "string",
        "enum": ["today", "week", "month", "year", "all"],
        "description": "时间范围"
      }
    },
    "required": ["query"]
  }
}

错误处理

工具执行失败

# 返回错误信息让模型处理
tool_result = {
    "error": "API 调用失败：网络超时",
    "suggestion": "请稍后重试或检查网络连接"
}

参数校验

# 在工具内部校验参数
def get_weather(city: str):
    if not city or len(city) < 2:
        return {"error": "城市名无效，请提供有效的城市名"}
    # ... 正常逻辑

安全考虑

1. 权限控制

• 敏感操作需要用户确认
• 限制工具可访问的资源范围
• 记录所有工具调用日志

2. 输入验证

def execute_code(code: str):
    # 危险操作需要沙箱
    if "import os" in code or "subprocess" in code:
        return {"error": "不允许执行系统命令"}
    # 在沙箱中执行
    return sandbox_run(code)

3. 速率限制

• 防止工具被滥用
• 设置调用频率上限
• 监控异常调用模式

性能优化

1. 并行执行

import asyncio

# 多个独立工具并行执行
results = await asyncio.gather(
    get_weather("Beijing"),
    get_weather("Shanghai"),
    get_weather("Guangzhou")
)

2. 缓存结果

from functools import lru_cache

@lru_cache(maxsize=100)
def get_weather(city: str):
    # 缓存相同查询
    ...

3. 减少工具数量

• 合并相似工具
• 移除不常用工具
• 工具越多，模型越容易困惑

常见陷阱

陷阱	解决方案
工具描述太抽象	提供具体示例
参数类型不匹配	明确 schema 类型
循环调用	设置最大调用次数
忘记返回结果	使用框架自动处理