Instalacja Python SDK
Na tej stronie
Instalacja Python SDK
Python SDK openai to oficjalna biblioteka umożliwiająca interakcję z API. W tej lekcji przeprowadzimy Cię przez proces instalacji i skonfigurujemy czystą strukturę projektu, której będziesz używać przez cały kurs.
Wymagania wstępne i instalacja
Potrzebujesz Pythona w wersji 3.10 lub nowszej – jest to minimum wymagane przez SDK openai (wersja 3.42.1 według stanu na 2 listopada 2026 r., zgodnie z danymi z PyPI), menedżera pakietów (pip lub uv) oraz klucz API, który uzyskałeś w poprzedniej lekcji. Zacznij od potwierdzenia wersji swojego interpretera, ponieważ na maszynach deweloperskich często hostowanych jest wiele wersji:
python --version
# Python 3.12.4
Instalacja wymaga tylko jednego polecenia: pip install openai lub uv pip install openai, jeśli używasz uv, co jest znacznie szybsze. Warto jednak wyrobić sobie nawyk pracy wewnątrz wirtualnego środowiska. Zapobiega to typowej sytuacji, w której po sześciu miesiącach okazuje się, że dwa projekty wymagają niekompatybilnych wersji tej samej biblioteki.
# Utwórz wirtualne środowisko
python -m venv .venv
# Aktywuj (Linux/macOS)
source .venv/bin/activate
# Aktywuj (Windows)
.venv\Scripts\activate
# Zainstaluj SDK
pip install openai
Dwaj towarzysze pojawiają się w niemal każdym projekcie i zasługują na zainstalowanie obok SDK. Pydantic pomaga definiować schematy dla Structured Output, co zobaczysz później; python-dotenv ładuje plik .env do zmiennych środowiskowych.
# Instalacja z obsługą klas danych Pydantic
pip install openai pydantic
# Instalacja z python-dotenv dla zmiennych środowiskowych
pip install openai python-dotenv
Na koniec sprawdź, czy import działa poprawnie, i zanotuj zainstalowaną wersję. To pierwsza informacja, którą należy podać przy zgłaszaniu błędu do wsparcia technicznego.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Jeden klient, wszystkie API
SDK opiera się na pojedynczym obiekcie klienta, który udostępnia całą platformę za pośrednictwem podmodułów. Nie musisz tworzyć żadnych nowych instancji, aby przejść z generowania tekstu do osadzania (embeddings) lub moderacji.
from openai import OpenAI
client = OpenAI()
# Responses API (tekst, wywoływanie funkcji, strukturyzowane wyjście)
client.responses.create(...)
# Chat Completions API (przestarzałe)
client.chat.completions.create(...)
# Embeddings
client.embeddings.create(...)
# Obrazy
client.images.generate(...)
# Audio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderacja
client.moderations.create(...)
Konfiguracja klienta dla Twojego kontekstu
Domyślne ustawienia SDK sprawdzają się podczas eksperymentów, ale są niewystarczające dla aplikacji internetowych. Domyślny limit czasu (timeout) wynosi dziesięć minut: w przypadku API HTTP, które powinno odpowiadać w ciągu kilku sekund, oznacza to, że zawieszone żądanie blokuje worker’a znacznie zbyt długo. Skróć ten czas i zwiększ liczbę automatycznych ponowień, której wartość domyślna wynosi dwa.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 sekund (domyślnie: 10 minut)
max_retries=3, # 3 próby w przypadku błędu (domyślnie: 2)
)
Parametr base_url rozwiązuje inny problem: kierowanie wywołań przez firmowy serwer proxy, który rejestruje ruch wychodzący, lub do usługi udostępniającej kompatybilne API.
# Przydatne dla firmowych serwerów proxy lub kompatybilnych API
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
Na koniec, jeśli Twoja aplikacja opiera się na asyncio – FastAPI, aiohttp i tym podobne – użyj AsyncOpenAI. Klient synchroniczny blokowałby pętlę zdarzeń podczas generowania, niwecząc zalety kodu asynchronicznego.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Użycie z 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?
Strukturyzacja projektu
Przyjmij organizację, która od samego początku oddziela konfigurację klienta od reszty kodu. Unikniesz w ten sposób rozrzucenia dziesiątek wywołań OpenAI() w całym projekcie, z których każde miałoby własne ustawienia.
my-project/
├── .env # Klucz API (NIGDY nie commituj do gita)
├── .gitignore # Zawiera .env
├── requirements.txt # Zależności
├── src/
│ ├── __init__.py
│ ├── client.py # Konfiguracja klienta OpenAI
│ └── main.py # Punkt wejścia
└── tests/
└── test_api.py
Plik src/client.py centralizuje fabrykę klienta: w dniu, w którym zmienisz limit czasu lub dodasz proxy, będziesz musiał zmodyfikować tylko jedno miejsce.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Zwraca skonfigurowanego klienta OpenAI."""
return OpenAI(
max_retries=3,
timeout=30.0
)
Plik requirements.txt ustala minimalne oczekiwane wersje:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Trzy typowe błędy
Błąd ModuleNotFoundError dotyczący openai prawie zawsze oznacza, że wirtualne środowisko jest nieaktywne lub inne niż to, w którym zainstalowano pakiet. Zlokalizuj interpreter, który jest faktycznie używany, za pomocą polecenia which python w systemach Linux i macOS lub where python w systemie Windows, a następnie ponownie zainstaluj pakiet poleceniem pip install --upgrade openai. Błąd AuthenticationError wskazuje na problem ze zmienną środowiskową: wydrukuj os.environ.get("OPENAI_API_KEY", "NOT DEFINED"), aby wykluczyć usterki – plik .env nie zostanie załadowany, jeśli load_dotenv() nie zostało wywołane przed utworzeniem instancji klienta. Na koniec błąd dotyczący nieznanego parametru zazwyczaj oznacza, że SDK jest zbyt stare dla funkcji, z której korzystasz: rozwiąże to polecenie pip install --upgrade openai.
Kluczowe wnioski
- Zainstaluj SDK za pomocą
pip install openaiwewnątrz wirtualnego środowiska - Klient
OpenAI()jest punktem wejścia dla wszystkich API - Używaj
AsyncOpenAI()w aplikacjach asynchronicznych - Skonfiguruj limit czasu i liczbę ponowień zgodnie ze swoimi potrzebami
- Ustrukturyzuj projekt, używając pliku
.envi scentralizowanego klienta