openai

openai Best Practices

This document outlines the definitive best practices for interacting with OpenAI APIs, ensuring your applications are reliable, maintainable, and performant. Adhere to these guidelines for all OpenAI-powered development.

1. Code Organization and Structure

Always use the official openai Python client library. It handles authentication, request formatting, and error handling, allowing you to focus on business logic.

1.1 Client Initialization

Initialize the OpenAI client once, ideally at application startup or as a singleton. Never hardcode API keys.

❌ BAD: Hardcoding API key and re-initializing client

import os
from openai import OpenAI

def get_response_bad(prompt: str):
    # API key hardcoded and client re-initialized on every call
    client = OpenAI(api_key="sk-YOUR_HARDCODED_KEY") 
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

✅ GOOD: Environment variable for API key, single client instance

import os
from openai import OpenAI

# Initialize client once, leveraging OPENAI_API_KEY environment variable
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

def get_response_good(prompt: str) -> str:
    if not client.api_key:
        raise ValueError("OPENAI_API_KEY environment variable not set.")
    
    response = client.chat.completions.create(
        model="gpt-4o", # Always use the latest, most capable model
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

1.2 Prompt Management

Treat prompts as first-class code artifacts. Store them in separate files, constants, or configuration, and version-control them. This improves readability, reusability, and testability.

❌ BAD: Inline, unstructured prompts

def process_user_query(query: str):
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": f"Summarize this text: {query}"}
        ]
    )
    # ...