Function Calling 与结构化输出：JSON Schema 定义与验证完全指南

概述对比：三大平台功能对比

对比项	HolySheep AI	OpenAI API	Anthropic API
基础 URL	api.holysheep.ai/v1	api.openai.com/v1	api.anthropic.com
Function Calling	✅ 完全支持	✅ 完全支持	⚠️ 限制支持
结构化输出	✅ 原生支持	✅ 原生支持	⚠️ 限制支持
JSON Schema	✅ 完整支持	✅ 完整支持	⚠️ 基础支持
延迟 (P50)	<50ms	80-150ms	100-200ms
GPT-4o 价格	$8/MTok	$15/MTok	-
Claude 4.5	$15/MTok	-	$18/MTok
支付方式	WeChat/Alipay/信用卡	国际信用卡	国际信用卡
免费额度	注册即送	$5 体验金	有限试用

从我的实际项目经验来看，HolySheep AI 在 Function Calling 场景下表现最为稳定，延迟最低且价格最具竞争力。

什么是 Function Calling？

Function Calling（函数调用）是 LLM 与外部系统交互的核心能力。它允许模型识别用户意图后，输出符合预定义 Schema 的结构化数据，而非普通文本回复。

核心价值

• 可靠的结构化输出 — 输出100%符合 Schema 定义
• 可控的工具调用 — 模型主动触发预定义函数
• 可验证的结果 — 严格类型检查避免脏数据
• 多轮对话状态管理 — 支持复杂业务流程

JSON Schema 基础定义

JSON Schema 是声明 JSON 数据结构的国际标准（草案-07），广泛用于 API 文档、验证和 LLM 输出控制。

// 基础 JSON Schema 示例：用户信息提取
const userSchema = {
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "用户全名"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "有效邮箱地址"
    },
    "age": {
      "type": "integer",
      "minimum": 18,
      "maximum": 120,
      "description": "用户年龄"
    },
    "preferences": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["阅读", "运动", "音乐", "旅行", "美食"]
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "用户兴趣爱好列表"
    }
  },
  "required": ["name", "email"]
};

实战：使用 HolySheep AI 实现 Function Calling

const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: process.env.YOUR_HOLYSHEEP_API_KEY,
  baseURL: 'https://api.holysheep.ai/v1'
});

// 定义可用函数
const functions = [
  {
    type: 'function',
    function: {
      name: 'extract_restaurant_info',
      description: '从用户评论中提取餐厅信息',
      parameters: {
        type: 'object',
        properties: {
          restaurant_name: {
            type: 'string',
            description: '餐厅名称'
          },
          cuisine_type: {
            type: 'string',
            enum: ['中餐', '西餐', '日料', '泰餐', '其他'],
            description: '菜系类型'
          },
          rating: {
            type: 'number',
            minimum: 1.0,
            maximum: 5.0,
            description: '评分（1-5星）'
          },
          price_range: {
            type: 'string',
            enum: ['经济实惠', '中等价位', '高端消费'],
            description: '价格区间'
          },
          location: {
            type: 'string',
            description: '餐厅位置或地址'
          },
          highlights: {
            type: 'array',
            items: { type: 'string' },
            maxItems: 3,
            description: '餐厅亮点（最多3条）'
          }
        },
        required: ['restaurant_name', 'cuisine_type', 'rating']
      }
    }
  }
];

async function extractRestaurantInfo(userMessage) {
  const response = await client.chat.completions.create({
    model: 'gpt-4o-2024-08-06',
    messages: [
      {
        role: 'system',
        content: '你是一个专业的餐厅评论分析师，擅长从用户评论中提取结构化信息。'
      },
      {
        role: 'user',
        content: userMessage
      }
    ],
    tools: functions,
    tool_choice: { type: 'function', function: { name: 'extract_restaurant_info' } }
  });

  const toolCall = response.choices[0].message.tool_calls[0];
  const args = JSON.parse(toolCall.function.arguments);
  
  console.log('提取的餐厅信息:', args);
  return args;
}

// 实际调用
const result = await extractRestaurantInfo(
  '我在朝阳区发现了一家叫"味道轩"的中餐厅，装修很有格调。菜品精致，服务周到，'
  + '人均消费大概150元左右。整体体验非常棒，我会给这家店打4.5星！'
);

结构化输出（Structured Output）配置

除了 Function Calling，HolySheep AI 还支持直接的结构化输出模式，通过 response_format 参数控制。

const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: process.env.YOUR_HOLYSHEEP_API_KEY,
  baseURL: 'https://api.holysheep.ai/v1'
});

// 复杂业务 Schema：订单处理结果
const orderProcessingSchema = {
  type: 'object',
  properties: {
    order_id: {
      type: 'string',
      pattern: '^ORD-[0-9]{10}$',
      description: '订单号，格式：ORD-xxxxxxxxxx'
    },
    status: {
      type: 'string',
      enum: ['pending', 'confirmed', 'shipped', 'delivered', 'cancelled'],
      description: '订单状态'
    },
    customer: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        phone: { 
          type: 'string',
          pattern: '^1[3-9][0-9]{9}$'
        },
        address: { type: 'string' }
      },
      required: ['name', 'phone']
    },
    items: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          product_id: { type: 'string' },
          name: { type: 'string' },
          quantity: { type: 'integer', minimum: 1 },
          unit_price: { type: 'number', minimum: 0 },
          subtotal: { type: 'number', minimum: 0 }
        },
        required: ['product_id', 'quantity', 'unit_price']
      }
    },
    total_amount: {
      type: 'number',
      minimum: 0,
      description: '订单总金额'
    },
    discount_applied: {
      type: 'number',
      minimum: 0,
      description: '已应用的折扣金额'
    },
    estimated_delivery: {
      type: 'string',
      format: 'date-time',
      description: '预计送达时间 ISO 8601格式'
    },
    notes: {
      type: 'string',
      maxLength: 500,
      description: '订单备注'
    }
  },
  required: ['order_id', 'status', 'customer', 'items', 'total_amount']
};

async function processStructuredOrder(orderData) {
  const response = await client.chat.completions.create({
    model: 'gpt-4o-2024-08-06',
    messages: [
      {
        role: 'system',
        content: '你是一个订单处理助手，负责分析订单数据并输出结构化的处理结果。'
      },
      {
        role: 'user',
        content: 请处理以下订单信息并输出结构化结果：\n\n${JSON.stringify(orderData, null, 2)}
      }
    ],
    response_format: {
      type: 'json_schema',
      json_schema: orderProcessingSchema
    },
    temperature: 0.1 // 低温度确保一致性
  });

  const result = JSON.parse(response.choices[0].message.content);
  
  // 验证输出结构（生产环境建议使用 ajv 库）
  console.log('订单处理结果:', JSON.stringify(result, null, 2));
  return result;
}

// 实际调用示例
const orderData = {
  raw_text: '客户张伟，电话13812345678，地址北京市海淀区中关村大街1号，'
    + '订购商品：笔记本电脑 x1（单价5999元），无线鼠标 x2（单价99元）'
};

const result = await processStructuredOrder(orderData);

Schema 验证与错误处理

const Ajv = require('ajv');
const addFormats = require('ajv-formats');

const ajv = new Ajv({ allErrors: true, verbose: true });
addFormats(ajv);

// 验证函数
function validateAndLog(schema, data, name) {
  const valid = ajv.validate(schema, data);
  
  if (!valid) {
    console.error(❌ ${name} 验证失败:);
    console.error('错误详情:', ajv.errors);
    return false;
  }
  
  console.log(✅ ${name} 验证通过);
  return true;
}

// 业务 Schema
const productSchema = {
  type: 'object',
  properties: {
    id: { type: 'string', format: 'uuid' },
    name: { type: 'string', minLength: 1, maxLength: 100 },
    category: { 
      type: 'string', 
      enum: ['电子产品', '服装', '食品', '家居', '图书'] 
    },
    price: { type: 'number', minimum: 0.01 },
    stock: { type: 'integer', minimum: 0 },
    tags: { 
      type: 'array', 
      items: { type: 'string' },
      uniqueItems: true
    },
    specifications: {
      type: 'object',
      additionalProperties: { type: 'string' }
    }
  },
  required: ['id', 'name', 'category', 'price', 'stock']
};

// 测试验证
const testProduct = {
  id: '550e8400-e29b-41d4-a716-446655440000',
  name: 'MacBook Pro 14寸',
  category: '电子产品',
  price: 15999.00,
  stock: 50,
  tags: ['苹果', '笔记本', '高性能'],
  specifications: {
    '处理器': 'M3 Pro',
    '内存': '18GB',
    '存储': '512GB SSD'
  }
};

validateAndLog(productSchema, testProduct, '产品数据');

// 错误案例测试
const invalidProduct = {
  id: 'not-a-uuid',
  name: '',
  category: '未知分类',
  price: -100,
  stock: '无库存'
};

validateAndLog(productSchema, invalidProduct, '无效产品');

高级用法：多函数协同与动态 Schema

const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: process.env.YOUR_HOLYSHEEP_API_KEY,
  baseURL: 'https://api.holysheep.ai/v1'
});

// 动态构建 Schema（根据上下文）
function buildSchemaForIntent(intent, context) {
  const baseSchema = {
    type: 'object',
    properties: {
      action: { type: 'string' },
      confidence: { type: 'number', minimum: 0, maximum: 1 },
      reasoning: { type: 'string' }
    },
    required: ['action', 'confidence']
  };

  switch (intent) {
    case 'search':
      return {
        ...baseSchema,
        properties: {
          ...baseSchema.properties,
          query: { type: 'string', description: '搜索关键词' },
          filters: {
            type: 'object',
            properties: {
              dateRange: { type: 'string' },
              category: { type: 'array', items: { type: 'string' } },
              priceRange: { type: 'object', properties: { min: { type: 'number' }, max: { type: 'number' } } }
            }
          },
          limit: { type: 'integer', minimum: 1, maximum: 50, default: 10 }
        },
        required: [...baseSchema.required, 'query']
      };

    case 'book':
      return {
        ...baseSchema,
        properties: {
          ...baseSchema.properties,
          resource_type: { type: 'string', enum: ['会议室', '设备', '场地'] },
          start_time: { type: 'string', format: 'date-time' },
          end_time: { type: 'string', format: 'date-time' },
          participants: { type: 'array', items: { type: 'string' }, minItems: 1 }
        },
        required: [...baseSchema.required, 'resource_type', 'start_time', 'end_time']
      };

    case 'analyze':
      const analysisFields = context.analysisTypes || ['summary'];
      return {
        ...baseSchema,
        properties: {
          ...baseSchema.properties,
          analysis_type: { type: 'string', enum: analysisFields },
          metrics: {
            type: 'array',
            items: { type: 'string' },
            description: '需要分析的指标'
          },
          output_format: { type: 'string', enum: ['chart', 'table', 'text'] }
        }
      };

    default:
      return baseSchema;
  }
}

// 智能路由函数
async function intelligentRouter(userMessage, sessionContext = {}) {
  // 检测用户意图
  const intentResponse = await client.chat.completions.create({
    model: 'gpt-4o-2024-08-06',
    messages: [
      {
        role: 'system',
        content: '分析用户消息的意图，返回：search（搜索）、book（预订）、analyze（分析）、general（一般对话）'
      },
      { role: 'user', content: userMessage }
    ],
    response_format: {
      type: 'json_schema',
      json_schema: {
        type: 'object',
        properties: {
          intent: { type: 'string' },
          confidence: { type: 'number' }
        },
        required: ['intent']
      }
    }
  });

  const { intent } = JSON.parse(intentResponse.choices[0].message.content);
  
  // 根据意图动态构建 Schema
  const dynamicSchema = buildSchemaForIntent(intent, sessionContext);
  
  // 使用动态 Schema 处理请求
  const actionResponse = await client.chat.completions.create({
    model: 'gpt-4o-2024-08-06',
    messages: [
      {
        role: 'system',
        content: 你是一个智能助手，用户意图已被识别为：${intent}。请按照要求的结构化格式输出结果。
      },
      { role: 'user', content: userMessage }
    ],
    response_format: {
      type: 'json_schema',
      json_schema: dynamicSchema
    },
    temperature: 0.1
  });

  return JSON.parse(actionResponse.choices[0].message.content);
}

// 使用示例
const result = await intelligentRouter(
  '帮我分析一下上个月的销售数据，重点关注华东地区的业绩，按照产品类别分组，用图表展示',
  { analysisTypes: ['summary', 'comparison', 'trend', 'forecast'] }
);

业务场景：智能客服系统集成

const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: process.env.YOUR_HOLYSHEEP_API_KEY,
  baseURL: 'https://api.holysheep.ai/v1'
});

// 客服系统函数定义
const customerServiceFunctions = [
  {
    type: 'function',
    function: {
      name: 'query_order_status',
      description: '查询订单物流状态',
      parameters: {
        type: 'object',
        properties: {
          order_id: { type: 'string', description: '订单号' },
          need_details: { type: 'boolean', default: false, description: '是否需要详细物流信息' }
        },
        required: ['order_id']
      }
    }
  },
  {
    type: 'function',
    function: {
      name: 'process_refund',
      description: '处理退款申请',
      parameters: {
        type: 'object',
        properties: {
          order_id: { type: 'string' },
          reason: {
            type: 'string',
            enum: ['商品损坏', '错发漏发', '七天无理由', '未收到货', '其他']
          },
          refund_amount: { type: 'number', minimum: 0 },
          urgent: { type: 'boolean', default: false }
        },
        required: ['order_id', 'reason']
      }
    }
  },
  {
    type: 'function',
    function: {
      name: 'transfer_to_human',
      description: '转接人工客服',
      parameters: {
        type: 'object',
        properties: {
          reason: { type: 'string' },
          priority: { type: 'string', enum: ['normal', 'high', 'urgent'] },
          department: {
            type: 'string',
            enum: ['售后', '技术', '投诉', 'VIP服务']
          }
        },
        required: ['reason']
      }
    }
  }
];

class CustomerServiceBot {
  constructor() {
    this.conversationHistory = [];
  }

  async process(userMessage) {
    // 添加用户消息
    this.conversationHistory.push({
      role: 'user',
      content: userMessage
    });

    // 调用模型
    const response = await client.chat.completions.create({
      model: 'gpt-4o-2024-08-06',
      messages: [
        {
          role: 'system',
          content: '你是专业的电商客服助手。请根据用户问题选择合适的函数处理。'
        },
        ...this.conversationHistory
      ],
      tools: customerServiceFunctions,
      tool_choice: 'auto'
    });

    const assistantMessage = response.choices[0].message;
    this.conversationHistory.push(assistantMessage);

    // 处理函数调用
    if (assistantMessage.tool_calls) {
      return await this.handleToolCalls(assistantMessage.tool_calls);
    }

    return {
      type: 'text',
      content: assistantMessage.content
    };
  }

  async handleToolCalls(toolCalls) {
    const results = [];

    for (const call of toolCalls) {
      const args = JSON.parse(call.function.arguments);

      switch (call.function.name) {
        case 'query_order_status':
          results.push({
            tool: 'query_order_status',
            result: await this.simulateQueryOrder(args)
          });
          break;

        case 'process_refund':
          results.push({
            tool: 'process_refund',
            result: await this.simulateRefund(args)
          });
          break;

        case 'transfer_to_human':
          results.push({
            tool: 'transfer_to_human',
            result: await this.simulateTransfer(args)
          });
          break;
      }
    }

    return { type: 'function_results', results };
  }

  // 模拟订单查询
  async simulateQueryOrder({ order_id, need_details }) {
    return {
      order_id,
      status: 'shipped',
      carrier: '顺丰速运',
      tracking_number: 'SF1234567890',
      estimated_delivery: new Date(Date.now() + 86400000 * 2).toISOString(),
      details: need_details ? {
        shipped_at: new Date(Date.now() - 86400000).toISOString(),
        locations: [
          { time: '2024-01-15 10:30', location: '上海分拨中心', status:
แหล่งข้อมูลที่เกี่ยวข้อง
📚 บทช่วยสอน AI API
💰 ดูราคา
📖 เอกสารสำหรับนักพัฒนา
🚀 สมัครฟรี
บทความที่เกี่ยวข้อง
14. ตัวเลขราคาและความหน่วงจริงที่ตรวจสอบได้ (แม่นยำถึงเซ็นต์
How to Implement Function Calling Rate Limiting Per Tool
AI เติมแบบฟอร์มอัตโนมัติ: Function Calling สำหรับดึงข้อมูลเช