OpenAI API 实战教程：如何稳定获取结构化 JSON 输出

在与大型语言模型（LLM）交互时，一个常见的需求是从非结构化文本中提取信息并将其转换为结构化数据，例如 JSON。虽然我们可以在提示（Prompt）中要求模型返回 JSON，但结果有时并不可靠。模型可能会在 JSON 前后添加额外的解释性文本，或者在复杂情况下生成无效的 JSON 格式。

幸运的是，OpenAI API 提供了一个强大的功能——JSON 模式（JSON Mode），可以强制模型输出语法正确的 JSON 对象。本教程将通过一个实用的 Python 示例，带你一步步学习如何安全、可靠地调用 API 并获得稳定的 JSON 输出。

你将学到：

• 使用 .env 文件安全地管理你的 API 密钥。
• 构建有效的系统提示（System Prompt）来指导模型行为。
• 利用 response_format 参数启用 JSON 模式。
• 解析并使用 API 返回的 JSON 数据。

步骤 1：项目设置与环境配置

首先，我们需要搭建好开发环境。

1.1 安装必要的库

我们需要 openai 库来与 API 交互，以及 python-dotenv 库来管理环境变量。打开你的终端并运行以下命令：

pip install openai python-dotenv

1.2 创建 .env 文件管理密钥

在代码中硬编码 API 密钥是一个非常糟糕的做法，它不仅不安全，而且不灵活。我们将在项目根目录下创建一个名为 .env 的文件来存放我们的配置信息。

创建一个 .env 文件，并填入以下内容（请替换成你自己的信息）：

# .env 文件

# 输入你在 uiuiapi.com 获取的 API 密钥或官方API秘钥
API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# API 的基础 URL (例如 OpenAI 官方地址或uiuiAPI地址)
BASE_URL="https://uiuiapi地址/v1"

# 你希望使用的模型名称 (可选)
MODEL_NAME="gpt-4o"

💡 提示： 将 .env 文件添加到你的 .gitignore 中，以避免意外地将敏感信息提交到代码仓库。

步骤 2：编写 Python 脚本

现在，让我们开始编写核心的 Python 代码。我们将创建一个名为 extract_info.py 的文件。

2.1 导入库并加载配置

代码的开头部分负责导入所需模块，并从我们刚刚创建的 .env 文件中安全地加载配置。

import os
import json
from openai import OpenAI
from dotenv import load_dotenv

def main():
    """
    主函数，从 .env 文件加载配置并执行API调用。
    """
    # --- 1. 从 .env 文件加载环境变量 ---
    load_dotenv()

    # 使用 os.getenv() 安全地获取配置
    api_key = os.getenv("API_KEY")
    base_url = os.getenv("BASE_URL")
    model_name = os.getenv("MODEL_NAME", "gpt-4o") # 提供默认值

    # --- 检查配置是否存在 ---
    if not api_key or not base_url:
        print("错误：API_KEY 或 BASE_URL 未在 .env 文件中设置。")
        return

    print("--- 配置加载成功 ---")
    print(f"将要使用的模型: {model_name}")

    # ... 后续代码将在这里添加 ...

这段代码确保了我们的程序在运行前能够正确读取到所有必要的配置信息，如果配置缺失，它会友好地提示并退出。

2.2 初始化客户端并构造提示

接下来，我们初始化 OpenAI 客户端，并精心构造一个提示，告诉模型我们想要做什么。

    # ... 接上文 ...

    # --- 2. 初始化API客户端 ---
    try:
        client = OpenAI(
            api_key=api_key,
            base_url=base_url,
        )
    except Exception as e:
        print(f"初始化OpenAI客户端时出错: {e}")
        return

    # --- 3. 准备API请求 ---
    source_text = "user email is test@example.com, and the user id is 12345."
    messages = [
        {"role": "system", "content": "You are a helpful assistant designed to output JSON."},
        {"role": "user", "content": f"From the text '{source_text}', extract the email and user ID. Please provide the output in a JSON format where the keys are exactly 'email' and 'user_id'."}
    ]

这里有两个关键点：

1. 系统消息 (**role: "system"**): 我们给模型设定了一个角色：“你是一个旨在输出 JSON 的有用助手”。这为模型的行为提供了高级指导。
2. 用户消息 (**role: "user"**): 我们给出了具体的指令，包括要处理的文本和对输出 JSON 格式的明确要求（键名必须是 email 和 user_id）。

2.3 调用 API 并启用 JSON 模式

这是整个流程中最核心的一步。我们在调用 API 时，通过设置 response_format 参数来启用 JSON 模式。

    # ... 接上文 ...

    # --- 4. 调用API并处理响应 ---
    print(f"\n--- 正在调用 API ... ---")
    try:
        response = client.chat.completions.create(
            model=model_name,
            # 这是启用 JSON 模式的关键！
            response_format={"type": "json_object"}, 
            messages=messages
        )
        json_content_string = response.choices[0].message.content

        print("API 调用成功，已收到响应。")
        print("\n--- API返回的原始JSON字符串 ---")
        print(json_content_string)

        # ... 后续解析代码 ...

    except Exception as e:
        print(f"\n调用API时发生错误: {e}")
        return
```response_format={"type": "json_object"}` 会指示模型**必须**返回一个语法正确的 JSON 对象。这比任何在提示文本中的要求都更加可靠和强制。

#### 2.4 解析并使用结果

API 返回的是一个 JSON 格式的字符串。我们需要将其解析为 Python 字典才能方便地使用。

```python
        # ... 接上文 ...

        # 解析并提取结果
        parsed_json = json.loads(json_content_string)
        print("\n--- 解析后的Python字典 ---")
        print(parsed_json)

        email = parsed_json.get('email')
        user_id = parsed_json.get('user_id')
        print("\n--- 提取结果 ---")
        print(f"Email: {email}" if email else "Email: 未找到")
        print(f"ID: {user_id}" if user_id else "ID: 未找到")

    except Exception as e:
        print(f"\n调用API时发生错误: {e}")
        return

if __name__ == "__main__":
    main()

我们使用 json.loads() 将字符串转换为字典，然后通过 .get() 方法安全地提取所需信息。

步骤 3：运行脚本并查看结果

将以上所有代码片段整合到 extract_info.py 文件中。现在，在你的终端中运行它：

python extract_info.py

如果一切顺利，你将看到类似以下的输出：

--- 配置加载成功 ---
将要使用的模型: gpt-4o

--- 正在调用 API ... ---
API 调用成功，已收到响应。

--- API返回的原始JSON字符串 ---
{
  "email": "test@example.com",
  "user_id": "12345"
}

--- 解析后的Python字典 ---
{'email': 'test@example.com', 'user_id': '12345'}

--- 提取结果 ---
Email: test@example.com
ID: 12345

如你所见，我们得到了一个干净、格式正确的 JSON，并且可以轻松地从中提取数据。

界智通（jieagi）总结与拓展

通过本教程，你掌握了使用 OpenAI API 的 JSON 模式来获取结构化数据的核心技巧。

关键要点回顾：

• 安全第一: 始终使用环境变量（.env 文件）管理敏感信息。
• 明确指示: 通过系统消息和用户消息清晰地传达你的意图。
• 强制格式: 使用 response_format={"type": "json_object"} 来确保获得可靠的 JSON 输出。
• 稳健处理: 使用 try...except 块和 .get() 方法让你的代码更加健壮。

这项技术可以广泛应用于各种场景，例如：

• 数据抓取：将网页文章内容转换为结构化的数据。
• 用户输入解析：将用户的自然语言命令转换为程序可以执行的参数。
• 日志分析：从混乱的日志文本中提取关键事件信息。
• 智能客服：从客户对话中自动提取订单号、联系方式等信息。

现在，你可以尝试修改 source_text 和用户提示，来处理更复杂的文本提取任务了！

​