Instalarea SDK-ului Python
Pe această pagină
Instalarea SDK-ului Python
SDK-ul Python openai este biblioteca oficială pentru interacțiunea cu API-ul. Această lecție vă ghidează prin procesul de instalare și configurează o structură de proiect curată, pe care o veți utiliza pe tot parcursul cursului.
Condiții prealabile și instalare
Aveți nevoie de Python 3.10 sau o versiune mai nouă—cerința minimă impusă de SDK-ul openai (versiunea 3.42.1 la data de 2 noiembrie 2026, conform PyPI)—de un manager de pachete (pip sau uv) și de cheia API obținută în lecția anterioară. Începeți prin a confirma versiunea interpretorului, deoarece mașinile de dezvoltare găzduiesc adesea mai multe versiuni simultan:
python --version
# Python 3.12.4
Instalarea necesită o singură comandă: pip install openai, sau uv pip install openai dacă utilizați uv, care este semnificativ mai rapid. Totuși, faceți-vă un obicei din a lucra într-un mediu virtual. Acest lucru previne scenariul frecvent în care, peste șase luni, descoperiți că două proiecte necesită versiuni incompatibile ale aceleiași biblioteci.
# Crearea unui mediu virtual
python -m venv .venv
# Activare (Linux/macOS)
source .venv/bin/activate
# Activare (Windows)
.venv\Scripts\activate
# Instalarea SDK-ului
pip install openai
Două instrumente complementare apar în aproape fiecare proiect și merită instalate alături de SDK. Pydantic ajută la definirea schemelor pentru Structured Output (ieșire structurată), pe care o veți întâlni mai târziu; python-dotenv încarcă fișierul .env în variabile de mediu.
# Instalare cu suport pentru dataclass-uri Pydantic
pip install openai pydantic
# Instalare cu python-dotenv pentru variabile de mediu
pip install openai python-dotenv
În final, verificați dacă importul funcționează și rețineți versiunea instalată. Aceasta este prima informație pe care trebuie să o furnizați dacă deschideți un tichet de suport.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Un singur client, toate API-urile
SDK-ul se învârte în jurul unui singur obiect client care expune întreaga platformă prin submodule. Nu trebuie să instanțiați nimic nou pentru a trece de la generarea de text la embeddings sau moderare.
from openai import OpenAI
client = OpenAI()
# Responses API (text, apeluri de funcții, ieșire structurată)
client.responses.create(...)
# Chat Completions API (vechi)
client.chat.completions.create(...)
# Embeddings
client.embeddings.create(...)
# Imagini
client.images.generate(...)
# Audio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderare
client.moderations.create(...)
Configurarea clientului pentru contextul dumneavoastră
Valorile implicite ale SDK-ului funcționează pentru experimentare, dar sunt insuficiente pentru aplicațiile web. Timpul de așteptare (timeout) implicit este de zece minute: într-un API HTTP care ar trebui să răspundă în câteva secunde, acest lucru înseamnă că o cerere blocată ocupă un worker mult prea mult timp. Reduceți această valoare și măriți numărul de reîncercări automate, care implicit este setat la două.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 de secunde (implicit: 10 minute)
max_retries=3, # 3 încercări în caz de eroare (implicit: 2)
)
Parametrul base_url răspunde unei alte nevoi: rutarea apelurilor printr-un proxy corporativ care înregistrează traficul de ieșire sau către un serviciu care expune un API compatibil.
# Util pentru proxy-uri corporative sau API-uri compatibile
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
În final, dacă aplicația dumneavoastră se bazează pe asyncio—FastAPI, aiohttp și altele similare—utilizați AsyncOpenAI. Clientul sincron ar bloca bucla de evenimente (event loop) în timpul generării, anulând beneficiile codului asincron.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Utilizare cu await
import asyncio
async def main():
response = await async_client.responses.create(
model="gpt-5.6-terra",
input="Hello!"
)
print(response.output_text)
asyncio.run(main())
# Output: Hello! How can I help you today?
Structurarea proiectului
Adoptați o organizare care izolează configurarea clientului de restul codului încă de la început. Acest lucru evită dispersarea a zeci de apeluri OpenAI() în întregul proiect, fiecare cu propriile setări.
my-project/
├── .env # Cheia API (NU faceți commit în git)
├── .gitignore # Include .env
├── requirements.txt # Dependențe
├── src/
│ ├── __init__.py
│ ├── client.py # Configurarea clientului OpenAI
│ └── main.py # Punct de intrare
└── tests/
└── test_api.py
Fișierul src/client.py centralizează fabrica de clienți: în ziua în care modificați timeout-ul sau adăugați un proxy, trebuie să modificați un singur loc.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Returnează un client OpenAI configurat."""
return OpenAI(
max_retries=3,
timeout=30.0
)
Iar requirements.txt fixează versiunile minime așteptate:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Trei erori frecvente
O eroare ModuleNotFoundError pentru openai semnalează aproape întotdeauna un mediu virtual inactiv sau unul diferit de cel în care ați instalat pachetul. Localizați interpretorul utilizat efectiv cu which python pe Linux și macOS, sau where python pe Windows, apoi reinstalați cu pip install --upgrade openai. O eroare AuthenticationError indică o problemă legată de variabila de mediu: afișați os.environ.get("OPENAI_API_KEY", "NOT DEFINED") pentru a exclude cauzele posibile—fișierul .env nu este încărcat dacă load_dotenv() nu a fost apelat înainte de instanțierea clientului. În final, o eroare privind un parametru necunoscut indică de obicei un SDK prea vechi pentru funcționalitatea pe care o utilizați: pip install --upgrade openai rezolvă această problemă.
Puncte cheie
- Instalați SDK-ul cu
pip install openaiîntr-un mediu virtual - Clientul
OpenAI()este punctul de intrare pentru toate API-urile - Utilizați
AsyncOpenAI()pentru aplicațiile asincrone - Configurați timeout-ul și reîncercările în funcție de nevoile dumneavoastră
- Structurați proiectul cu un fișier
.envși un client centralizat