openai python
v1.55.1
OpenAI Python ライブラリを使用すると、Python 3.8 以降のアプリケーションから OpenAI REST API に簡単にアクセスできます。このライブラリには、すべてのリクエスト パラメータとレスポンス フィールドの型定義が含まれており、httpx を利用した同期クライアントと非同期クライアントの両方を提供します。
これは、Stainless を使用した OpenAPI 仕様から生成されます。
REST API ドキュメントは、platform.openai.com にあります。このライブラリの完全な API は、api.md にあります。
重要
SDK は、2023 年 11 月 6 日にリリースされた v1 で書き直されました。コードを自動的に更新するスクリプトが含まれている v1 移行ガイドを参照してください。
# install from PyPI
pip install openaiこのライブラリの完全な API は、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" ,
) api_keyキーワード引数を指定できますが、API キーがソース管理に保存されないように、python-dotenv を使用してOPENAI_API_KEY="My API Key"を.envファイルに追加することをお勧めします。
ホストされたイメージの場合:
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 } " },
},
],
}
],
)画像を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 } " },
},
],
}
],
)API と対話する場合、Run の開始やベクター ストアへのファイルの追加などの一部のアクションは非同期であり、完了までに時間がかかります。 SDK には、ターミナル状態に達するまでステータスをポーリングし、結果のオブジェクトを返すヘルパー関数が含まれています。 API メソッドの結果としてポーリングのメリットが得られるアクションが発生する場合、「_and_poll」で終わるメソッドの対応するバージョンが存在します。
たとえば、Run を作成し、最終状態に達するまでポーリングするには、次を実行します。
run = client . beta . threads . runs . create_and_poll (
thread_id = thread . id ,
assistant_id = assistant . id ,
)実行のライフサイクルの詳細については、「実行ライフサイクルのドキュメント」を参照してください。
ベクター ストアを作成して操作する場合、ポーリング ヘルパーを使用して操作のステータスを監視できます。便宜上、複数のファイルを同時にアップロードできる一括アップロード ヘルパーも提供しています。
sample_files = [ Path ( "sample-paper.pdf" ), ...]
batch = await client . vector_stores . file_batches . upload_and_poll (
store . id ,
files = sample_files ,
)SDK には、ストリームを処理し、受信イベントを処理するためのヘルパーも含まれています。
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 )ストリーミング ヘルパーの詳細については、専用ドキュメント helpers.md を参照してください。
OpenAI代わりにAsyncOpenAIをインポートし、各 API 呼び出しでawaitを使用するだけです。
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 ())それ以外の点では、同期クライアントと非同期クライアント間の機能は同一です。
サーバー サイド イベント (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 = "" )非同期クライアントはまったく同じインターフェイスを使用します。
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 ())重要
グローバル クライアントに依存するのではなく、クライアント インスタンスをインスタンス化することを強くお勧めします。
また、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 は、標準のクライアント インスタンスベースの API とまったく同じです。
これは、アプリケーション コードではなく、反復を高速化するために REPL またはノートブック内で使用することを目的としています。
次の理由から、アプリケーション コード内で常にクライアントを (例: client = OpenAI()で) インスタンス化することをお勧めします。
ネストされたリクエスト パラメーターは TypedDict です。応答は Pydantic モデルであり、次のようなヘルパー メソッドも提供します。
model.to_json()model.to_dict()入力されたリクエストとレスポンスは、エディタ内でオートコンプリートとドキュメントを提供します。バグを早期に発見するために VS Code で型エラーを確認したい場合は、 python.analysis.typeCheckingMode basicに設定します。
OpenAI API のリスト メソッドはページ分割されます。
このライブラリは、各リスト応答に自動ページ分割イテレータを提供するため、連続するページを手動でリクエストする必要はありません。
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 )または、非同期的に:
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 ())あるいは、 .has_next_page() 、 .next_page_info() 、または.get_next_page()メソッドを使用して、ページの操作をより詳細に制御することもできます。
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.または、返されたデータを直接操作することもできます。
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. ネストされたパラメーターは、 TypedDict使用して型指定された辞書です。次に例を示します。
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" },
)ファイルのアップロードに対応するリクエスト パラメータは、 bytes 、 PathLikeインスタンス、または(filename, contents, media type)のタプルとして渡すことができます。
from pathlib import Path
from openai import OpenAI
client = OpenAI ()
client . files . create (
file = Path ( "input.jsonl" ),
purpose = "fine-tune" ,
)非同期クライアントはまったく同じインターフェイスを使用します。 PathLikeインスタンスを渡すと、ファイルの内容が非同期で自動的に読み取られます。
ライブラリが API に接続できない場合 (ネットワーク接続の問題やタイムアウトなどにより)、 openai.APIConnectionErrorのサブクラスが発生します。
API が成功以外のステータス コード (つまり、4xx または 5xx 応答) を返すと、 status_codeとresponseプロパティを含むopenai.APIStatusErrorのサブクラスが発生します。
すべてのエラーは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 )エラーコードは次のとおりです。
| ステータスコード | エラーの種類 |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| >=500 | InternalServerError |
| 該当なし | APIConnectionError |
デバッグリクエストの詳細については、これらのドキュメントを参照してください。
SDK 内のすべてのオブジェクト応答には、 x-request-id応答ヘッダーから追加される_request_idプロパティが用意されているため、失敗した要求をすぐにログに記録し、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 _プレフィックスを使用する他のプロパティとは異なり、 _request_idプロパティはパブリックであることに注意してください。特に記載がない限り、他のすべての_ prefix プロパティ、メソッド、およびモジュールはprivateです。
特定のエラーはデフォルトで自動的に 2 回再試行され、短い指数バックオフが行われます。デフォルトでは、接続エラー (ネットワーク接続の問題などによる)、408 リクエスト タイムアウト、409 競合、429 レート制限、および >=500 の内部エラーはすべて再試行されます。
max_retriesオプションを使用して、再試行設定を構成または無効にすることができます。
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" ,
)デフォルトでは、リクエストは 10 分後にタイムアウトになります。これは、float またはhttpx.Timeoutオブジェクトを受け入れる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" ,
)タイムアウトになると、 APITimeoutErrorがスローされます。
タイムアウトしたリクエストはデフォルトで 2 回再試行されることに注意してください。
標準ライブラリのloggingモジュールを使用します。
ロギングを有効にするには、環境変数OPENAI_LOG infoに設定します。
$ export OPENAI_LOG=infoまたは、より詳細なログを記録するためにdebug 。
None nullまたは欠落を意味するかどうかを判断する方法API 応答では、フィールドが明示的にnullあるか、完全に欠落している場合があります。どちらの場合も、このライブラリではその値はNoneです。 .model_fields_setを使用して 2 つのケースを区別できます。
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}.' )「生」の Response オブジェクトには、接頭辞.with_raw_response.任意の HTTP メソッド呼び出しに、たとえば、
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 )これらのメソッドはLegacyAPIResponseオブジェクトを返します。次のメジャー バージョンでわずかに変更されるため、これはレガシー クラスです。
同期クライアントの場合、 contentとtextプロパティではなくメソッドになることを除いて、これはほとんど同じです。非同期クライアントでは、すべてのメソッドが非同期になります。
移行スクリプトが提供され、移行は通常はスムーズに行われるはずです。
.with_streaming_response上記のインターフェイスは、リクエストを行うと完全な応答本文を熱心に読み取りますが、これは必ずしも希望通りであるとは限りません。
応答本文をストリーミングするには、代わりに.with_streaming_responseを使用します。これにはコンテキスト マネージャーが必要で.read() 、 .text() 、 .json() 、 .iter_bytes() 、 .iter_text() 、 .iter_lines()または.parse() 。非同期クライアントでは、これらは非同期メソッドです。
そのため、 .with_streaming_responseメソッドは別のAPIResponseオブジェクトを返し、非同期クライアントは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 )応答が確実に閉じられるようにするには、コンテキスト マネージャーが必要です。
このライブラリは、文書化された API に簡単にアクセスできるように型付けされています。
文書化されていないエンドポイント、パラメータ、または応答プロパティにアクセスする必要がある場合でも、ライブラリを使用できます。
文書化されていないエンドポイントにリクエストを行うには、 client.get 、 client.post 、およびその他の http 動詞を使用してリクエストを行うことができます。このリクエストを行う際には、クライアントのオプション (再試行など) が尊重されます。
import httpx
response = client . post (
"/foo" ,
cast_to = httpx . Response ,
body = { "my_param" : True },
)
print ( response . headers . get ( "x-foo" ))追加のパラメータを明示的に送信したい場合は、 extra_query 、 extra_body 、およびextra_headersリクエスト オプションを使用して送信できます。
文書化されていない応答プロパティにアクセスするには、 response.unknown_propなどの追加フィールドにアクセスします。 Pydantic モデルのすべての追加フィールドを、 response.model_extraを使用した辞書として取得することもできます。
httpx クライアントを直接オーバーライドして、次のようなユースケースに合わせてカスタマイズできます。
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" ),
),
) with_options()を使用して、リクエストごとにクライアントをカスタマイズすることもできます。
client . with_options ( http_client = DefaultHttpxClient (...))デフォルトでは、クライアントがガベージ コレクションされるたびに、ライブラリは基礎となる HTTP 接続を閉じます。必要に応じて.close()メソッドを使用するか、終了時に閉じるコンテキスト マネージャーを使用してクライアントを手動で閉じることができます。
このライブラリを Azure OpenAI で使用するには、 OpenAIクラスの代わりにAzureOpenAIクラスを使用します。
重要
Azure API の形状はコア API の形状とは異なります。つまり、応答/パラメーターの静的型が常に正しいとは限りません。
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 ())基本OpenAIクライアントで提供されるオプションに加えて、次のオプションが提供されます。
azure_endpoint (またはAZURE_OPENAI_ENDPOINT環境変数)azure_deploymentapi_version (またはOPENAI_API_VERSION環境変数)azure_ad_token (またはAZURE_OPENAI_AD_TOKEN環境変数)azure_ad_token_providerMicrosoft Entra ID (旧称 Azure Active Directory) でクライアントを使用する例は、ここにあります。
このパッケージは通常 SemVer の規則に従いますが、下位互換性のない変更がマイナー バージョンとしてリリースされる場合があります。
私たちは下位互換性を真剣に受け止めており、スムーズなアップグレード エクスペリエンスを確実に提供できるよう懸命に取り組んでいます。
皆様からのフィードバックをお待ちしております。質問、バグ、提案がある問題を開いてください。
最新バージョンにアップグレードしても、期待していた新機能が表示されない場合は、Python 環境がまだ古いバージョンを使用している可能性があります。
実行時に使用されているバージョンは、次の方法で確認できます。
import openai
print ( openai . __version__ )Python 3.8 以降。
貢献ドキュメントを参照してください。
