Przejdź do głównej treści
Polski— Wybierz język
Menu

Instalacja Python SDK

Lekcja 4 z 22 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Instalacja Python SDK
  2. Wymagania wstępne i instalacja
  3. Jeden klient, wszystkie API
  4. Konfiguracja klienta dla Twojego kontekstu
  5. Strukturyzacja projektu
  6. Trzy typowe błędy
  7. Kluczowe wnioski

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 openai wewną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 .env i scentralizowanego klienta