Instaliraj Python SDK
Na ovoj stranici
Instaliraj Python SDK
Python SDK openai službena je knjižnica za interakciju s API-jem. Ova će te lekcija provesti kroz postupak instalacije i postaviti čistu strukturu projekta koju ćeš koristiti tijekom ostatka tečaja.
Preduvjeti i instalacija
Trebaš Python 3.10 ili noviji—minimalni zahtjev SDK-a openai (verzija 3.42.1 od 2. studenog 2026., prema PyPI-ju), upravitelj paketa (pip ili uv) i API ključ koji si dobio/la u prethodnoj lekciji. Započni potvrdom svog interpretera jer razvojna računala često imaju više instaliranih verzija:
python --version
# Python 3.12.4
Instalacija zahtijeva samo jednu naredbu: pip install openai, ili uv pip install openai ako koristiš uv, što je znatno brže. Ipak, navikni se raditi unutar virtualnog okruženja. Time izbjegavaš čestu situaciju u kojoj, šest mjeseci kasnije, otkriješ da dva projekta zahtijevaju nekompatibilne verzije iste knjižnice.
# Stvori virtualno okruženje
python -m venv .venv
# Aktiviraj (Linux/macOS)
source .venv/bin/activate
# Aktiviraj (Windows)
.venv\Scripts\activate
# Instaliraj SDK
pip install openai
Dva prateća alata pojavljuju se u gotovo svakom projektu i zaslužuju instalaciju uz SDK. Pydantic pomaže u definiranju shema za strukturirani izlaz (Structured Output), što ćeš vidjeti kasnije; python-dotenv učitava datoteku .env u varijable okruženja.
# Instaliraj s podrškom za Pydantic podatkovne klase
pip install openai pydantic
# Instaliraj s python-dotenv za varijable okruženja
pip install openai python-dotenv
Na kraju, provjeri funkcionira li uvoz i zabilježi instaliranu verziju. To je prva informacija koju trebaš navesti ako otvoriš zahtjev za podršku.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Jedan klijent, svi API-ji
SDK se vrti oko jednog objekta klijenta koji izlaže cijelu platformu putem podmodula. Ne moraš instancirati ništa novo da bi prešao/la s generiranja teksta na ugradnje (embeddings) ili moderaciju.
from openai import OpenAI
client = OpenAI()
# Responses API (tekst, pozivanje funkcija, strukturirani izlaz)
client.responses.create(...)
# Chat Completions API (stariji)
client.chat.completions.create(...)
# Ugradnje (Embeddings)
client.embeddings.create(...)
# Slike
client.images.generate(...)
# Audio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderacija
client.moderations.create(...)
Konfiguriraj klijenta za svoj kontekst
Zadane postavke SDK-a dobre su za eksperimentiranje, ali nedovoljne za web aplikacije. Zadano vrijeme čekanja (timeout) iznosi deset minuta: u HTTP API-ju od kojeg se očekuje odgovor unutar nekoliko sekundi, to znači da zaglavljeni zahtjev predugo zauzima radnika (worker). Smanji to vrijeme i povećaj broj automatskih ponovnih pokušaja, koji je zadano postavljen na dva.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 sekundi (zadano: 10 minuta)
max_retries=3, # 3 pokušaja u slučaju greške (zadano: 2)
)
Parametar base_url rješava još jednu potrebu: usmjeravanje poziva kroz korporativni proxy koji bilježi odlazni promet ili prema servisu koji izlaže kompatibilan API.
# Korisno za korporativne proxyje ili kompatibilne API-je
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
Konačno, ako se tvoja aplikacija oslanja na asyncio—FastAPI, aiohttp i slično—koristi AsyncOpenAI. Sinkroni klijent bi blokirao petlju događaja tijekom generiranja, čime bi poništio prednosti asinkronog koda.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Korištenje s 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 you help you today?
Strukturiraj svoj projekt
Usvoji organizaciju koja od samog početka izolira konfiguraciju klijenta od ostatka tvog koda. Time izbjegavaš raspršivanje desetaka poziva OpenAI() kroz cijeli projekt, od kojih svaki ima vlastite postavke.
my-project/
├── .env # API ključ (NIKAD ne commitaj u git)
├── .gitignore # Uključuje .env
├── requirements.txt # Ovisnosti
├── src/
│ ├── __init__.py
│ ├── client.py # Konfiguracija OpenAI klijenta
│ └── main.py # Ulazna točka
└── tests/
└── test_api.py
Datoteka src/client.py centralizira tvornicu klijenta: dan kada promijeniš vrijeme čekanja ili dodaš proxy, trebaš modificirati samo jedno mjesto.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Vraća konfigurirani OpenAI klijent."""
return OpenAI(
max_retries=3,
timeout=30.0
)
A requirements.txt fiksira minimalne očekivane verzije:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Tri česta kvara
ModuleNotFoundError za openai gotovo uvijek signalizira neaktivno virtualno okruženje ili ono različito od onoga u kojem si instalirao/la paket. Lociraj interpreter koji se zapravo koristi s which python na Linuxu i macOSu, ili where python na Windowsima, zatim ponovno instaliraj s pip install --upgrade openai. AuthenticationError upućuje na varijablu okruženja: ispiši os.environ.get("OPENAI_API_KEY", "NOT DEFINED") kako bi isključio/la probleme—datoteka .env se ne učitava ako load_dotenv() nije pozvan prije instanciranja klijenta. Konačno, greška koja se odnosi na nepoznati parametar obično ukazuje na to da je SDK prestar za značajku koju koristiš: pip install --upgrade openai rješava to.
Ključne točke
- Instaliraj SDK s
pip install openaiunutar virtualnog okruženja - Klijent
OpenAI()ulazna je točka za sve API-je - Koristi
AsyncOpenAI()za asinkrone aplikacije - Konfiguriraj vrijeme čekanja i ponovne pokušaje prema svojim potrebama
- Strukturiraj projekt s datotekom
.envi centraliziranim klijentom