openai python
v1.55.1
Pustaka OpenAI Python menyediakan akses mudah ke OpenAI REST API dari aplikasi Python 3.8+ apa pun. Pustaka ini mencakup definisi tipe untuk semua parameter permintaan dan bidang respons, dan menawarkan klien sinkron dan asinkron yang didukung oleh httpx.
Itu dihasilkan dari spesifikasi OpenAPI kami dengan Stainless.
Dokumentasi REST API dapat ditemukan di platform.openai.com. API lengkap perpustakaan ini dapat ditemukan di api.md.
Penting
SDK ditulis ulang dalam v1, yang dirilis pada 6 November 2023. Lihat panduan migrasi v1, yang menyertakan skrip untuk memperbarui kode Anda secara otomatis.
# install from PyPI
pip install openaiAPI lengkap perpustakaan ini dapat ditemukan di api.md.
import os
from openai import OpenAI
client = OpenAI (
api_key = os . environ . get ( "OPENAI_API_KEY" ), # This is the default and can be omitted
)
chat_completion = client . chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "Say this is a test" ,
}
],
model = "gpt-4o" ,
) Meskipun Anda dapat memberikan argumen kata kunci api_key , sebaiknya gunakan python-dotenv untuk menambahkan OPENAI_API_KEY="My API Key" ke file .env Anda sehingga Kunci API Anda tidak disimpan di kontrol sumber.
Dengan gambar yang dihosting:
response = client . chat . completions . create (
model = "gpt-4o-mini" ,
messages = [
{
"role" : "user" ,
"content" : [
{ "type" : "text" , "text" : prompt },
{
"type" : "image_url" ,
"image_url" : { "url" : f" { img_url } " },
},
],
}
],
)Dengan gambar sebagai string yang dikodekan base64:
response = client . chat . completions . create (
model = "gpt-4o-mini" ,
messages = [
{
"role" : "user" ,
"content" : [
{ "type" : "text" , "text" : prompt },
{
"type" : "image_url" ,
"image_url" : { "url" : f"data: { img_type } ;base64, { img_b64_str } " },
},
],
}
],
)Saat berinteraksi dengan API, beberapa tindakan seperti memulai Jalankan dan menambahkan file ke penyimpanan vektor bersifat asinkron dan memerlukan waktu untuk diselesaikan. SDK menyertakan fungsi pembantu yang akan melakukan polling status hingga mencapai status terminal dan kemudian mengembalikan objek yang dihasilkan. Jika metode API menghasilkan tindakan yang dapat memanfaatkan polling, maka akan ada versi metode yang sesuai yang diakhiri dengan '_and_poll'.
Misalnya untuk membuat Run dan polling hingga mencapai status terminal, Anda dapat menjalankan:
run = client . beta . threads . runs . create_and_poll (
thread_id = thread . id ,
assistant_id = assistant . id ,
)Informasi selengkapnya tentang siklus hidup Run dapat ditemukan di Dokumentasi Run Lifecycle
Saat membuat dan berinteraksi dengan penyimpanan vektor, Anda dapat menggunakan bantuan polling untuk memantau status operasi. Untuk kenyamanan, kami juga menyediakan bantuan unggahan massal yang memungkinkan Anda mengunggah beberapa file sekaligus.
sample_files = [ Path ( "sample-paper.pdf" ), ...]
batch = await client . vector_stores . file_batches . upload_and_poll (
store . id ,
files = sample_files ,
)SDK juga menyertakan pembantu untuk memproses aliran dan menangani kejadian masuk.
with client . beta . threads . runs . stream (
thread_id = thread . id ,
assistant_id = assistant . id ,
instructions = "Please address the user as Jane Doe. The user has a premium account." ,
) as stream :
for event in stream :
# Print the text from text delta events
if event . type == "thread.message.delta" and event . data . delta . content :
print ( event . data . delta . content [ 0 ]. text )Informasi lebih lanjut tentang streaming helper dapat ditemukan di dokumentasi khusus: helpers.md
Cukup impor AsyncOpenAI alih-alih OpenAI dan gunakan await pada setiap panggilan API:
import os
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI (
api_key = os . environ . get ( "OPENAI_API_KEY" ), # This is the default and can be omitted
)
async def main () -> None :
chat_completion = await client . chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "Say this is a test" ,
}
],
model = "gpt-4o" ,
)
asyncio . run ( main ())Fungsionalitas antara klien sinkron dan asinkron identik.
Kami memberikan dukungan untuk respons streaming menggunakan Server Side Events (SSE).
from openai import OpenAI
client = OpenAI ()
stream = client . chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "Say this is a test" ,
}
],
model = "gpt-4o" ,
stream = True ,
)
for chunk in stream :
print ( chunk . choices [ 0 ]. delta . content or "" , end = "" )Klien async menggunakan antarmuka yang sama persis.
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI ()
async def main ():
stream = await client . chat . completions . create (
model = "gpt-4" ,
messages = [{ "role" : "user" , "content" : "Say this is a test" }],
stream = True ,
)
async for chunk in stream :
print ( chunk . choices [ 0 ]. delta . content or "" , end = "" )
asyncio . run ( main ())Penting
Kami sangat menyarankan untuk membuat instance instance klien daripada mengandalkan klien global.
Kami juga mengekspos contoh klien global yang dapat diakses dengan cara yang mirip dengan versi sebelum v1.
import openai
# optional; defaults to `os.environ['OPENAI_API_KEY']`
openai . api_key = '...'
# all client options can be configured just like the `OpenAI` instantiation counterpart
openai . base_url = "https://..."
openai . default_headers = { "x-foo" : "true" }
completion = openai . chat . completions . create (
model = "gpt-4o" ,
messages = [
{
"role" : "user" ,
"content" : "How do I output all files in a directory using Python?" ,
},
],
)
print ( completion . choices [ 0 ]. message . content )API ini sama persis dengan API berbasis instans klien standar.
Ini dimaksudkan untuk digunakan dalam REPL atau notebook untuk iterasi yang lebih cepat, bukan dalam kode aplikasi.
Kami menyarankan Anda selalu membuat instance klien (misalnya, dengan client = OpenAI() ) dalam kode aplikasi karena:
Parameter permintaan bersarang adalah TypedDicts. Respons adalah model Pydantic yang juga menyediakan metode pembantu untuk hal-hal seperti:
model.to_json()model.to_dict() Permintaan dan tanggapan yang diketik menyediakan pelengkapan otomatis dan dokumentasi dalam editor Anda. Jika Anda ingin melihat kesalahan ketik di VS Code untuk membantu menangkap bug sebelumnya, setel python.analysis.typeCheckingMode ke basic .
Metode daftar di OpenAI API diberi nomor halaman.
Pustaka ini menyediakan iterator penomoran halaman otomatis pada setiap respons daftar, sehingga Anda tidak perlu meminta halaman berturut-turut secara manual:
from openai import OpenAI
client = OpenAI ()
all_jobs = []
# Automatically fetches more pages as needed.
for job in client . fine_tuning . jobs . list (
limit = 20 ,
):
# Do something with job here
all_jobs . append ( job )
print ( all_jobs )Atau, secara asinkron:
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI ()
async def main () -> None :
all_jobs = []
# Iterate through items across all pages, issuing requests as needed.
async for job in client . fine_tuning . jobs . list (
limit = 20 ,
):
all_jobs . append ( job )
print ( all_jobs )
asyncio . run ( main ()) Alternatifnya, Anda dapat menggunakan metode .has_next_page() , .next_page_info() , atau .get_next_page() untuk kontrol yang lebih terperinci saat bekerja dengan laman:
first_page = await client . fine_tuning . jobs . list (
limit = 20 ,
)
if first_page . has_next_page ():
print ( f"will fetch next page using these details: { first_page . next_page_info () } " )
next_page = await first_page . get_next_page ()
print ( f"number of items we just fetched: { len ( next_page . data ) } " )
# Remove `await` for non-async usage.Atau langsung bekerja dengan data yang dikembalikan:
first_page = await client . fine_tuning . jobs . list (
limit = 20 ,
)
print ( f"next page cursor: { first_page . after } " ) # => "next page cursor: ..."
for job in first_page . data :
print ( job . id )
# Remove `await` for non-async usage. Parameter bersarang adalah kamus yang diketik menggunakan TypedDict , misalnya:
from openai import OpenAI
client = OpenAI ()
completion = client . chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "Can you generate an example json object describing a fruit?" ,
}
],
model = "gpt-4o" ,
response_format = { "type" : "json_object" },
) Parameter permintaan yang sesuai dengan unggahan file dapat diteruskan sebagai bytes , instance PathLike atau tupel (filename, contents, media type) .
from pathlib import Path
from openai import OpenAI
client = OpenAI ()
client . files . create (
file = Path ( "input.jsonl" ),
purpose = "fine-tune" ,
) Klien async menggunakan antarmuka yang sama persis. Jika Anda meneruskan instance PathLike , konten file akan dibaca secara otomatis secara asinkron.
Ketika perpustakaan tidak dapat terhubung ke API (misalnya, karena masalah koneksi jaringan atau waktu habis), subkelas openai.APIConnectionError dimunculkan.
Ketika API mengembalikan kode status yang tidak berhasil (yaitu, respons 4xx atau 5xx), subkelas openai.APIStatusError dimunculkan, berisi status_code dan properti response .
Semua kesalahan diwarisi dari openai.APIError .
import openai
from openai import OpenAI
client = OpenAI ()
try :
client . fine_tuning . jobs . create (
model = "gpt-4o" ,
training_file = "file-abc123" ,
)
except openai . APIConnectionError as e :
print ( "The server could not be reached" )
print ( e . __cause__ ) # an underlying Exception, likely raised within httpx.
except openai . RateLimitError as e :
print ( "A 429 status code was received; we should back off a bit." )
except openai . APIStatusError as e :
print ( "Another non-200-range status code was received" )
print ( e . status_code )
print ( e . response )Kode kesalahan adalah sebagai berikut:
| Kode Status | Jenis Kesalahan |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| >=500 | InternalServerError |
| T/A | APIConnectionError |
Untuk informasi selengkapnya tentang permintaan debug, lihat dokumen ini
Semua respons objek di SDK menyediakan properti _request_id yang ditambahkan dari header respons x-request-id sehingga Anda dapat dengan cepat mencatat permintaan yang gagal dan melaporkannya kembali ke OpenAI.
completion = await client . chat . completions . create (
messages = [{ "role" : "user" , "content" : "Say this is a test" }], model = "gpt-4"
)
print ( completion . _request_id ) # req_123 Perhatikan bahwa tidak seperti properti lain yang menggunakan awalan _ , properti _request_id bersifat publik. Kecuali jika didokumentasikan sebaliknya, semua properti, metode, dan modul awalan _ lainnya bersifat private .
Kesalahan tertentu secara otomatis dicoba ulang 2 kali secara default, dengan kemunduran eksponensial singkat. Kesalahan koneksi (misalnya, karena masalah konektivitas jaringan), 408 Batas Waktu Permintaan, 409 Konflik, 429 Batas Kecepatan, dan >=500 Kesalahan internal semuanya dicoba ulang secara default.
Anda dapat menggunakan opsi max_retries untuk mengonfigurasi atau menonaktifkan pengaturan coba lagi:
from openai import OpenAI
# Configure the default for all requests:
client = OpenAI (
# default is 2
max_retries = 0 ,
)
# Or, configure per-request:
client . with_options ( max_retries = 5 ). chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "How can I get the name of the current day in JavaScript?" ,
}
],
model = "gpt-4o" ,
) Secara default, waktu tunggu permintaan habis setelah 10 menit. Anda dapat mengonfigurasinya dengan opsi timeout , yang menerima objek float atau httpx.Timeout :
from openai import OpenAI
# Configure the default for all requests:
client = OpenAI (
# 20 seconds (default is 10 minutes)
timeout = 20.0 ,
)
# More granular control:
client = OpenAI (
timeout = httpx . Timeout ( 60.0 , read = 5.0 , write = 10.0 , connect = 2.0 ),
)
# Override per-request:
client . with_options ( timeout = 5.0 ). chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "How can I list all files in a directory using Python?" ,
}
],
model = "gpt-4o" ,
) Saat batas waktu habis, APITimeoutError dilempar.
Perhatikan bahwa permintaan waktu tunggu tersebut dicoba ulang dua kali secara default.
Kami menggunakan modul logging perpustakaan standar.
Anda dapat mengaktifkan pembuatan log dengan menyetel variabel lingkungan OPENAI_LOG ke info .
$ export OPENAI_LOG=info Atau untuk debug agar logging lebih panjang.
None berarti null atau hilang Dalam respons API, suatu bidang mungkin secara eksplisit null , atau hilang seluruhnya; dalam kedua kasus tersebut, nilainya adalah None di perpustakaan ini. Anda dapat membedakan kedua kasus tersebut dengan .model_fields_set :
if response . my_field is None :
if 'my_field' not in response . model_fields_set :
print ( 'Got json like {}, without a "my_field" key present at all.' )
else :
print ( 'Got json like {"my_field": null}.' ) Objek Respon "mentah" dapat diakses dengan mengawali .with_raw_response. ke panggilan metode HTTP apa pun, misalnya,
from openai import OpenAI
client = OpenAI ()
response = client . chat . completions . with_raw_response . create (
messages = [{
"role" : "user" ,
"content" : "Say this is a test" ,
}],
model = "gpt-4o" ,
)
print ( response . headers . get ( 'X-My-Header' ))
completion = response . parse () # get the object that `chat.completions.create()` would have returned
print ( completion ) Metode ini mengembalikan objek LegacyAPIResponse . Ini adalah kelas lama karena kami mengubahnya sedikit di versi utama berikutnya.
Untuk klien sinkronisasi, sebagian besar hal ini akan sama dengan pengecualian content & text akan menjadi metode, bukan properti. Di klien async, semua metode akan menjadi async.
Skrip migrasi akan disediakan & migrasi secara umum akan lancar.
.with_streaming_responseAntarmuka di atas dengan bersemangat membaca seluruh isi respons saat Anda membuat permintaan, yang mungkin tidak selalu sesuai dengan keinginan Anda.
Untuk melakukan streaming isi respons, gunakan .with_streaming_response sebagai gantinya, yang memerlukan pengelola konteks dan hanya membaca isi respons setelah Anda memanggil .read() , .text() , .json() , .iter_bytes() , .iter_text() , .iter_lines() atau .parse() . Di klien async, ini adalah metode async.
Dengan demikian, metode .with_streaming_response mengembalikan objek APIResponse yang berbeda, dan klien async mengembalikan objek AsyncAPIResponse .
with client . chat . completions . with_streaming_response . create (
messages = [
{
"role" : "user" ,
"content" : "Say this is a test" ,
}
],
model = "gpt-4o" ,
) as response :
print ( response . headers . get ( "X-My-Header" ))
for line in response . iter_lines ():
print ( line )Manajer konteks diperlukan agar respons dapat ditutup dengan andal.
Perpustakaan ini diketik untuk akses mudah ke API yang didokumentasikan.
Jika Anda perlu mengakses titik akhir, parameter, atau properti respons yang tidak terdokumentasi, pustaka masih dapat digunakan.
Untuk membuat permintaan ke titik akhir yang tidak berdokumen, Anda dapat membuat permintaan menggunakan client.get , client.post , dan kata kerja http lainnya. Opsi pada klien akan dihormati (seperti percobaan ulang) akan dihormati ketika membuat permintaan ini.
import httpx
response = client . post (
"/foo" ,
cast_to = httpx . Response ,
body = { "my_param" : True },
)
print ( response . headers . get ( "x-foo" )) Jika Anda ingin mengirim param tambahan secara eksplisit, Anda dapat melakukannya dengan opsi permintaan extra_query , extra_body , dan extra_headers .
Untuk mengakses properti respons yang tidak terdokumentasi, Anda dapat mengakses kolom tambahan seperti response.unknown_prop . Anda juga bisa mendapatkan semua bidang tambahan pada model Pydantic sebagai dict dengan response.model_extra .
Anda dapat langsung mengganti klien httpx untuk menyesuaikannya dengan kasus penggunaan Anda, termasuk:
from openai import OpenAI , DefaultHttpxClient
client = OpenAI (
# Or use the `OPENAI_BASE_URL` env var
base_url = "http://my.test.server.example.com:8083/v1" ,
http_client = DefaultHttpxClient (
proxies = "http://my.test.proxy.example.com" ,
transport = httpx . HTTPTransport ( local_address = "0.0.0.0" ),
),
) Anda juga dapat menyesuaikan klien berdasarkan permintaan dengan menggunakan with_options() :
client . with_options ( http_client = DefaultHttpxClient (...)) Secara default, perpustakaan menutup koneksi HTTP yang mendasarinya setiap kali klien mengumpulkan sampah. Anda dapat menutup klien secara manual menggunakan metode .close() jika diinginkan, atau dengan pengelola konteks yang menutup saat keluar.
Untuk menggunakan perpustakaan ini dengan Azure OpenAI, gunakan kelas AzureOpenAI bukan kelas OpenAI .
Penting
Bentuk Azure API berbeda dari bentuk API inti yang berarti tipe statis untuk respons/param tidak selalu benar.
from openai import AzureOpenAI
# gets the API Key from environment variable AZURE_OPENAI_API_KEY
client = AzureOpenAI (
# https://learn.microsoft.com/azure/ai-services/openai/reference#rest-api-versioning
api_version = "2023-07-01-preview" ,
# https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource?pivots=web-portal#create-a-resource
azure_endpoint = "https://example-endpoint.openai.azure.com" ,
)
completion = client . chat . completions . create (
model = "deployment-name" , # e.g. gpt-35-instant
messages = [
{
"role" : "user" ,
"content" : "How do I output all files in a directory using Python?" ,
},
],
)
print ( completion . to_json ()) Selain opsi yang disediakan di klien OpenAI dasar, opsi berikut juga disediakan:
azure_endpoint (atau variabel lingkungan AZURE_OPENAI_ENDPOINT )azure_deploymentapi_version (atau variabel lingkungan OPENAI_API_VERSION )azure_ad_token (atau variabel lingkungan AZURE_OPENAI_AD_TOKEN )azure_ad_token_providerContoh penggunaan klien dengan Microsoft Entra ID (sebelumnya dikenal sebagai Azure Active Directory) dapat ditemukan di sini.
Paket ini umumnya mengikuti konvensi SemVer, meskipun perubahan tertentu yang tidak kompatibel mungkin dirilis sebagai versi minor:
Kami menganggap serius kompatibilitas ke belakang dan bekerja keras untuk memastikan Anda dapat mengandalkan pengalaman peningkatan yang lancar.
Kami menantikan tanggapan Anda; silakan buka masalah dengan pertanyaan, bug, atau saran.
Jika Anda telah meningkatkan ke versi terbaru tetapi tidak melihat fitur baru apa pun yang Anda harapkan, kemungkinan besar lingkungan python Anda masih menggunakan versi yang lebih lama.
Anda dapat menentukan versi yang digunakan saat runtime dengan:
import openai
print ( openai . __version__ )Python 3.8 atau lebih tinggi.
Lihat dokumentasi kontribusi.
