AI 标准协议及调用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "system",
      "content": "你是一个有帮助的 AI 助手，擅长回答技术问题。"
    },
    {
      "role": "user",
      "content": "什么是机器学习？"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 2000,
  "top_p": 1.0,
  "stream": false,
  "stop": null,
  "presence_penalty": 0,
  "frequency_penalty": 0
}

1
2
3
4
5
6

[
  { "role": "system", "content": "你是一个有帮助的助手" },
  { "role": "user", "content": "什么是机器学习？" },
  { "role": "assistant", "content": "机器学习是..." },
  { "role": "user", "content": "能举个例子吗？" }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "机器学习是人工智能的一个分支..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 50,
    "total_tokens": 70
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 2000,
  "system": "你是一个有帮助的 AI 助手，擅长回答技术问题。",
  "messages": [
    {
      "role": "user",
      "content": "什么是机器学习？"
    }
  ],
  "temperature": 0.7,
  "top_p": 1.0,
  "stop_sequences": null,
  "metadata": {
    "user_id": "user_123"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

[
  {
    "role": "user",
    "content": "什么是机器学习？"
  },
  {
    "role": "assistant",
    "content": "机器学习是人工智能的一个分支..."
  },
  {
    "role": "user",
    "content": "能举个例子吗？"
  }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "机器学习是..."
    }
  ],
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 50
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

{
  // --- 系统指令（可选但推荐） ---
  "system_instruction": {
    "parts": [
      {
        "text": "你是一个专业的 AI 助手，擅长解释技术概念。请用清晰、易懂的语言回答问题。"
      }
    ]
  },

  // --- 对话内容 ---
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "什么是机器学习？请详细解释。"
        }
      ]
    }
  ],

  // --- 生成配置 ---
  "generationConfig": {
    "temperature": 0.7, // 1. 控制随机性 (0-2)
    "topP": 0.95, // 2. 核采样阈值
    "topK": 40, // 3. 候选 token 数量
    "maxOutputTokens": 2048, // 4. 最大输出长度
    "stopSequences": [], // 停止序列

    // --- Gemini 3 核心新参数 ---
    "thinking_level": "HIGH" // 5. 【核心】替代旧版 budget，控制推理深度 (MINIMAL/MEDIUM/HIGH)
  },

  // --- 安全设置 ---
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "你好，请介绍一下自己" }]
    },
    {
      "role": "model",
      "parts": [
        { "text": "你好！我是 Gemini，一个由 Google 开发的 AI 助手..." }
      ]
    },
    {
      "role": "user",
      "parts": [{ "text": "你能做什么？" }]
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "role": "user",
  "parts": [
    { "text": "这张图片里有什么？" },
    {
      "inline_data": {
        "mime_type": "image/jpeg",
        "data": "base64_encoded_image_data"
      }
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "systemInstruction": {
    "parts": [
      {
        "text": "你是一个专业的 Python 编程助手，代码要简洁高效。"
      }
    ]
  },
  "contents": [...]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            // 1. 【新增】推理思考过程（仅在开启 thinking_level 时出现）
            "thought": "首先，我需要定义机器学习的三个核心要素：数据、算法和模型。然后..."
          },
          {
            "text": "机器学习是人工智能的一个分支，它使计算机系统能够从数据中学习并改进，而无需明确编程..."
          }
        ],
        // 2. 【核心新增】思维签名，用于多轮对话维持逻辑连贯
        "thought_signature": "asdf897asdf_logic_chain_v3"
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "blocked": false // 新增：更直观的布尔值判断
        }
      ],
      "avg_logprobs": -0.15, // 3. 【新增】平均对数概率，用于评估回答的置信度
      "groundingMetadata": {
        // 4. 【增强】联网搜索溯源
        "searchEntryPoint": {
          "renderedContent": "..."
        },
        "groundingChunks": [
          {
            "web": {
              "uri": "https://wikipedia.org/...",
              "title": "Machine Learning"
            }
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 150,
    "totalTokenCount": 160,
    // 5. 【新增】分项计费统计
    "cachedContentTokenCount": 0,
    "reasoningTokenCount": 45, // 思考过程消耗的 Token
    "mediaTokenCount": 0
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 模型请求调用函数
# response.candidates[0].content.parts 包含:
# {
#   "function_call": {
#     "name": "get_weather",
#     "args": {"city": "北京"},
#     "id": "call_123"  # Gemini 3 新增
#   }
# }

# 你返回结果时
response_part = {
  "role": "tool",  # 注意角色（不是 user）
  "parts": [
    {
      "function_response": {
        "name": "get_weather",
        "id": "call_123",  # 必须匹配 ID
        "response": {
          "result": "Sunny, 25°C"
        }
      }
    }
  ]
}

1

pip install google-generativeai python-dotenv

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

import google.generativeai as genai
import os
from dotenv import load_dotenv

load_dotenv()

# 配置 API Key
genai.configure(api_key=os.getenv("GEMINI_API_KEY"))

# 初始化模型
model = genai.GenerativeModel('gemini-1.5-pro')

def chat_with_gemini(user_message: str) -> str:
    """
    与 Gemini 进行对话

    Args:
        user_message: 用户输入的消息

    Returns:
        Gemini 的回复
    """
    try:
        response = model.generate_content(user_message)
        return response.text
    except Exception as e:
        return f"发生错误：{str(e)}"

# 使用示例
if __name__ == "__main__":
    question = "什么是机器学习？"
    answer = chat_with_gemini(question)
    print(f"问题：{question}")
    print(f"回答：{answer}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

def chat_with_stream(user_message: str):
    """流式输出，逐字显示"""

    model = genai.GenerativeModel('gemini-1.5-pro')

    response = model.generate_content(
        user_message,
        stream=True  # 启用流式输出
    )

    print("Gemini: ", end="", flush=True)
    for chunk in response:
        print(chunk.text, end="", flush=True)
    print()

# 使用
chat_with_stream("介绍一下 async/await 的工作原理")

1

用户提问 → AI 思考 → 等待... → 完整回复一次性显示

1

用户提问 → AI 思考 → 逐字显示 → 逐字显示 → 逐字显示 → 完成

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

data: {"content": "你"}

data: {"content": "好"}

data: {"content": "，"}

data: {"content": "我"}

data: {"content": "是"}

data: [DONE]

1
2
3
4
5
6
7
8
9

输入: "什么是机器学习？"
↓
模型预测: "机" (第1个token)
↓
模型预测: "器" (第2个token，基于前面的上下文)
↓
模型预测: "学" (第3个token)
↓
... 持续预测直到结束

1
2
3
4
5
6
7

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"机"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"器"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"学"},"finish_reason":null}]}

data: [DONE]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

1. 建立 HTTP 连接（设置 stream=True）
   ↓
2. 持续监听服务器推送的数据
   ↓
3. 每收到一个 chunk：
   - 解析 JSON 数据
   - 提取 delta.content（本次新增的内容）
   - 立即显示给用户
   - 累积到完整内容中
   ↓
4. 检测到 finish_reason 不为 null 或收到 [DONE]
   ↓
5. 关闭连接，流式输出完成

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 客户端需要维护一个缓冲区
buffer = ""

for chunk in response.iter_content():
    # 1. 将新数据追加到缓冲区
    buffer += chunk.decode('utf-8')

    # 2. 寻找完整的消息（以 \n\n 分隔）
    while '\n\n' in buffer:
        # 3. 提取一个完整的消息
        message, buffer = buffer.split('\n\n', 1)

        # 4. 解析并处理
        if message.startswith('data: '):
            data = message[6:]  # 去掉 "data: " 前缀
            if data == '[DONE]':
                break
            json_obj = json.loads(data)
            # 处理 json_obj...

1
2
3
4

# 后端代码中必须设置响应头
response.headers['X-Accel-Buffering'] = 'no'  # 针对 Nginx
response.headers['Cache-Control'] = 'no-cache'
response.headers['Connection'] = 'keep-alive'

1
2
3
4
5

location /api/chat {
    proxy_pass http://backend;
    proxy_buffering off;  # 关闭缓冲
    proxy_cache off;      # 关闭缓存
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "choices": [
    {
      "message": {
        "content": "机器学习是人工智能的一个分支..." // 完整内容
      },
      "finish_reason": "stop"
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// 第1次
{"choices": [{"delta": {"content": "机"}, "finish_reason": null}]}

// 第2次
{"choices": [{"delta": {"content": "器"}, "finish_reason": null}]}

// 第3次
{"choices": [{"delta": {"content": "学"}, "finish_reason": null}]}

// ...

// 最后一次
{"choices": [{"delta": {}, "finish_reason": "stop"}]}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

// 第1个 chunk：开始传输函数调用
{
  "choices": [{
    "delta": {
      "tool_calls": [{
        "index": 0,
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": ""
        }
      }]
    },
    "finish_reason": null
  }]
}

// 第2个 chunk：传输参数的第一部分
{
  "choices": [{
    "delta": {
      "tool_calls": [{
        "index": 0,
        "function": {
          "arguments": "{\"locat"
        }
      }]
    },
    "finish_reason": null
  }]
}

// 第3个 chunk：传输参数的第二部分
{
  "choices": [{
    "delta": {
      "tool_calls": [{
        "index": 0,
        "function": {
          "arguments": "ion\": \"Shang"
        }
      }]
    },
    "finish_reason": null
  }]
}

// 第4个 chunk：传输参数的最后部分
{
  "choices": [{
    "delta": {
      "tool_calls": [{
        "index": 0,
        "function": {
          "arguments": "hai\"}"
        }
      }]
    },
    "finish_reason": null
  }]
}

// 最后一个 chunk
{
  "choices": [{
    "delta": {},
    "finish_reason": "tool_calls"
  }]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 客户端处理示例
tool_calls = {}

for chunk in stream:
    delta = chunk['choices'][0]['delta']

    if 'tool_calls' in delta:
        for tool_call in delta['tool_calls']:
            index = tool_call['index']

            # 初始化工具调用
            if index not in tool_calls:
                tool_calls[index] = {
                    'id': tool_call.get('id', ''),
                    'type': tool_call.get('type', ''),
                    'function': {
                        'name': tool_call.get('function', {}).get('name', ''),
                        'arguments': ''
                    }
                }

            # 累积参数字符串
            if 'function' in tool_call and 'arguments' in tool_call['function']:
                tool_calls[index]['function']['arguments'] += tool_call['function']['arguments']

# 流结束后，解析完整的参数
for tool_call in tool_calls.values():
    args_str = tool_call['function']['arguments']
    tool_call['function']['arguments'] = json.loads(args_str)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

def stream_chat(user_message: str):
    """流式输出示例"""

    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": user_message}],
        stream=True  # 启用流式输出
    )

    print("AI: ", end="", flush=True)

    # 逐块处理响应
    for chunk in response:
        # 检查是否有内容
        if chunk.choices[0].delta.content:
            content = chunk.choices[0].delta.content
            print(content, end="", flush=True)

    print()  # 换行

# 使用
stream_chat("介绍一下 Python 的装饰器")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

def stream_chat_detailed(user_message: str):
    """详细的流式处理"""

    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": user_message}],
        stream=True
    )

    full_content = ""

    for chunk in response:
        # chunk 的结构
        # {
        #   "id": "chatcmpl-123",
        #   "object": "chat.completion.chunk",
        #   "created": 1677652288,
        #   "model": "gpt-3.5-turbo",
        #   "choices": [
        #     {
        #       "index": 0,
        #       "delta": {
        #         "content": "你"  # 本次返回的内容片段
        #       },
        #       "finish_reason": null
        #     }
        #   ]
        # }

        delta = chunk.choices[0].delta

        # 第一个 chunk 可能包含 role
        if delta.role:
            print(f"角色: {delta.role}")

        # 大部分 chunk 包含 content
        if delta.content:
            content = delta.content
            full_content += content
            print(content, end="", flush=True)

        # 最后一个 chunk 的 finish_reason 不为 null
        finish_reason = chunk.choices[0].finish_reason
        if finish_reason:
            print(f"\n\n结束原因: {finish_reason}")
            print(f"完整内容长度: {len(full_content)} 字符")

# 使用
stream_chat_detailed("什么是机器学习？")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

import requests
import json

def stream_chat_http(user_message: str):
    """使用 requests 库实现流式输出"""

    url = "https://api.openai.com/v1/chat/completions"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.getenv('OPENAI_API_KEY')}"
    }

    data = {
        "model": "gpt-3.5-turbo",
        "messages": [{"role": "user", "content": user_message}],
        "stream": True
    }

    # stream=True 启用流式接收
    response = requests.post(url, headers=headers, json=data, stream=True)

    print("AI: ", end="", flush=True)

    # 逐行读取响应
    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')

            # SSE 格式：data: {...}
            if line.startswith('data: '):
                data_str = line[6:]  # 去掉 "data: " 前缀

                # 结束标记
                if data_str == '[DONE]':
                    break

                try:
                    data = json.loads(data_str)
                    content = data['choices'][0]['delta'].get('content', '')
                    if content:
                        print(content, end="", flush=True)
                except json.JSONDecodeError:
                    continue

    print()

# 使用
stream_chat_http("介绍一下 async/await")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function streamChat(userMessage) {
  const stream = await client.chat.completions.create({
    model: "gpt-3.5-turbo",
    messages: [{ role: "user", content: userMessage }],
    stream: true,
  });

  process.stdout.write("AI: ");

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content || "";
    process.stdout.write(content);
  }

  console.log("\n");
}

// 使用
streamChat("介绍一下 JavaScript 的闭包");

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

async function streamChatFetch(userMessage) {
  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({
      model: "gpt-3.5-turbo",
      messages: [{ role: "user", content: userMessage }],
      stream: true,
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  process.stdout.write("AI: ");

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    // 解码数据
    const chunk = decoder.decode(value);
    const lines = chunk.split("\n");

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const data = line.slice(6);

        if (data === "[DONE]") {
          console.log("\n");
          return;
        }

        try {
          const parsed = JSON.parse(data);
          const content = parsed.choices[0]?.delta?.content || "";
          process.stdout.write(content);
        } catch (e) {
          // 忽略解析错误
        }
      }
    }
  }
}

// 使用
streamChatFetch("什么是 Promise？");

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// 注意：OpenAI API 不支持直接使用 EventSource（需要 POST 请求）
// 这里展示的是通用的 SSE 客户端实现

function streamChatBrowser(userMessage) {
  // 需要后端代理，因为 EventSource 只支持 GET 请求
  const eventSource = new EventSource(
    `/api/chat/stream?message=${encodeURIComponent(userMessage)}`,
  );

  const outputDiv = document.getElementById("output");

  eventSource.onmessage = (event) => {
    if (event.data === "[DONE]") {
      eventSource.close();
      return;
    }

    try {
      const data = JSON.parse(event.data);
      const content = data.choices[0]?.delta?.content || "";
      outputDiv.textContent += content;
    } catch (e) {
      console.error("解析错误:", e);
    }
  };

  eventSource.onerror = (error) => {
    console.error("SSE 错误:", error);
    eventSource.close();
  };
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

async function streamChatBrowser(userMessage) {
  const response = await fetch("/api/chat", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: userMessage,
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  const outputDiv = document.getElementById("output");

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split("\n");

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const data = line.slice(6);

        if (data === "[DONE]") {
          return;
        }

        try {
          const parsed = JSON.parse(data);
          const content = parsed.choices[0]?.delta?.content || "";
          outputDiv.textContent += content;
        } catch (e) {
          // 忽略解析错误
        }
      }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

def stream_chat_robust(user_message: str) -> str:
    """健壮的流式输出实现"""

    full_content = ""

    try:
        response = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[{"role": "user", "content": user_message}],
            stream=True,
            timeout=30  # 设置超时
        )

        for chunk in response:
            if chunk.choices[0].delta.content:
                content = chunk.choices[0].delta.content
                full_content += content
                print(content, end="", flush=True)

        print()
        return full_content

    except Exception as e:
        print(f"\n流式输出错误: {e}")
        return full_content  # 返回已接收的部分内容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

用户提问
    ↓
AI 分析问题
    ↓
AI 决定需要调用工具 ← 这里 AI 只是"决策"
    ↓
返回工具调用请求（函数名 + 参数）
    ↓
开发者执行实际函数 ← 这里才是真正的执行
    ↓
将结果返回给 AI
    ↓
AI 生成最终回复

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "type": "function", // 工具类型，目前主要是 function
  "function": {
    "name": "get_weather", // 函数名称（必需）
    "description": "获取指定城市的天气信息", // 函数描述（必需）
    "parameters": {
      // 参数定义（必需）
      "type": "object", // 参数类型，通常是 object
      "properties": {
        // 参数属性
        "city": {
          "type": "string",
          "description": "城市名称，如：北京、上海"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "description": "温度单位"
        }
      },
      "required": ["city"] // 必需参数列表
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  "properties": {
    "name": {
      "type": "string",
      "description": "用户姓名"
    },
    "age": {
      "type": "integer",
      "description": "用户年龄"
    },
    "price": {
      "type": "number",
      "description": "商品价格"
    },
    "is_active": {
      "type": "boolean",
      "description": "是否激活"
    }
  }
}

1
2
3
4
5

{
  "type": "string",
  "enum": ["small", "medium", "large"],
  "description": "尺寸大小"
}

1
2
3
4
5
6
7

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "description": "标签列表"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "type": "object",
  "properties": {
    "address": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "street": { "type": "string" }
      }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
  "type": "function",
  "function": {
    "name": "search_products",
    "description": "在商品数据库中搜索商品，支持按名称、分类、价格区间筛选",
    "parameters": {
      "type": "object",
      "properties": {
        "keyword": {
          "type": "string",
          "description": "搜索关键词，用于匹配商品名称或描述"
        },
        "category": {
          "type": "string",
          "enum": ["electronics", "clothing", "food", "books"],
          "description": "商品分类"
        },
        "min_price": {
          "type": "number",
          "description": "最低价格（元）"
        },
        "max_price": {
          "type": "number",
          "description": "最高价格（元）"
        },
        "sort_by": {
          "type": "string",
          "enum": ["price_asc", "price_desc", "popularity"],
          "description": "排序方式：价格升序、价格降序、热度"
        }
      },
      "required": ["keyword"] // 只有 keyword 是必需的
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "model": "gpt-3.5-turbo",
  "messages": [{ "role": "user", "content": "北京今天天气怎么样？" }],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称，如：北京、上海"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "温度单位"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"北京\", \"unit\": \"celsius\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "北京今天天气怎么样？"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123", // 工具调用的唯一 ID
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\": \"北京\", \"unit\": \"celsius\"}"
          }
        }
      ]
    },
    {
      "role": "tool", // 必须是 "tool"
      "tool_call_id": "call_abc123", // 必须与上面的 id 对应
      "content": "{\"temperature\": 15, \"condition\": \"晴朗\"}" // 工具执行结果
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

{
  "messages": [
    { "role": "user", "content": "北京和上海今天天气怎么样？" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\": \"北京\"}"
          }
        },
        {
          "id": "call_def456",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\": \"上海\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": 15, \"condition\": \"晴朗\"}"
    },
    {
      "role": "tool",
      "tool_call_id": "call_def456",
      "content": "{\"temperature\": 20, \"condition\": \"多云\"}"
    }
  ]
}

1
2

差：帮我写代码
好：你是一位精通 Python 的后端工程师，请帮我编写一个 FastAPI 接口，用于用户注册功能

1
2
3
4
5
6

请生成一个用户注册接口，要求：
- 使用 FastAPI 框架
- 验证邮箱格式
- 密码需要加密存储
- 返回 JSON 格式响应
- 包含错误处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

请分析以下代码的问题：

​```python
[代码内容]
​```

请指出：
1. 潜在的安全问题
2. 性能优化建议
3. 代码规范问题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

请将以下句子改写为正式语气：

示例1：
输入：这个东西真不错
输出：该产品质量优良

示例2：
输入：快点搞定吧
输出：请尽快完成

现在请改写：
输入：这代码写得太烂了

1
2
3
4
5
6
7
8

请一步步分析这个问题：

问题：一个班级有 30 名学生，其中 60% 是女生，女生中有 40% 戴眼镜，请问戴眼镜的女生有多少人？

请按以下步骤思考：
1. 计算女生总数
2. 计算戴眼镜的女生数
3. 给出最终答案

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

from openai import OpenAI
import json

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

def extract_with_prompt(text: str) -> dict:
    """使用 prompt 引导输出 JSON"""

    prompt = f"""
请从以下文本中提取信息，并以 JSON 格式返回。

要求的 JSON 格式：
{{
  "person": "人名",
  "location": "地点",
  "time": "时间"
}}

文本：{text}

请只返回 JSON，不要包含其他内容。
"""

    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": prompt}]
    )

    content = response.choices[0].message.content

    # 手动解析 JSON
    try:
        # 可能需要清理内容（去掉 markdown 代码块标记等）
        content = content.strip()
        if content.startswith("```json"):
            content = content[7:]
        if content.startswith("```"):
            content = content[3:]
        if content.endswith("```"):
            content = content[:-3]
        content = content.strip()

        return json.loads(content)
    except json.JSONDecodeError as e:
        print(f"JSON 解析失败: {e}")
        return {}

# 使用
result = extract_with_prompt("张三昨天在北京参加了会议")
print(result)