Assistants API (プレビュー) リファレンス

  • [アーティクル]

Note

  • ファイル検索では、アシスタントあたり最大 10,000 個のファイルを取り込むことができます。これは以前の 500 倍以上の量です。 これは高速で、マルチスレッド検索を通して並列クエリをサポートしており、強化された再ランク付けとクエリの書き換えを特徴としています。
    • ベクトル ストアは、API 内の新しいオブジェクトです。 ファイルがベクトル ストアに追加されると、自動的にそのファイルの解析、チャンク、埋め込みが行われ、検索の準備が整います。 ベクトル ストアは、複数のアシスタントとスレッドにわたって使用できるため、ファイル管理と課金が単純化されます。
  • 特定の実行において特定のツール (ファイル検索、コード インタープリター、関数など) の使用を強制するために使用できる tool_choice パラメーターのサポートが追加されました。

この記事では、新しい Assistants API (プレビュー) に関する Python と REST のリファレンス ドキュメントを提供します。 さらに詳しい手順については、概要ガイドに関する記事をご覧ください。

アシスタントを作成する

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

モデルと指示を使ってアシスタントを作成します。

要求本文

名前 タイプ Required 説明
モデル string 必須 使用するモデルのモデル デプロイ名。
name 文字列または null 値 省略可能 アシスタントの名前。 最大長は 256 文字です。
description 文字列または null 値 省略可能 アシスタントの説明。 最大長は 512 文字です。
instructions 文字列または null 値 省略可能 アシスタントが使うシステムの指示。 最大長は 256,000 文字です。
tools 配列 省略可能 既定値は [] です。 アシスタントで有効になっているツールのリスト。 アシスタントごとに最大 128 個のツールを使用できます。 現在、tools で指定できる種類は code_interpreter または function です。 function の説明には、最大 1,024 文字を使用できます。
metadata map 省略可能 オブジェクトにアタッチできる 16 個のキーと値のペアのセット。 これは、オブジェクトに関する追加情報を構造化された形式で格納する場合に役立ちます。 キーの最大長は 64 文字、値の最大長は 512 文字です。
温度 数値または null 省略可能 デフォルト値は 1 です。 使うサンプリング温度 (0 から 2) を決定します。 0.8 のような大きい値にすると、出力はよりランダムになり、0.2 のような小さい値にすると、出力はより集中的および決定論的になります。
top_p 数値または null 省略可能 デフォルト値は 1 です。 温度によるサンプリングに代わる核サンプリングと呼ばれるもので、モデルは top_p の確率質量を持つトークンの結果を考慮します。 したがって、0.1 は、上位 10% の確率質量を含むトークンのみが考慮されることを意味します。 一般的に、これと temperature の両方ではなく、いずれかを変更することをお勧めします。
応答形式 文字列またはオブジェクト 省略可能 モデルから出力する必要がある形式を指定します。 GPT-4 Turbo と gpt-3.5-turbo-1106 以降のすべての GPT-3.5 Turbo モデルと互換性があります。 このパラメーターを { "type": "json_object" } に設定すると、JSON モードが有効になります。これにより、モデルが生成するメッセージが有効な JSON であることが保証されます。 重要な点として、JSON モードを使う場合、システムまたはユーザー メッセージを使って、ユーザー自身が JSON を生成することをモデルに指示する必要もあります。 この指示がないと、トークンの上限に達するまで、モデルはいつまでも空白のストリームを生成する可能性があります。その結果、実行時間が長く、一見 "スタック" しているように見える要求が発生します。 さらに、finish_reason="length" を使うと、メッセージの内容が部分的に切り取られる可能性があります。これは、世代が max_tokens を超えたか、会話がコンテキストの最大長を超えたことを示します。
tool_resources オブジェクト 省略可能 アシスタントのツールによって使用されるリソースのセット。 リソースは、ツールの種類に固有です。 たとえば、code_interpreter ツールにはファイル ID の一覧が必要ですが、file_search ツールにはベクター ストア ID の一覧が必要です。

返品

アシスタント オブジェクト。

アシスタント作成要求の例

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant = client.beta.assistants.create(
  instructions="You are an AI assistant that can write code to help answer math questions",
  model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name. 
  tools=[{"type": "code_interpreter"}]
)

アシスタントのリストを取得する

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

すべてのアシスタントのリストを返します。

クエリ パラメーター

パラメーター タイプ Required 説明
limit integer 省略可能 返されるオブジェクトの数の制限。 制限の範囲は 1 から 100 で、既定値は 20 です。
order string 省略可能 - 既定値は desc オブジェクトの created_at タイムスタンプによる並べ替え順序。 昇順の場合は asc、降順の場合は desc。
after string 省略可能 改ページで使うカーソル。 after は、リスト内での場所を定義するオブジェクト ID です。 たとえば、リスト取得要求を行い、obj_foo で終わる 100 個のオブジェクトを受け取った場合、後続の呼び出しに after=obj_foo を含めて、リストの次のページをフェッチできます。
before string 省略可能 改ページで使うカーソル。 before は、リスト内での場所を定義するオブジェクト ID です。 たとえば、リスト取得要求を行い、obj_foo で終わる 100 個のオブジェクトを受け取った場合、後続の呼び出しに before=obj_foo を含めて、リストの前のページをフェッチできます。

返品

アシスタント オブジェクトのリスト

アシスタント リスト取得の例

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

アシスタントを取得する

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

アシスタントを取得します。

パス パラメーター

パラメーター タイプ Required Description
assistant_id string 必須 取得するアシスタントの ID。

返品

指定された ID と一致するアシスタント オブジェクト。

アシスタント取得の例

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

アシスタントを変更する

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

アシスタントを変更します。

パス パラメーター

パラメーター タイプ Required 説明
assistant_id string 必須 ファイルが属しているアシスタントの ID。

要求本文

パラメーター タイプ Required 説明
model 省略可能 使用するモデルのモデル デプロイ名。
name 文字列または null 値 省略可能 アシスタントの名前。 最大長は 256 文字です。
description 文字列または null 値 省略可能 アシスタントの説明。 最大長は 512 文字です。
instructions 文字列または null 値 省略可能 アシスタントが使うシステムの指示。 最大長は 32,768 文字です。
tools 配列 省略可能 既定値は [] です。 アシスタントで有効になっているツールのリスト。 アシスタントごとに最大 128 個のツールを使用できます。 tools で指定できる種類は code_interpreter または function です。 function の説明には、最大 1,024 文字を使用できます。
metadata map 省略可能 オブジェクトにアタッチできる 16 個のキーと値のペアのセット。 これは、オブジェクトに関する追加情報を構造化された形式で格納する場合に役立ちます。 キーの最大長は 64 文字、値の最大長は 512 文字です。
temperature 数値または null 省略可能 デフォルト値は 1 です。 使うサンプリング温度 (0 から 2) を決定します。 0.8 のような大きい値にすると、出力はよりランダムになり、0.2 のような小さい値にすると、出力はより集中的および決定論的になります。
top_p 数値または null 省略可能 デフォルト値は 1 です。 温度によるサンプリングに代わる核サンプリングと呼ばれるもので、モデルは top_p の確率質量を持つトークンの結果を考慮します。 したがって、0.1 は、上位 10% の確率質量を含むトークンのみが考慮されることを意味します。 一般的に、これと temperature の両方ではなく、いずれかを変更することをお勧めします。
response_format 文字列またはオブジェクト 省略可能 モデルから出力する必要がある形式を指定します。 GPT-4 Turbo と gpt-3.5-turbo-1106 以降のすべての GPT-3.5 Turbo モデルと互換性があります。 このパラメーターを { "type": "json_object" } に設定すると、JSON モードが有効になります。これにより、モデルが生成するメッセージが有効な JSON であることが保証されます。 重要な点として、JSON モードを使う場合、システムまたはユーザー メッセージを使って、ユーザー自身が JSON を生成することをモデルに指示する必要もあります。 この指示がないと、トークンの上限に達するまで、モデルはいつまでも空白のストリームを生成する可能性があります。その結果、実行時間が長く、一見 "スタック" しているように見える要求が発生します。 さらに、finish_reason="length" を使うと、メッセージの内容が部分的に切り取られる可能性があります。これは、世代が max_tokens を超えたか、会話がコンテキストの最大長を超えたことを示します。
tool_resources オブジェクト 省略可能 アシスタントのツールによって使用されるリソースのセット。 リソースは、ツールの種類に固有です。 たとえば、code_interpreter ツールにはファイル ID の一覧が必要ですが、file_search ツールにはベクター ストア ID の一覧が必要です。

返品

変更されたアシスタント オブジェクト。

アシスタント変更の例

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_updated_assistant = client.beta.assistants.update(
  "asst_abc123",
  instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
  name="HR Helper",
  tools=[{"type": "code-interpreter"}],
  model="gpt-4", #model = model deployment name
)

print(my_updated_assistant)

アシスタントを削除する

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

アシスタントを削除します。

パス パラメーター

パラメーター タイプ Required Description
assistant_id string 必須 ファイルが属しているアシスタントの ID。

返品

削除の状態。

アシスタント削除の例

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

ファイル アップロード API リファレンス

アシスタントは、微調整と同じ API をファイル アップロードに使用します。 ファイルをアップロードするときは、purpose パラメーターに適切な値を指定する必要があります。

アシスタント オブジェクト

フィールド タイプ 説明
id string API エンドポイントで参照できる識別子。
object string オブジェクトの種類。これは常に assistant です。
created_at integer アシスタントが作成されたときの Unix タイムスタンプ (秒単位)。
name 文字列または null 値 アシスタントの名前。 最大長は 256 文字です。
description 文字列または null 値 アシスタントの説明。 最大長は 512 文字です。
model string 使用するモデル デプロイ名の名前。
instructions 文字列または null 値 アシスタントが使うシステムの指示。 最大長は 32,768 文字です。
tools 配列 アシスタントで有効になっているツールのリスト。 アシスタントごとに最大 128 個のツールを使用できます。 tools で指定できる種類は code_interpreter または function です。 function の説明には、最大 1,024 文字を使用できます。
metadata map オブジェクトにアタッチできる 16 個のキーと値のペアのセット。 これは、オブジェクトに関する追加情報を構造化された形式で格納する場合に役立ちます。 キーの最大長は 64 文字、値の最大長は 512 文字です。
temperature 数値または null デフォルト値は 1 です。 使うサンプリング温度 (0 から 2) を決定します。 0.8 のような大きい値にすると、出力はよりランダムになり、0.2 のような小さい値にすると、出力はより集中的および決定論的になります。
top_p 数値または null デフォルト値は 1 です。 温度によるサンプリングに代わる核サンプリングと呼ばれるもので、モデルは top_p の確率質量を持つトークンの結果を考慮します。 したがって、0.1 は、上位 10% の確率質量を含むトークンのみが考慮されることを意味します。 一般的に、これと temperature の両方ではなく、いずれかを変更することをお勧めします。
response_format 文字列またはオブジェクト モデルから出力する必要がある形式を指定します。 GPT-4 Turbo と gpt-3.5-turbo-1106 以降のすべての GPT-3.5 Turbo モデルと互換性があります。 このパラメーターを { "type": "json_object" } に設定すると、JSON モードが有効になります。これにより、モデルが生成するメッセージが有効な JSON であることが保証されます。 重要な点として、JSON モードを使う場合、システムまたはユーザー メッセージを使って、ユーザー自身が JSON を生成することをモデルに指示する必要もあります。 この指示がないと、トークンの上限に達するまで、モデルはいつまでも空白のストリームを生成する可能性があります。その結果、実行時間が長く、一見 "スタック" しているように見える要求が発生します。 さらに、finish_reason="length" を使うと、メッセージの内容が部分的に切り取られる可能性があります。これは、世代が max_tokens を超えたか、会話がコンテキストの最大長を超えたことを示します。
tool_resources オブジェクト アシスタントのツールによって使用されるリソースのセット。 リソースは、ツールの種類に固有です。 たとえば、code_interpreter ツールにはファイル ID の一覧が必要ですが、file_search ツールにはベクター ストア ID の一覧が必要です。