Namestitev Python SDK-ja
Na tej strani
Namestitev Python SDK-ja
Python SDK openai je uradna knjižnica za interakcijo z API-jem. Ta lekcija te bo popeljala skozi postopek namestitve in vzpostavila čisto strukturo projekta, ki jo boš uporabljal skozi ves preostanek tečaja.
Predpogoji in namestitev
Potrebuješ Python 3.10 ali novejši – to je najmanjša zahteva SDK-ja openai (različica 3.42.1 z dne 2. novembra 2026, po podatkih PyPI) – upravitelja paketov (pip ali uv) in ključ API, ki si ga pridobil v prejšnji lekciji. Najprej potrdi svoj tolmač, saj razvojna okolja pogosto gostijo več različic hkrati:
python --version
# Python 3.12.4
Namestitev zahteva le en ukaz: pip install openai ali uv pip install openai, če uporabljaš uv, kar je bistveno hitreje. Vendar si navadi delati znotraj virtualnega okolja. S tem preprečiš pogost scenarij, ko čez šest mesecev ugotoviš, da dva projekta zahtevata nezdružljivi različici iste knjižnice.
# Ustvari virtualno okolje
python -m venv .venv
# Aktiviraj (Linux/macOS)
source .venv/bin/activate
# Aktiviraj (Windows)
.venv\Scripts\activate
# Namesti SDK
pip install openai
Dva spremljevalca se pojavita v skoraj vsakem projektu in si zaslužita namestitev skupaj s SDK-jem. Pydantic pomaga definirati sheme za strukturirane izhode, kar boš videl kasneje; python-dotenv pa naloži datoteko .env v spremenljivke okolja.
# Namesti s podporo za podatkovne razrede Pydantic
pip install openai pydantic
# Namesti s python-dotenv za spremenljivke okolja
pip install openai python-dotenv
Na koncu preveri, ali uvoz deluje, in zabeleži nameščeno različico. To je prvi podatek, ki ga moraš navesti, če odpreš zahtevek za podporo.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
En odjemalec, vsi API-ji
SDK se vrti okoli enega samega objekta odjemalca, ki prek podmodulov omogoča dostop do celotne platforme. Ni treba ustvarjati ničesar novega, da bi preklopil z generiranja besedila na vdelave ali moderacijo.
from openai import OpenAI
client = OpenAI()
# Responses API (besedilo, klicanje funkcij, strukturirani izhod)
client.responses.create(...)
# Chat Completions API (starejši)
client.chat.completions.create(...)
# Vdelave (Embeddings)
client.embeddings.create(...)
# Slike
client.images.generate(...)
# Zvok
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderacija
client.moderations.create(...)
Konfiguracija odjemalca za tvoj kontekst
Privzete nastavitve SDK-ja zadostujejo za eksperimentiranje, a so nezadostne za spletne aplikacije. Privzeti časovni limit je deset minut: pri HTTP API-ju, od katerega pričakujemo odziv v nekaj sekundah, to pomeni, da zataknjena zahteva predolgo zaseda delavca. Zmanjšaj ga in povečaj število samodejnih poskusov ponovnega izvajanja, ki je privzeto nastavljeno na dva.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 sekund (privzeto: 10 minut)
max_retries=3, # 3 poskusi ob napaki (privzeto: 2)
)
Parameter base_url naslavlja drugo potrebo: preusmerjanje klicev prek korporacijskega posredniškega strežnika, ki beleži odhodni promet, ali do storitve, ki ponuja združljiv API.
# Uporabno za korporacijske posredniške strežnike ali združljive API-je
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
Če tvoja aplikacija temelji na asyncio – FastAPI, aiohttp in podobno – uporabi AsyncOpenAI. Sinhroni odjemalec bi med generiranjem blokiral zanko dogodkov in s tem izničil prednosti asinhrone kode.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Uporaba 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?
Strukturiraj svoj projekt
Takoj na začetku sprejmi organizacijo, ki loči konfiguracijo odjemalca od preostale kode. S tem se izogneš razpršenju ducatov klicev OpenAI() po tvojem projektu, od katerih ima vsak svoje nastavitve.
my-project/
├── .env # Ključ API (NIKOLI ne potisni v git)
├── .gitignore # Vključuje .env
├── requirements.txt # Odvisnosti
├── src/
│ ├── __init__.py
│ ├── client.py # Konfiguracija odjemalca OpenAI
│ └── main.py # Vstopna točka
└── tests/
└── test_api.py
Datoteka src/client.py centralizira tovarno odjemalcev: ko boš nekega dne spremenil časovni limit ali dodal posredniški strežnik, boš moral spremeniti le eno mesto.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Vrne konfiguriranega odjemalca OpenAI."""
return OpenAI(
max_retries=3,
timeout=30.0
)
Datoteka requirements.txt pa določi najmanjše pričakovane različice:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Tri pogoste napake
ModuleNotFoundError za openai skoraj vedno kaže na neaktivno virtualno okolje ali na to, da uporabljaš drugačno okolje od tistega, v katerem si namestil paket. Najdi tolmač, ki se dejansko uporablja, z ukazom which python v Linuxu in macOS ali where python v Windowsih, nato pa znova namesti z pip install --upgrade openai. Napaka AuthenticationError kaže na spremenljivko okolja: izpiši os.environ.get("OPENAI_API_KEY", "NOT DEFINED"), da izključiš težave – datoteka .env se ne naloži, če load_dotenv() ni bil poklican pred ustvarjanjem instance odjemalca. Nazadnje, napaka glede neznanega parametra običajno pomeni, da je SDK prestar za funkcijo, ki jo uporabljaš: to rešiš z pip install --upgrade openai.
Ključne ugotovitve
- Namesti SDK z
pip install openaiznotraj virtualnega okolja - Odjemalec
OpenAI()je vstopna točka za vse API-je - Za asinhrone aplikacije uporabi
AsyncOpenAI() - Časovni limit in število poskusov prilagodi svojim potrebam
- Projekt strukturiraj z datoteko
.envin centraliziranim odjemalcem