1. 理解API响应头部的重要性
在使用openai api时，除了获取模型生成的文本内容外，有时我们还需要访问api响应的http头部信息。这些头部信息通常包含重要的元数据，例如：
- 速率限制（Rate Limits）：x-ratelimit-limit (总限制), x-ratelimit-remaining (剩余次数), x-ratelimit-reset (重置时间) 等，对于管理API调用频率至关重要。
- 请求ID：用于调试和追踪特定请求。
- 内容类型、编码等标准HTTP头部。
然而，OpenAI Python SDK的默认调用方式（如client.chat.completions.create）通常会直接返回经过解析的模型输出对象，而将底层的HTTP响应细节（包括头部）进行了抽象。
2. 通过with_raw_response获取原始响应
为了访问这些被抽象的HTTP头部，OpenAI Python SDK提供了一个特殊的修饰符with_raw_response。当与API调用方法（如create）结合使用时，它会返回一个包含原始HTTP响应数据的对象，而不是直接解析后的模型输出。
以下是获取API响应头部的具体步骤和示例代码：
步骤一：导入OpenAI库并初始化客户端
立即学习“Python免费学习笔记（深入）”；
首先，确保你已经安装了openai库，并按照常规方式初始化OpenAI客户端。
from openai import OpenAI
import os # 通常用于获取API密钥
# 确保你的OPENAI_API_KEY环境变量已设置
# 或者直接传递 api_key="Your_API_Key"
client = OpenAI(
api_key=os.environ.get("OPENAI_API_KEY")
)步骤二：使用with_raw_response进行API调用
在调用API方法（例如chat.completions.create）之前，在其前面加上.with_raw_response。这将返回一个APIRawResponse对象。
raw_response = client.chat.completions.with_raw_response.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Hello world"}]
)这个raw_response对象封装了HTTP响应的所有细节。
步骤三：解析模型输出和提取HTTP头部
从raw_response对象中，你可以通过.parse()方法获取到标准解析后的模型输出（例如ChatCompletion对象），并通过.headers属性访问HTTP头部字典。
# 解析出ChatCompletion对象
chat_completion = raw_response.parse()
print("Chat Completion:", chat_completion.choices[0].message.content)
# 获取HTTP头部信息
response_headers = raw_response.headers
print("\nHTTP Response Headers:")
for key, value in response_headers.items():
print(f" {key}: {value}")
# 示例：获取速率限制信息
print("\nRate Limit Information (if available):")
print(f" X-RateLimit-Limit-Requests: {response_headers.get('x-ratelimit-limit-requests', 'N/A')}")
print(f" X-RateLimit-Remaining-Requests: {response_headers.get('x-ratelimit-remaining-requests', 'N/A')}")
print(f" X-RateLimit-Reset-Requests: {response_headers.get('x-ratelimit-reset-requests', 'N/A')}")完整示例代码：
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ.get("OPENAI_API_KEY")
)
try:
raw_response = client.chat.completions.with_raw_response.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Hello world"}]
)
# 解析ChatCompletion对象
chat_completion = raw_response.parse()
print("模型响应内容:", chat_completion.choices[0].message.content)
# 获取HTTP头部信息
response_headers = raw_response.headers
print("\nHTTP响应头部信息:")
for key, value in response_headers.items():
print(f" {key}: {value}")
# 提取并打印速率限制信息
print("\n速率限制信息:")
print(f" 请求限制 (Requests): {response_headers.get('x-ratelimit-limit-requests', '未提供')}")
print(f" 剩余请求 (Requests): {response_headers.get('x-ratelimit-remaining-requests', '未提供')}")
print(f" 重置时间 (Requests): {response_headers.get('x-ratelimit-reset-requests', '未提供')}")
print(f" 令牌限制 (Tokens): {response_headers.get('x-ratelimit-limit-tokens', '未提供')}")
print(f" 剩余令牌 (Tokens): {response_headers.get('x-ratelimit-remaining-tokens', '未提供')}")
print(f" 重置时间 (Tokens): {response_headers.get('x-ratelimit-reset-tokens', '未提供')}")
except Exception as e:
print(f"发生错误: {e}")
3. 注意事项
- 通用性：with_raw_response修饰符适用于OpenAI Python SDK中的大多数API调用，例如client.embeddings.with_raw_response.create()等。
- 错误处理：在实际应用中，建议添加try-except块来捕获API调用可能发生的异常。
- API密钥安全：始终通过环境变量或其他安全方式管理API密钥，避免硬编码。
- 头部键名：HTTP头部键名通常不区分大小写，但在Python字典中访问时，建议使用其标准小写形式（如x-ratelimit-limit-requests）。
总结
通过使用OpenAI Python SDK的with_raw_response方法，开发者可以轻松地获取API调用的原始HTTP响应，进而访问包括速率限制在内的各种HTTP头部信息。这对于精细化管理API使用、进行调试以及理解API行为模式都非常重要。掌握这一技巧，能帮助你更有效地利用OpenAI API。
