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

[アーティクル]
06/13/2024

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

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

要求本文

名前	タイプ	必須	説明
モデル	string	必須	使用するモデルのモデルデプロイ名。
name	文字列または null 値	省略可能	アシスタントの名前。最大長は 256 文字です。
description	文字列または null 値	省略可能	アシスタントの説明。最大長は 512 文字です。
instructions	文字列または null 値	省略可能	アシスタントが使うシステムの指示。最大長は 256,000 文字です。
tools	配列	省略可能	既定値は [] です。アシスタントで有効になっているツールのリスト。アシスタントごとに最大 128 個のツールを使用できます。現在、tools で指定できる種類は `code_interpreter` または `function` です。 `function` の説明には、最大 1,024 文字を使用できます。
file_ids	配列	省略可能	既定値は [] です。このアシスタントにアタッチされているファイル ID のリスト。アシスタントには最大 20 個のファイルをアタッチできます。ファイルは、作成日の昇順で並べ替えられます。
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` を超えたか、会話がコンテキストの最大長を超えたことを示します。

返品

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

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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"}]
)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-1106-preview"
  }'

アシスタントファイルを作成する

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

File を assistant にアタッチして、アシスタントファイルを作成します。

パスパラメーター

パラメーター	タイプ	必須	Description
`assistant_id`	string	必須	ファイルをアタッチする必要があるアシスタントの ID。

要求本文

名前	タイプ	必須	説明
file_id	string	必須	アシスタントが使う必要のあるファイル ID (purpose="assistants")。ファイルにアクセスできる code_interpreter などのツールに便利です。

返品

アシスタントファイルオブジェクト。

アシスタントファイル作成要求の例

Python 1.x
REST

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

assistant_file = client.beta.assistants.files.create(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
       "file_id": "assistant-abc123"
     }'

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

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

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

クエリパラメーター

パラメーター	タイプ	必須	説明
`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 を含めて、リストの前のページをフェッチできます。

返品

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

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

Python 1.x
REST

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

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

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

アシスタントファイルのリストを取得する

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

アシスタントファイルのリストを返します。

パスパラメーター

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

クエリパラメーター

パラメーター	タイプ	必須	説明
`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 を含めて、リストの前のページをフェッチできます。

返品

アシスタントファイルオブジェクトのリスト

アシスタントファイルリスト取得の例

Python 1.x
REST

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

assistant_files = client.beta.assistants.files.list(
  assistant_id="asst_abc123"
)
print(assistant_files)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

アシスタントを取得する

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

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

パスパラメーター

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

返品

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

アシスタント取得の例

Python 1.x
REST

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

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

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

アシスタントファイルを取得する

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

アシスタントファイルを取得します。

パスパラメーター

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

返品

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

アシスタントファイル取得の例

Python 1.x
REST

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

assistant_file = client.beta.assistants.files.retrieve(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files/{file-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

アシスタントを変更する

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

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

パスパラメーター

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

要求本文

パラメーター	タイプ	必須	説明
`model`		省略可能	使用するモデルのモデルデプロイ名。
`name`	文字列または null 値	省略可能	アシスタントの名前。最大長は 256 文字です。
`description`	文字列または null 値	省略可能	アシスタントの説明。最大長は 512 文字です。
`instructions`	文字列または null 値	省略可能	アシスタントが使うシステムの指示。最大長は 32,768 文字です。
`tools`	配列	省略可能	既定値は [] です。アシスタントで有効になっているツールのリスト。アシスタントごとに最大 128 個のツールを使用できます。 tools で指定できる種類は code_interpreter または function です。 `function` の説明には、最大 1,024 文字を使用できます。
`file_ids`	配列	省略可能	既定値は [] です。このアシスタントにアタッチされているファイル ID のリスト。アシスタントには最大 20 個のファイルをアタッチできます。ファイルは、作成日の昇順で並べ替えられます。以前はリストにアタッチされていたファイルが、リストに含まれない場合は、アシスタントから削除されます。
`metadata`	map	省略可能	オブジェクトにアタッチできる 16 個のキーと値のペアのセット。これは、オブジェクトに関する追加情報を構造化された形式で格納する場合に役立ちます。キーの最大長は 64 文字、値の最大長は 512 文字です。

返品

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

アシスタント変更の例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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
  file_ids=["assistant-abc123", "assistant-abc456"],
)

print(my_updated_assistant)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "code-interpreter"}],
      "model": "gpt-4",
      "file_ids": ["assistant-abc123", "assistant-abc456"]
    }'

アシスタントを削除する

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

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

パスパラメーター

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

返品

削除の状態。

アシスタント削除の例

Python 1.x
REST

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

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

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

アシスタントファイルを削除する

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

アシスタントファイルを削除します。

パスパラメーター

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

返品

ファイルの削除の状態

アシスタントファイル削除の例

Python 1.x
REST

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

deleted_assistant_file = client.beta.assistants.files.delete(
    assistant_id="asst_abc123",
    file_id="assistant-abc123"
)
print(deleted_assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
```  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

ファイルアップロード 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 文字を使用できます。
`file_ids`	配列	このアシスタントにアタッチされているファイル ID のリスト。アシスタントには最大 20 個のファイルをアタッチできます。ファイルは、作成日の昇順で並べ替えられます。
`metadata`	map	オブジェクトにアタッチできる 16 個のキーと値のペアのセット。これは、オブジェクトに関する追加情報を構造化された形式で格納する場合に役立ちます。キーの最大長は 64 文字、値の最大長は 512 文字です。

アシスタントファイルオブジェクト

フィールド	タイプ	説明
`id`	string	API エンドポイントで参照できる識別子。
`object`	string	オブジェクトの種類。これは常に `assistant.file` です
`created_at`	integer	アシスタントファイルが作成されたときの Unix タイムスタンプ (秒単位)。
`assistant_id`	string	ファイルがアタッチされているアシスタント ID。

次の方法で共有

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

アシスタントを作成する

要求本文

返品

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

アシスタントファイルを作成する

返品

アシスタントファイル作成要求の例

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

返品

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

アシスタントファイルのリストを取得する

返品

アシスタントファイルリスト取得の例

アシスタントを取得する

アシスタント取得の例

アシスタントファイルを取得する

返品

アシスタントファイル取得の例

アシスタントを変更する

アシスタント変更の例

アシスタントを削除する

アシスタント削除の例

アシスタントファイルを削除する

アシスタントファイル削除の例

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

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

アシスタントファイルオブジェクト

フィードバック

フィードバック

その他のリソース

次の方法で共有

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

アシスタントを作成する

要求本文

返品

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

アシスタント ファイルを作成する

返品

アシスタント ファイル作成要求の例

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

返品

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

アシスタント ファイルのリストを取得する

返品

アシスタント ファイル リスト取得の例

アシスタントを取得する

アシスタント取得の例

アシスタント ファイルを取得する

返品

アシスタント ファイル取得の例

アシスタントを変更する

アシスタント変更の例

アシスタントを削除する

アシスタント削除の例

アシスタント ファイルを削除する

アシスタント ファイル削除の例

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

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

アシスタント ファイル オブジェクト

フィードバック

フィードバック

その他のリソース

アシスタントファイルを作成する

アシスタントファイル作成要求の例

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

アシスタントファイルのリストを取得する

アシスタントファイルリスト取得の例

アシスタントファイルを取得する

アシスタントファイル取得の例

アシスタントファイルを削除する

アシスタントファイル削除の例

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

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

アシスタントファイルオブジェクト