函数调用工具允许智能体调用外部函数和 API，极大扩展了 AI 助手的能力边界，使其能够执行具体的操作和获取实时数据。

​
功能特性

结构化输出

  • 自动解析函数参数
  • 类型验证和转换
  • 错误处理和重试
  • 结果格式化

多函数支持

  • 同时定义多个函数
  • 函数链式调用
  • 条件函数选择
  • 并行函数执行

灵活集成

  • RESTful API 集成
  • 数据库操作
  • 文件系统访问
  • 第三方服务调用

​
基础用法

安装SDK
# 安装最新版本
pip install zai-sdk

# 或指定版本
pip install zai-sdk==0.0.3.3
验证安装
import zai
print(zai.__version__)

​
定义函数

import json
from zai import ZhipuAiClient

client = ZhipuAiClient(api_key="your_api_key")

# 定义天气查询函数
def get_weather(city: str) -> dict:
    """获取指定城市的天气信息"""
    # 这里应该调用真实的天气 API
    weather_data = {
        "city": city,
        "temperature": "22°C",
        "condition": "晴天",
        "humidity": "65%",
        "wind_speed": "5 km/h"
    }
    return weather_data

# 函数描述格式
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的当前天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称，例如：北京、上海"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

​
完整实现示例

​
高级应用场景

在使用函数调用时，请确保对外部 API 和数据库操作进行适当的安全验证和权限控制。

​
实践建议

函数设计原则

  1. 单一职责：每个函数只做一件事
  2. 清晰命名：函数名和参数名要有意义
  3. 完整描述：提供详细的函数和参数描述
  4. 错误处理：妥善处理异常情况
  5. 类型安全：验证参数类型和值

安全考虑

  1. 输入验证：严格验证所有输入参数
  2. 权限控制：限制函数的访问权限
  3. 资源限制：防止资源滥用
  4. 日志记录：记录函数调用日志
  5. 异常处理：优雅处理错误情况

​
参数设计

# 好的参数设计
{
    "type": "object",
    "properties": {
        "city": {
            "type": "string",
            "description": "城市名称，支持中英文，如：北京、Beijing",
            "examples": ["北京", "上海", "New York"]
        },
        "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "温度单位",
            "default": "celsius"
        }
    },
    "required": ["city"]
}

​
错误处理

def robust_function(param: str) -> dict:
    """健壮的函数实现"""
    try:
        # 参数验证
        if not param or not isinstance(param, str):
            return {
                "success": False,
                "error": "参数无效",
                "error_code": "INVALID_PARAM"
            }
        
        # 业务逻辑
        result = process_data(param)
        
        return {
            "success": True,
            "data": result,
            "timestamp": datetime.now().isoformat()
        }
    
    except ValueError as e:
        return {
            "success": False,
            "error": f"数据错误: {str(e)}",
            "error_code": "DATA_ERROR"
        }
    except Exception as e:
        return {
            "success": False,
            "error": f"系统错误: {str(e)}",
            "error_code": "SYSTEM_ERROR"
        }

​
性能优化

from functools import lru_cache
import asyncio

# 缓存结果
@lru_cache(maxsize=100)
def cached_function(param: str) -> dict:
    """带缓存的函数"""
    # 耗时操作
    result = expensive_operation(param)
    return result

# 异步函数
async def async_function(param: str) -> dict:
    """异步函数实现"""
    async with aiohttp.ClientSession() as session:
        async with session.get(f"https://api.example.com/{param}") as response:
            data = await response.json()
            return {"success": True, "data": data}

​
安全考虑

​
输入验证

def secure_function(user_input: str) -> dict:
    """安全的函数实现"""
    # 输入长度限制
    if len(user_input) > 1000:
        return {"error": "输入过长"}
    
    # 危险字符过滤
    dangerous_chars = ['<', '>', '&', '"', "'"]
    if any(char in user_input for char in dangerous_chars):
        return {"error": "输入包含危险字符"}
    
    # SQL 注入防护
    sql_keywords = ['DROP', 'DELETE', 'UPDATE', 'INSERT']
    if any(keyword in user_input.upper() for keyword in sql_keywords):
        return {"error": "输入包含危险关键词"}
    
    return {"success": True, "processed_input": user_input}

​
权限控制

def check_permissions(user_id: str, operation: str) -> bool:
    """检查用户权限"""
    user_permissions = get_user_permissions(user_id)
    return operation in user_permissions

def protected_function(user_id: str, operation: str, data: dict) -> dict:
    """需要权限验证的函数"""
    if not check_permissions(user_id, operation):
        return {
            "success": False,
            "error": "权限不足",
            "error_code": "PERMISSION_DENIED"
        }
    
    # 执行操作
    return perform_operation(operation, data)
建议为每个函数提供详细的文档和示例，帮助模型更好地理解函数的用途和使用方法。
函数调用涉及代码执行，请确保实现适当的安全措施，包括输入验证、权限控制和错误处理。