Asenna Python SDK
Tällä sivulla
Asenna Python SDK
openai-Python-SDK on virallinen kirjasto API:n kanssa vuorovaikuttamiseen. Tässä oppitunnissa käydään läpi asennus ja luodaan siisti projektirakenne, jota tulet käyttämään koko kurssin ajan.
Edellytykset ja asennus
Tarvitset Python-version 3.10 tai uudemman – tämä on openai-SDK:n vaatima minimiversio (versio 3.42.1 marraskuun 2. päivänä 2026 PyPI:n mukaan) – paketinhallintatyökalun (pip tai uv) sekä API-avaimen, jonka hankit edellisellä oppitunnilla. Aloita varmistamalla tulkkinsi versio, sillä kehityskoneilla on usein useita versioita samanaikaisesti:
python --version
# Python 3.12.4
Asennus vaatii vain yhden komennon: pip install openai, tai uv pip install openai, jos käytät uv:tä, joka on huomattavasti nopeampi. Tee kuitenkin tavaksi työskennellä virtuaaliympäristön sisällä. Tämä estää yleisen tilanteen, jossa kuuden kuukauden päästä huomaat kahden projektin vaativan yhteensopimattomia versioita samasta kirjastosta.
# Luo virtuaaliympäristö
python -m venv .venv
# Aktivoi (Linux/macOS)
source .venv/bin/activate
# Aktivoi (Windows)
.venv\Scripts\activate
# Asenna SDK
pip install openai
Kaksi lisätyökalua esiintyy lähes jokaisessa projektissa ja ne kannattaa asentaa SDK:n rinnalle. Pydantic auttaa määrittelemään skeemoja jäsennetylle tulosteelle (Structured Output), jonka näet myöhemmin; python-dotenv lataa .env-tiedoston ympäristömuuttujiin.
# Asenna tuki Pydantic-dataclassille
pip install openai pydantic
# Asenna python-dotenv ympäristömuuttujia varten
pip install openai python-dotenv
Lopuksi varmista, että tuonti toimii, ja tarkista asennettu versio. Tämä on ensimmäinen tieto, joka kannattaa antaa, jos avaat tukipyyntöä.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Yksi asiakas, kaikki API:t
SDK pyörii yhden asiakasoljektion ympärillä, joka paljastaa koko alustan alimoduulien kautta. Sinun ei tarvitse luoda mitään uutta siirtyäksesi tekstin generoinnista upotuksiin tai moderointiin.
from openai import OpenAI
client = OpenAI()
# Responses API (teksti, funktiokutsut, jäsennetty tuloste)
client.responses.create(...)
# Chat Completions API (vanhentunut)
client.chat.completions.create(...)
# Upotukset (Embeddings)
client.embeddings.create(...)
# Kuvat
client.images.generate(...)
# Ääni
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderointi
client.moderations.create(...)
Määritä asiakas kontekstisi mukaan
SDK:n oletusasetukset sopivat kokeiluun, mutta eivät web-sovelluksille. Oletusaikakatkaisu on kymmenen minuuttia: HTTP-API:ssa, jonka odotetaan vastaavan sekunneissa, tämä tarkoittaa, että jumittunut pyyntö sitoo työntekijän liian pitkäksi aikaa. Lyhennä aikakatkaisua ja kasvata automaattisten uudelleenyritysten määrää, jonka oletusarvo on kaksi.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 sekuntia (oletus: 10 minuuttia)
max_retries=3, # 3 yritystä virheen sattuessa (oletus: 2)
)
base_url-parametri ratkaisee toisen tarpeen: reitittää kutsut yrityksen välityspalvelimen kautta, joka lokittaa lähtevää liikennettä, tai palveluun, joka tarjoaa yhteensopivan API:n.
# Hyödyllinen yritysvälityspalvelimille tai yhteensopiville API:lle
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
Lopuksi, jos sovelluksesi luottaa asyncioon – kuten FastAPI, aiohttp ja muut vastaavat – käytä AsyncOpenAI:tä. Synkroninen asiakas estäisi tapahtumasilmukan generoinnin aikana, mikä kumoaisi asynkronisen koodin hyödyt.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Käyttö await-lausekkeen kanssa
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?
Rakenne projektillesi
Omaksu organisaatio, joka eristää asiakasmääritykset muusta koodistasi heti alusta alkaen. Tämä välttää tilanteen, jossa kymmeniä OpenAI()-kutsuja sirpaloituvat projektiisi, jokainen omilla asetuksillaan.
my-project/
├── .env # API-avain (ÄLÄ koskaan commitoi gitiin)
├── .gitignore # Sisältää .env-tiedoston
├── requirements.txt # Riippuvuudet
├── src/
│ ├── __init__.py
│ ├── client.py # OpenAI-asiakkaan määritys
│ └── main.py # Sisääntulopiste
└── tests/
└── test_api.py
src/client.py-tiedosto keskittää asiakastehtaan: sinä päivänä, kun muutat aikakatkaisua tai lisäät välityspalvelimen, sinun tarvitsee muokata vain yhtä kohtaa.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Palauttaa määritetyn OpenAI-asiakkaan."""
return OpenAI(
max_retries=3,
timeout=30.0
)
Ja requirements.txt lukitsee odotetut minimiversiot:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Kolme yleistä virhettä
ModuleNotFoundError virhe openai:lle viittaa lähes aina inaktiiviseen virtuaaliympäristöön tai siihen, että ympäristö on eri kuin se, johon asensit paketin. Etsi käytössä oleva tulkki komennolla which python Linuxissa ja macOS:ssä tai where python Windowsissa, ja asenna uudelleen komennolla pip install --upgrade openai. AuthenticationError viittaa ympäristömuuttujaan: tulosta os.environ.get("OPENAI_API_KEY", "NOT DEFINED") sulkeaksesi pois ongelmat – .env-tiedostoa ei ladata, jos load_dotenv()-funktiota ei ole kutsuttu ennen asiakkaan luomista. Lopuksi, tuntematonta parametria koskeva virhe viittaa yleensä siihen, että SDK on liian vanha käyttämällesi ominaisuudelle: pip install --upgrade openai ratkaisee tämän.
Keskeiset asiat
- Asenna SDK komennolla
pip install openaivirtuaaliympäristön sisällä OpenAI()-asiakas on sisäänkäynti kaikkiin API:hin- Käytä
AsyncOpenAI():tä asynkronisissa sovelluksissa - Määritä aikakatkaisu ja uudelleenyritykset tarpeidesi mukaan
- Rakenne projektisi
.env-tiedostolla ja keskitetyllä asiakkaalla