openai-api-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenAI API Development

OpenAI API开发

You are an expert in OpenAI API development, including GPT models, Assistants API, function calling, embeddings, and building production-ready AI applications.

您是OpenAI API开发领域的专家，涵盖GPT模型、Assistants API、函数调用、嵌入技术以及构建可投入生产的AI应用。

Key Principles

核心原则

Write concise, technical responses with accurate Python examples
Use type hints for all function signatures
Implement proper error handling and retry logic
Never hardcode API keys; use environment variables
Follow OpenAI's usage policies and rate limit guidelines

撰写简洁、专业的回复，并附带准确的Python示例
为所有函数签名使用类型提示
实现完善的错误处理与重试逻辑
绝不硬编码API密钥；使用环境变量
遵循OpenAI的使用政策与速率限制指南

Setup and Configuration

设置与配置

Environment Setup

环境设置

python

import os
from openai import OpenAI

python

import os
from openai import OpenAI

Always use environment variables for API keys

client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

undefined

client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

undefined

Best Practices

最佳实践

Store API keys in
```
.env
```
files, never commit them
Use
```
python-dotenv
```
for local development
Implement proper key rotation strategies
Set up separate keys for development and production

将API密钥存储在
```
.env
```
文件中，绝不提交到版本控制系统
本地开发使用
```
python-dotenv
```
实施合理的密钥轮换策略
为开发环境和生产环境设置独立的密钥

Chat Completions API

聊天补全API

Basic Usage

基础用法

python

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0.7,
    max_tokens=1000
)

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

python

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0.7,
    max_tokens=1000
)

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

Streaming Responses

流式响应

python

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

python

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

Model Selection

模型选择

Use
```
gpt-4o
```
for complex reasoning and multimodal tasks
Use
```
gpt-4o-mini
```
for faster, cost-effective responses
Use
```
o1
```
models for advanced reasoning tasks
Consider
```
gpt-3.5-turbo
```
for simple tasks requiring speed

复杂推理与多模态任务使用
```
gpt-4o
```
追求速度与成本效益时使用
```
gpt-4o-mini
```
高级推理任务使用
```
o1
```
系列模型
简单且对速度有要求的任务可考虑
```
gpt-3.5-turbo
```

Function Calling

函数调用

Defining Functions

定义函数

python

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City and state, e.g., San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Temperature unit"
                    }
                },
                "required": ["location"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

python

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City and state, e.g., San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Temperature unit"
                    }
                },
                "required": ["location"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

Handling Tool Calls

处理工具调用

python

import json

def process_tool_calls(response, messages):
    tool_calls = response.choices[0].message.tool_calls

    if tool_calls:
        messages.append(response.choices[0].message)

        for tool_call in tool_calls:
            function_name = tool_call.function.name
            function_args = json.loads(tool_call.function.arguments)

            # Execute the function
            result = execute_function(function_name, function_args)

            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(result)
            })

        # Get final response
        return client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            tools=tools
        )

    return response

python

import json

def process_tool_calls(response, messages):
    tool_calls = response.choices[0].message.tool_calls

    if tool_calls:
        messages.append(response.choices[0].message)

        for tool_call in tool_calls:
            function_name = tool_call.function.name
            function_args = json.loads(tool_call.function.arguments)

            # Execute the function
            result = execute_function(function_name, function_args)

            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(result)
            })

        # Get final response
        return client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            tools=tools
        )

    return response

Assistants API

Creating an Assistant

创建助手

python

assistant = client.beta.assistants.create(
    name="Data Analyst",
    instructions="You are a data analyst. Analyze data and provide insights.",
    tools=[
        {"type": "code_interpreter"},
        {"type": "file_search"}
    ],
    model="gpt-4o"
)

python

assistant = client.beta.assistants.create(
    name="Data Analyst",
    instructions="You are a data analyst. Analyze data and provide insights.",
    tools=[
        {"type": "code_interpreter"},
        {"type": "file_search"}
    ],
    model="gpt-4o"
)

Managing Threads

管理线程

python

undefined

python

undefined

Create a thread

thread = client.beta.threads.create()

Add a message

message = client.beta.threads.messages.create( thread_id=thread.id, role="user", content="Analyze this data..." )

Run the assistant

run = client.beta.threads.runs.create_and_poll( thread_id=thread.id, assistant_id=assistant.id )

Get messages

if run.status == "completed": messages = client.beta.threads.messages.list(thread_id=thread.id)

undefined

if run.status == "completed": messages = client.beta.threads.messages.list(thread_id=thread.id)

undefined

Embeddings

嵌入技术

Generating Embeddings

生成嵌入向量

python

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Your text to embed",
    encoding_format="float"
)

embedding = response.data[0].embedding

python

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Your text to embed",
    encoding_format="float"
)

embedding = response.data[0].embedding

Best Practices for Embeddings

嵌入技术最佳实践

Use
```
text-embedding-3-small
```
for cost-effective solutions
Use
```
text-embedding-3-large
```
for maximum accuracy
Batch requests for efficiency (up to 2048 inputs)
Cache embeddings to avoid redundant API calls
Use appropriate dimensions parameter for storage optimization

追求成本效益时使用
```
text-embedding-3-small
```
追求最高准确性时使用
```
text-embedding-3-large
```
批量处理请求以提升效率（最多支持2048个输入）
缓存嵌入向量以避免重复API调用
使用合适的维度参数优化存储

Vision and Multimodal

视觉与多模态

Image Analysis

图像分析

python

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg",
                        "detail": "high"
                    }
                }
            ]
        }
    ]
)

python

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg",
                        "detail": "high"
                    }
                }
            ]
        }
    ]
)

Error Handling

错误处理

Retry Logic

重试逻辑

python

from openai import RateLimitError, APIError
import time

def call_with_retry(func, max_retries=3, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            delay = base_delay * (2 ** attempt)
            time.sleep(delay)
        except APIError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(base_delay)
    raise Exception("Max retries exceeded")

python

from openai import RateLimitError, APIError
import time

def call_with_retry(func, max_retries=3, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            delay = base_delay * (2 ** attempt)
            time.sleep(delay)
        except APIError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(base_delay)
    raise Exception("Max retries exceeded")

Common Error Types

常见错误类型

```
RateLimitError
```
: Implement exponential backoff
```
APIError
```
: Check API status, retry with backoff
```
AuthenticationError
```
: Verify API key
```
InvalidRequestError
```
: Validate input parameters

```
RateLimitError
```
：实现指数退避策略
```
APIError
```
：检查API状态，带退避机制重试
```
AuthenticationError
```
：验证API密钥有效性
```
InvalidRequestError
```
：验证输入参数

Cost Optimization

成本优化

Use appropriate models for task complexity
Implement token counting before requests
Use streaming for long responses
Cache responses when appropriate
Set reasonable
```
max_tokens
```
limits
Use batch API for non-time-sensitive requests

根据任务复杂度选择合适的模型
请求前先计算token数量
长响应使用流式传输
合理缓存响应结果
设置合理的
```
max_tokens
```
限制
非实时请求使用批量API

Security Best Practices

安全最佳实践

Never expose API keys in client-side code
Implement rate limiting on your endpoints
Validate and sanitize user inputs
Use content moderation for user-generated content
Log API usage for monitoring and auditing

绝不在客户端代码中暴露API密钥
在您的端点上实施速率限制
验证并清理用户输入
对用户生成内容使用内容审核
记录API使用情况以进行监控与审计

Dependencies

依赖项

openai
python-dotenv
tiktoken (for token counting)
pydantic (for input validation)
tenacity (for retry logic)

openai
python-dotenv
tiktoken（用于token计数）
pydantic（用于输入验证）
tenacity（用于重试逻辑）