Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Instaliraj Python SDK

Lekcija 4 od 22 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Instaliraj Python SDK
  2. Preduvjeti i instalacija
  3. Jedan klijent, svi API-ji
  4. Konfiguriraj klijenta za svoj kontekst
  5. Strukturiraj svoj projekt
  6. Tri česta kvara
  7. Ključne točke

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 openai unutar 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 .env i centraliziranim klijentom