Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Asenna Python SDK

Oppitunti 4 / 22 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Asenna Python SDK
  2. Edellytykset ja asennus
  3. Yksi asiakas, kaikki API:t
  4. Määritä asiakas kontekstisi mukaan
  5. Rakenne projektillesi
  6. Kolme yleistä virhettä
  7. Keskeiset asiat

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 openai virtuaaliympä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