Installazzjoni tal-SDK tal-Python
F'din il-paġna
Installazzjoni tal-SDK tal-Python
L-SDK tal-Python openai hija l-librerija uffiċjali għall-interazzjoni mal-API. Din il-lezzjoni tgħidlek kif tinstallaha u tħejjilek struttura ta’ proġett nadifa li se tuża matul il-bqija tal-kors.
Prerekwiżiti u Installazzjoni
Għandek bżonn Python 3.10 jew aktar reċenti—il-minimu meħtieġ mill-SDK openai (verżjoni 3.42.1 sal-2 ta’ Novembru 2026, skont PyPI)—maniġer tal-pakketti (pip jew uv), u l-API key li ksibt fil-lezzjoni ta’ qabel. Ibda billi tikkonferma l-interpreter tiegħek, peress li l-magni ta’ żvilupp spiss jospitaw verżjonijiet multipli:
python --version
# Python 3.12.4
L-installazzjoni tieħu kmand wieħed biss: pip install openai, jew uv pip install openai jekk tuża uv, li huwa ferm aktar mgħaġġel. Madankollu, agħmilha drawwa li taħdem ġo ambjent virtwali. Dan jipprevjeni x-xena komuni fejn, sitt xhur wara, issib li żewġ proġetti jeħtieġu verżjonijiet inkompatibbli tal-istess librerija.
# Oħloq ambjent virtwali
python -m venv .venv
# Attiva (Linux/macOS)
source .venv/bin/activate
# Attiva (Windows)
.venv\Scripts\activate
# Installa l-SDK
pip install openai
Żewġ għodod jidhru kważi f’kull proġett u jistħoqqilhom li jiġu installati flimkien mal-SDK. Pydantic tgħin tiddefinixxi skemi għal Output Strutturat, li se tara aktar tard; python-dotenv ittagħbja l-fajl .env f’varjabbli tal-ambjent.
# Installa b'appoġġ għal dataclasses ta' Pydantic
pip install openai pydantic
# Installa b'python-dotenv għal varjabbli tal-ambjent
pip install openai python-dotenv
Fl-aħħar nett, ivverifika li l-import jaħdem u nnota l-verżjoni installata. Din hija l-ewwel biċċa informazzjoni li għandek tipprovdi jekk tiftaħ tikketta ta’ appoġġ.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Klijent Wieħed, L-APIs Kollha
L-SDK tidħor madwar oġġett klijent wieħed li jesponi l-pjattaforma kollha permezz ta’ sottomoduli. M’għandekx bżonn tistabbilixxi xejn ġdid biex tibdel mill-ġenerazzjoni tat-test għal embeddings jew moderazzjoni.
from openai import OpenAI
client = OpenAI()
# Responses API (test, sejħa tal-funzjoni, output strutturat)
client.responses.create(...)
# Chat Completions API (antik)
client.chat.completions.create(...)
# Embeddings
client.embeddings.create(...)
# Immaġni
client.images.generate(...)
# Awdjo
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderazzjoni
client.moderations.create(...)
Ikkonfigura l-Klijent għall-Kuntest Tiegħek
Id-defaults tal-SDK jaħdmu għall-esperimentazzjoni iżda jonqsu għall-applikazzjonijiet tal-web. Il-limitu ta’ żmien (timeout) default huwa ta’ għaxar minuti: f’API HTTP mistenni jirrispondi fi ħdan sekondi, dan ifisser li talba mwaqqfa torbot ħaddiem għal żmien twil wisq. Naqqsu, u żid in-numru ta’ tentattivi awtomatiċi (retries), li default huwa tnejn.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 sekonda (default: 10 minuti)
max_retries=3, # 3 tentattivi fuq żball (default: 2)
)
Il-parametru base_url jindirizza ħtieġa oħra: ir-rotta tas-sejħiet permezz ta’ proxy korporattiv li jirreġistra t-traffiku ‘l barra, jew lejn servizz li jesponi API kompatibbli.
# Utli għal proxies korporattivi jew APIs kompatibbli
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
Fl-aħħar nett, jekk l-applikazzjoni tiegħek tiddependi fuq asyncio—FastAPI, aiohttp, u bħal dawn—uża AsyncOpenAI. Il-klijent sinkronu jimblokaw il-luċċu tal-avvenimenti (event loop) waqt il-ġenerazzjoni, u jneħħi l-benefiċċji tal-kodiċi asinkronu.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Użu b'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?
Iストラttura l-Proġett Tiegħek
Adotta organizzazzjoni li tiżola l-konfigurazzjoni tal-klijent mill-bqija tal-kodiċi tiegħek mill-bidu nett. Dan jevita li tferrax għexieren ta’ sejħiet OpenAI() matul il-proġett tiegħek, kull waħda bl-issettjar tagħha stess.
my-project/
├── .env # API key (QATT ma tagħmel commit fuq git)
├── .gitignore # Jinkludi .env
├── requirements.txt # Dipendenzi
├── src/
│ ├── __init__.py
│ ├── client.py # Konfigurazzjoni tal-klijent OpenAI
│ └── main.py # Punt tad-dħul
└── tests/
└── test_api.py
Il-fajl src/client.py jiċċentralizza l-fabbrika tal-klijent: il-jum li tbiddel it-timeout jew iżżid proxy, ikollok bżonn timmodifika post wieħed biss.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Jirritorna klijent OpenAI ikkonfigurat."""
return OpenAI(
max_retries=3,
timeout=30.0
)
U requirements.txt jissikka l-verżjonijiet minimi mistennija:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Tliet Fallimenti Komuni
ModuleNotFoundError fuq openai kważi dejjem tfisser ambjent virtwali mhux attiv jew wieħed differenti minn fejn installajt il-pakkett. Sib l-interpreter li qed jintuża attwalment b’which python fuq Linux u macOS, jew where python fuq Windows, imbagħad erġa’ installa b’pip install --upgrade openai. AuthenticationError tirreferi għall-varjabbli tal-ambjent: ipprintja os.environ.get("OPENAI_API_KEY", "NOT DEFINED") biex teskludi problemi—il-fajl .env ma jiġix imtagħbija jekk load_dotenv() ma ġietx imsejħa qabel ma tinstantzja l-klijent. Fl-aħħar nett, żball dwar parametru mhux magħruf ġeneralment jindika SDK antik wisq għall-funzjoni li qed tuża: pip install --upgrade openai isolvi dan.
Punti Ewlenin
- Installa l-SDK b’
pip install openaiġo ambjent virtwali - Il-klijent
OpenAI()huwa l-punt tad-dħul għall-APIs kollha - Uża
AsyncOpenAI()għal applikazzjonijiet asinkroni - Ikkonfigura t-timeout u r-retries skont il-ħtiġijiet tiegħek
- Iストラttura l-proġett tiegħek b’fajl
.envu klijent iċċentralizzat