クイック スタート: Azure OpenAI Assistants (プレビュー) の使用を開始する
Azure OpenAI Assistants (プレビュー) を使用すると、カスタム命令を使用してニーズに合わせた AI アシスタントを作成し、コード インタープリターやカスタム関数などの高度なツールで強化できます。
重要
この記事で説明する機能の一部は、プレビューでのみ使用できる場合があります。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境ではお勧めしません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。
前提条件
- Azure サブスクリプション。無料で作成できます。
- モデルがデプロイされた Azure AI ハブ リソース。 モデル デプロイの詳細については、リソース デプロイ ガイドを参照してください。
- Azure AI Studio の Azure AI プロジェクト。
Azure AI Studio (プレビュー) に移動する
Note
Azure OpenAI Studio を使用できますが、こちらの手順を使用して Azure AI Studio を使用することをお勧めします。 AI Studio では、より高速で、より多くのファイルをサポートするファイル検索ツールなど、いくつかのアップグレードを提供する Assistants v2 を使用できます。
Azure AI Studio にサインインします。
ご自分のプロジェクトに移動するか、Azure AI Studio で新しいプロジェクトを作成します。
プロジェクトの概要から、[プロジェクト プレイグラウンド] の下にある [アシスタント] を選びます。
アシスタント プレイグラウンドを使用すると、コードを実行する必要なく、AI Assistants の探索、プロタイプ作成、テストを行うことができます。 このページから、新しいアイデアを簡単に反復して、実験できます。
プレイグラウンドには、アシスタントを構成するためのオプションがいくつかあります。 次の手順では、[アシスタント設定] ウィンドウを使用して新しい AI アシスタントを作成します。
名前 説明 アシスタント名 特定のモデルに関連付けられているデプロイ名。 手順 手順はシステムメッセージに似ており、モデルに対して、どのように動作する必要があるかに関するガイダンスと、応答を生成する際に参照する必要があるコンテキストを提供します。 アシスタントのパーソナリティを記述したり、答えるべきことと答えるべきでないことを指示したり、応答のフォーマットを指示したりすることができます。 また、モデルが応答する際に実行する必要がある手順の例を提供することもできます。 デプロイ ここでは、アシスタントで使用するモデル デプロイを設定します。 関数 API 呼び出しを形成し、仕様に基づいてデータ出力を構造化するために、モデルのカスタム関数定義を作成します。 このクイックスタートでは使用しません。 コード インタープリター コード インタープリターを使用すると、サンドボックス化された Python 環境にアクセスできます。この環境を使用して、モデルでコードをテストしたり、実行したりすることができます。 [ファイル] ツールで使用するために、最大サイズが 512 MB のファイルを最大 10,000 個アップロードできます。 このクイックスタートでは使用しません。
最初のアシスタントを作成する
使用するデプロイを [デプロイ] ドロップダウンから選択します。
[アシスタントのセットアップ] ドロップダウンから [新規] を選択します。
アシスタントに名前を付けます。
「あなたは、数学の質問に答えるのに役立つコードを作成できる AI アシスタントです」という指示を入力します
モデル デプロイを選択します。 最新の GPT-4 モデルのいずれかを使用してテストすることをお勧めします。
コード インタープリターを有効にするトグルを選択します。
[保存] を選択します。
アシスタントが答える質問として 「式
3x + 11 = 14
を解く必要があります。 助けていただけますか?」 と入力します。[追加と実行] ボタン を選択します
The solution to the equation (3x + 11 = 14) is (x = 1).
この回答が正しいことはわかりますが、モデルがこの回答に到達するためにコード インタープリターを使用したこと、およびモデルのトレーニング データからの回答を単に繰り返すのではなく、モデルがコードを記述し、それが有効であることを確認するために、別の質問をします。
フォローアップの質問として「この解を得るために実行したコードを示してください」と入力します。
Sure. The code is very straightforward
# calculation x = (14 - 11) / 3 x
First, we subtract 11 from 14, then divide the result by 3. This gives us the value of x which is 1.0.
右側のパネルのログを参照して、コード インタープリターが使用されたことを確認し、応答を生成するために実行されたコードを検証することもできます。 コード インタープリターを使用すると、質問をコードに変換し、サンドボックス化された Python 環境で実行することで、より複雑な数学の質問に応答する機能がモデルに提供されますが、モデルが質問をコード内の有効な表現に正しく変換したことを確認するには、応答を検証する必要があることに留意することが重要です。
重要な概念
アシスタント プレイグラウンドを使用する場合は、次の概念に注意してください。
ツール
個々のアシスタントは、code interpreter
などの最大 128 個のツールと、ユーザーが関数を使用して作成するカスタム ツールにアクセスできます。
チャット セッション
アシスタント API 内で "スレッド" とも呼ばれるチャット セッションは、ユーザーとアシスタントの間で会話が行われる場所です。 従来のチャット入力候補の呼び出しとは異なり、スレッド内のメッセージの数に制限はありません。 要求は、アシスタントによって、モデルの入力トークンの制限に合わせて自動的に圧縮されます。
これは、会話の各ターン中にモデルに渡されるトークンの数をユーザーが制御していないことも意味します。 トークンの管理は抽象化され、Assistants API によって完全に処理されます。
現在の会話履歴を削除するには、[Clear chat] (チャットをクリアする) ボタンを選択します。
テキスト入力ボタンの下に、次の 2 つのボタンがあります。
- 実行せずにメッセージを追加する。
- 追加して実行する。
ログ
ログは、アシスタント API アクティビティの詳細なスナップショットを提供します。
パネルを表示する
既定では、アシスタントのセットアップ、チャット セッション、ログの 3 つのパネルがあります。 パネルの表示 ではパネルの追加、削除、並べ替えができます。 もしパネルを閉じてしまい、元に戻したくなった場合は、パネルを表示 を使って失ったパネルを復元してください。
リソースをクリーンアップする
Azure OpenAI リソースをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除できます。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。
または、アシスタントやスレッドをアシスタントの API を介して削除することもできます。
関連項目
- Assistants を使用する方法の詳細については、Assistants の攻略ガイドを参照してください。
- Azure OpenAI Assistants API のサンプル
リファレンス ドキュメント | ライブラリのソース コード | パッケージ (PyPi) |
前提条件
- Azure サブスクリプション - 無料アカウントを作成します
- Python 3.8 以降のバージョン
- Python ライブラリ: os、openai (バージョン 1.x が必要)
- Azure CLI をローカル開発環境でのパスワードレス認証に使用する場合は、Azure CLI でサインインして必要なコンテキストを作成します。
- サポートされているリージョン内の互換性があるモデルを持つ Azure OpenAI リソース。
- Responsible AI の透明性に関する注意や、その他の責任ある AI に関するリソースを確認して、Azure OpenAI Service の機能と制限事項を十分に理解することをお勧めします。
- この例のテストには、
gpt-4 (1106-preview)
モデルがデプロイされた Azure OpenAI リソースが使用されました。
パスワードレス認証が推奨されます
パスワードレス認証の場合は、次が必要になります:
- azure-identity パッケージを使用します。
- ユーザー アカウントに
Cognitive Services User
ロールを割り当てます。 これは、Azure portal の [アクセスの制御 (IAM)]>[ロールの割り当ての追加] で実行できます。 az login
などの Azure CLI でサインインします。
設定
- 次を使用して、OpenAI Python クライアント ライブラリをインストールします。
pip install openai
- 推奨されるパスワードレス認証は次のとおりです。
pip install azure-identity
Note
- ファイル検索では、アシスタントあたり最大 10,000 個のファイルを取り込むことができます。これは以前の 500 倍以上の量です。 これは高速で、マルチスレッド検索を通して並列クエリをサポートしており、強化された再ランク付けとクエリの書き換えを特徴としています。
- ベクトル ストアは、API 内の新しいオブジェクトです。 ファイルがベクトル ストアに追加されると、自動的にそのファイルの解析、チャンク、埋め込みが行われ、検索の準備が整います。 ベクトル ストアは、複数のアシスタントとスレッドにわたって使用できるため、ファイル管理と課金が単純化されます。
- 特定の実行において特定のツール (ファイル検索、コード インタープリター、関数など) の使用を強制するために使用できる
tool_choice
パラメーターのサポートが追加されました。
Note
このライブラリは、OpenAI によって保持されます。 このライブラリの最新の更新を追跡するには、リリース履歴を参照してください。
キーとエンドポイントを取得する
Azure OpenAI サービスに対して正常に呼び出しを行うには、次のものが必要です。
変数名 | 値 |
---|---|
ENDPOINT |
この値は、Azure portal からリソースを調べる際の キーとエンドポイント セクションにあります。 または、 Azure OpenAI Studio>Playground>View コードで値を見つけることができます。 エンドポイントの例: https://docs-test-001.openai.azure.com/ 。 |
API-KEY |
この値は、Azure portal からリソースを調べる際の キーとエンドポイント セクションにあります。 KEY1 または KEY2 を使用できます。 |
DEPLOYMENT-NAME |
この値は、モデルのデプロイ時にデプロイに対して選択したカスタム名に対応します。 この値は、Azure portal の Resource Management>モデル デプロイ または Azure OpenAI Studio の Management>デプロイ にあります。 |
Azure portal でリソースに移動します。 キーとエンドポイント は、リソース管理 セクションにあります。 エンドポイントとアクセス キーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1
または KEY2
を使用できます。 常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。
環境変数
キーとエンドポイントの永続的な環境変数を作成して割り当てます。
重要
API キーを使用する場合は、それを Azure Key Vault などの別の場所に安全に保存します。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。
AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。
setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"
アシスタントを作成する
このコードで、次の値を指定します。
名前 | 説明 |
---|---|
アシスタント名 | 特定のモデルに関連付けられているデプロイ名。 |
手順 | 手順はシステムメッセージに似ており、モデルに対して、どのように動作する必要があるかに関するガイダンスと、応答を生成する際に参照する必要があるコンテキストを提供します。 アシスタントのパーソナリティを記述したり、答えるべきことと答えるべきでないことを指示したり、応答のフォーマットを指示したりすることができます。 また、モデルが応答する際に実行する必要がある手順の例を提供することもできます。 |
モデル | ここでは、アシスタントで使用するモデル デプロイ名を設定します。 取得ツールには、gpt-35-turbo (1106) または gpt-4 (1106-preview) モデルが必要です。 モデル名が同じでない限り、この値をモデル名ではなくデプロイ名に設定します。 |
コード インタープリター | コード インタープリターを使用すると、サンドボックス化された Python 環境にアクセスできます。この環境を使用して、モデルでコードをテストしたり、実行したりすることができます。 |
ツール
個々のアシスタントは、code interpreter
などの最大 128 個のツールと、ユーザーが関数を使用して作成するカスタム ツールにアクセスできます。
Python アプリを作成する
az login
で Azure にサインインし、次の推奨されるパスワードレス Python 例でアシスタントを作成して実行します:
import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI
token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")
client = AzureOpenAI(
azure_ad_token_provider=token_provider,
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
api_version="2024-05-01-preview",
)
# Create an assistant
assistant = client.beta.assistants.create(
name="Math Assist",
instructions="You are an AI assistant that can write code to help answer math questions.",
tools=[{"type": "code_interpreter"}],
model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)
# Create a thread
thread = client.beta.threads.create()
# Add a user question to the thread
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)
# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
thread_id=thread.id,
assistant_id=assistant.id,
instructions="Please address the user as Jane Doe. The user has a premium account.",
)
print("Run completed with status: " + run.status)
if run.status == "completed":
messages = client.beta.threads.messages.list(thread_id=thread.id)
print(messages.to_json(indent=2))
認証にサービス API キーを使用するには、次の Python 例でアシスタントを作成して実行します:
import os
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.environ["AZURE_OPENAI_API_KEY"],
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
api_version="2024-05-01-preview",
)
# Create an assistant
assistant = client.beta.assistants.create(
name="Math Assist",
instructions="You are an AI assistant that can write code to help answer math questions.",
tools=[{"type": "code_interpreter"}],
model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)
# Create a thread
thread = client.beta.threads.create()
# Add a user question to the thread
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)
# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
thread_id=thread.id,
assistant_id=assistant.id,
instructions="Please address the user as Jane Doe. The user has a premium account.",
)
print("Run completed with status: " + run.status)
if run.status == "completed":
messages = client.beta.threads.messages.list(thread_id=thread.id)
print(messages.to_json(indent=2))
出力
実行が次の状態で完了: 完了
{
"data": [
{
"id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
"assistant_id": "asst_cYqL1RuwLyFV3HU1gkaE2k0K",
"attachments": [],
"content": [
{
"text": {
"annotations": [],
"value": "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
},
"type": "text"
}
],
"created_at": 1716397091,
"metadata": {},
"object": "thread.message",
"role": "assistant",
"run_id": "run_hFgBPbUtO8ZNTnNPC8PgpH1S",
"thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
},
{
"id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
"assistant_id": null,
"attachments": [],
"content": [
{
"text": {
"annotations": [],
"value": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
},
"type": "text"
}
],
"created_at": 1716397025,
"metadata": {},
"object": "thread.message",
"role": "user",
"run_id": null,
"thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
}
],
"object": "list",
"first_id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
"last_id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
"has_more": false
}
結果を理解する
この例では、コード インタープリターを有効にしてアシスタントを作成します。 数学の問題をアシスタントに質問すると、質問の回答を決定するために、アシスタントによって、質問が Python コードに変換され、サンドボックス化された環境でコードが実行されます。 回答に到達するためにモデルによって作成され、テストされるコードは次のとおりです。
from sympy import symbols, Eq, solve
# Define the variable
x = symbols('x')
# Define the equation
equation = Eq(3*x + 11, 14)
# Solve the equation
solution = solve(equation, x)
solution
コード インタープリターを使用すると、質問をコードに変換し、解に到達するまでそのコードを Python サンドボックスで実行することで、より複雑なクエリに応答する機能がモデルに提供されますが、モデルが質問をコード内の有効な表現に正しく変換したことを確認するには、応答を検証する必要があることに留意することが重要です。
リソースをクリーンアップする
Azure OpenAI リソースをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除できます。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。
関連項目
- Assistants を使用する方法の詳細については、Assistants の攻略ガイドを参照してください。
- Azure OpenAI Assistants API のサンプル
リファレンスのドキュメント | ソース コード | パッケージ (NuGet)
前提条件
- Azure サブスクリプション - 無料アカウントを作成します
- .NET 8 SDK
- サポートされているリージョン内の互換性があるモデルを持つ Azure OpenAI リソース。
- Responsible AI の透明性に関する注意や、その他の責任ある AI に関するリソースを確認して、Azure OpenAI Service の機能と制限事項を十分に理解することをお勧めします。
- この例のテストには、
gpt-4 (1106-preview)
モデルがデプロイされた Azure OpenAI リソースが使用されました。
設定
新しい .NET Core アプリを作成する
コンソール ウィンドウ (cmd、PowerShell、Bash など) で、dotnet new
コマンドを使用し、azure-openai-quickstart
という名前で新しいコンソール アプリを作成します。 このコマンドにより、次の C# ソース ファイルを 1 つ使用する単純な "Hello World" プロジェクトが作成されます: Program.cs。
dotnet new console -n azure-openai-assistants-quickstart
新しく作成されたアプリ フォルダーにディレクトリを変更します。 次を使用してアプリケーションをビルドできます。
dotnet build
ビルドの出力に警告やエラーが含まれないようにする必要があります。
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
以下を使って、OpenAI .NET クライアント ライブラリをインストールします。
dotnet add package Azure.AI.OpenAI.Assistants --prerelease
キーとエンドポイントを取得する
Azure OpenAI に対して正常に呼び出しを行うには、エンドポイントとキーが必要です。
変数名 | 値 |
---|---|
ENDPOINT |
この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Azure OpenAI Studio>[プレイグラウンド]>[コード ビュー] で値を確認することもできます。 エンドポイントの例: https://docs-test-001.openai.azure.com/ 。 |
API-KEY |
この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 KEY1 または KEY2 を使用できます。 |
Azure portal でリソースに移動します。 [キーとエンドポイント] セクションは、[リソース管理] セクションにあります。 エンドポイントとアクセス キーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1
または KEY2
を使用できます。 常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。
環境変数
キーとエンドポイントの永続的な環境変数を作成して割り当てます。
重要
API キーを使用する場合は、それを Azure Key Vault などの別の場所に安全に保存します。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。
AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。
setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"
アシスタントを作成する
このコードで、次の値を指定します。
名前 | 説明 |
---|---|
アシスタント名 | 特定のモデルに関連付けられているデプロイ名。 |
手順 | 手順はシステムメッセージに似ており、モデルに対して、どのように動作する必要があるかに関するガイダンスと、応答を生成する際に参照する必要があるコンテキストを提供します。 アシスタントのパーソナリティを記述したり、答えるべきことと答えるべきでないことを指示したり、応答のフォーマットを指示したりすることができます。 また、モデルが応答する際に実行する必要がある手順の例を提供することもできます。 |
モデル | ここでは、アシスタントで使用するモデル デプロイ名を設定します。 取得ツールには、gpt-35-turbo (1106) または gpt-4 (1106-preview) モデルが必要です。 モデル名が同じでない限り、この値をモデル名ではなくデプロイ名に設定します。 |
コード インタープリター | コード インタープリターを使用すると、サンドボックス化された Python 環境にアクセスできます。この環境を使用して、モデルでコードをテストしたり、実行したりすることができます。 |
ツール
個々のアシスタントは、code interpreter
などの最大 128 個のツールと、ユーザーが関数を使用して作成するカスタム ツールにアクセスできます。
次を使用してアシスタントを作成して実行します。
using Azure;
using Azure.AI.OpenAI.Assistants;
string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new ArgumentNullException("AZURE_OPENAI_ENDPOINT");
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY") ?? throw new ArgumentNullException("AZURE_OPENAI_API_KEY");
AssistantsClient client = new AssistantsClient(new Uri(endpoint), new AzureKeyCredential(key));
// Create an assistant
Assistant assistant = await client.CreateAssistantAsync(
new AssistantCreationOptions("gpt-4-1106-preview") // Replace this with the name of your model deployment
{
Name = "Math Tutor",
Instructions = "You are a personal math tutor. Write and run code to answer math questions.",
Tools = { new CodeInterpreterToolDefinition() }
});
// Create a thread
AssistantThread thread = await client.CreateThreadAsync();
// Add a user question to the thread
ThreadMessage message = await client.CreateMessageAsync(
thread.Id,
MessageRole.User,
"I need to solve the equation `3x + 11 = 14`. Can you help me?");
// Run the thread
ThreadRun run = await client.CreateRunAsync(
thread.Id,
new CreateRunOptions(assistant.Id)
);
// Wait for the assistant to respond
do
{
await Task.Delay(TimeSpan.FromMilliseconds(500));
run = await client.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
|| run.Status == RunStatus.InProgress);
// Get the messages
PageableList<ThreadMessage> messagesPage = await client.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = messagesPage.Data;
// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages.Reverse())
{
Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
foreach (MessageContent contentItem in threadMessage.ContentItems)
{
if (contentItem is MessageTextContent textItem)
{
Console.Write(textItem.Text);
}
Console.WriteLine();
}
}
これにより、次のように出力が表示されます。
2024-03-05 03:38:17 - user: I need to solve the equation `3x + 11 = 14`. Can you help me?
2024-03-05 03:38:25 - assistant: The solution to the equation \(3x + 11 = 14\) is \(x = 1\).
再実行する前にスレッド上に新しいメッセージを作成できます。この場合、アシスタントは過去のメッセージをスレッド内のコンテキストとして使います。
リソースをクリーンアップする
Azure OpenAI リソースをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除できます。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。
関連項目
- Assistants を使用する方法の詳細については、Assistants の攻略ガイドを参照してください。
- Azure OpenAI Assistants API のサンプル
リファレンス ドキュメント | ライブラリのソース コード | パッケージ (npm) |
前提条件
- Azure サブスクリプション - 無料アカウントを作成します
- TypeScript または ESM をサポートする Node.js LTS。
- Azure CLI をローカル開発環境でのパスワードレス認証に使用する場合は、Azure CLI でサインインして必要なコンテキストを作成します。
- サポートされているリージョン内の互換性があるモデルを持つ Azure OpenAI リソース。
- Responsible AI の透明性に関する注意や、その他の責任ある AI に関するリソースを確認して、Azure OpenAI Service の機能と制限事項を十分に理解することをお勧めします。
- この例のテストには、
gpt-4 (1106-preview)
モデルがデプロイされた Azure OpenAI リソースが使用されました。
パスワードレス認証が推奨されます
パスワードレス認証の場合は、次が必要になります:
@azure/identity
パッケージを使用します。- ユーザー アカウントに
Cognitive Services User
ロールを割り当てます。 これは、Azure portal の [アクセスの制御 (IAM)]>[ロールの割り当ての追加] で実行できます。 az login
などの Azure CLI でサインインします。
設定
次を使用して JavaScript 用の OpenAI アシスタントをインストールします。
npm install openai
推奨されるパスワードレス認証は次のとおりです。
npm install @azure/identity
キーとエンドポイントを取得する
Azure OpenAI サービスに対して正常に呼び出しを行うには、次のものが必要です。
変数名 | 値 |
---|---|
ENDPOINT |
この値は、Azure portal からリソースを調べる際の キーとエンドポイント セクションにあります。 または、 Azure OpenAI Studio>Playground>View コードで値を見つけることができます。 エンドポイントの例: https://docs-test-001.openai.azure.com/ 。 |
API-KEY |
この値は、Azure portal からリソースを調べる際の キーとエンドポイント セクションにあります。 KEY1 または KEY2 を使用できます。 |
DEPLOYMENT-NAME |
この値は、モデルのデプロイ時にデプロイに対して選択したカスタム名に対応します。 この値は、Azure portal の Resource Management>モデル デプロイ または Azure OpenAI Studio の Management>デプロイ にあります。 |
Azure portal でリソースに移動します。 キーとエンドポイント は、リソース管理 セクションにあります。 エンドポイントとアクセス キーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1
または KEY2
を使用できます。 常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。
環境変数
キーとエンドポイントの永続的な環境変数を作成して割り当てます。
重要
API キーを使用する場合は、それを Azure Key Vault などの別の場所に安全に保存します。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。
AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。
setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"
以下に示すデプロイ名と API バージョン用の環境変数を追加します。
AZURE_OPENAI_DEPLOYMENT_NAME
: Azure portal に表示されているデプロイ名。OPENAI_API_VERSION
: API バージョンの詳細を確認してください。
setx AZURE_OPENAI_DEPLOYMENT_NAME "REPLACE_WITH_YOUR_DEPLOYMENT_NAME"
setx OPENAI_API_VERSION "REPLACE_WITH_YOUR_API_VERSION"
アシスタントを作成する
このコードで、次の値を指定します。
名前 | 説明 |
---|---|
アシスタント名 | 特定のモデルに関連付けられているデプロイ名。 |
手順 | 手順はシステムメッセージに似ており、モデルに対して、どのように動作する必要があるかに関するガイダンスと、応答を生成する際に参照する必要があるコンテキストを提供します。 アシスタントのパーソナリティを記述したり、答えるべきことと答えるべきでないことを指示したり、応答のフォーマットを指示したりすることができます。 また、モデルが応答する際に実行する必要がある手順の例を提供することもできます。 |
モデル | これはデプロイ名です。 |
コード インタープリター | コード インタープリターを使用すると、サンドボックス化された Python 環境にアクセスできます。この環境を使用して、モデルでコードをテストしたり、実行したりすることができます。 |
ツール
個々のアシスタントは、code interpreter
などの最大 128 個のツールと、ユーザーが関数を使用して作成するカスタム ツールにアクセスできます。
az login
で Azure にサインインし、次の推奨されるパスワードレス TypeScript モジュール (index.ts) でアシスタントを作成して実行します:
import "dotenv/config";
import { AzureOpenAI } from "openai";
import {
Assistant,
AssistantCreateParams,
AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";
// Add `Cognitive Services User` to identity for Azure OpenAI resource
import {
DefaultAzureCredential,
getBearerTokenProvider,
} from "@azure/identity";
// Get environment variables
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
.AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;
// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
throw new Error(
"Please ensure to set AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_ENDPOINT in your environment variables."
);
}
// Get Azure SDK client
const getClient = (): AzureOpenAI => {
const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);
const assistantsClient = new AzureOpenAI({
endpoint: azureOpenAIEndpoint,
apiVersion: openAIVersion,
azureADTokenProvider,
});
return assistantsClient;
};
const assistantsClient = getClient();
const options: AssistantCreateParams = {
model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
name: "Math Tutor",
instructions:
"You are a personal math tutor. Write and run JavaScript code to answer math questions.",
tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";
// Create an assistant
const assistantResponse: Assistant =
await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);
// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);
// Add a user question to the thread
const threadResponse: Message =
await assistantsClient.beta.threads.messages.create(assistantThread.id, {
role,
content: message,
});
console.log(`Message created: ${JSON.stringify(threadResponse)}`);
// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
assistantThread.id,
{
assistant_id: assistantResponse.id,
},
{ pollIntervalMs: 500 }
);
console.log(`Run created: ${JSON.stringify(runResponse)}`);
// Get the messages
const runMessages: MessagesPage =
await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
for (const item of runMessageDatum.content) {
// types are: "image_file" or "text"
if (item.type === "text") {
console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
}
}
}
認証にサービス キーを使用するには、次の TypeScript モジュール (index.ts) でアシスタントを作成して実行します:
import "dotenv/config";
import { AzureOpenAI } from "openai";
import {
Assistant,
AssistantCreateParams,
AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";
// Get environment variables
const azureOpenAIKey = process.env.AZURE_OPENAI_KEY as string;
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
.AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;
// Check env variables
if (!azureOpenAIKey || !azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
throw new Error(
"Please set AZURE_OPENAI_KEY and AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME in your environment variables."
);
}
// Get Azure SDK client
const getClient = (): AzureOpenAI => {
const assistantsClient = new AzureOpenAI({
endpoint: azureOpenAIEndpoint,
apiVersion: openAIVersion,
apiKey: azureOpenAIKey,
});
return assistantsClient;
};
const assistantsClient = getClient();
const options: AssistantCreateParams = {
model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
name: "Math Tutor",
instructions:
"You are a personal math tutor. Write and run JavaScript code to answer math questions.",
tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";
// Create an assistant
const assistantResponse: Assistant =
await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);
// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);
// Add a user question to the thread
const threadResponse: Message =
await assistantsClient.beta.threads.messages.create(assistantThread.id, {
role,
content: message,
});
console.log(`Message created: ${JSON.stringify(threadResponse)}`);
// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
assistantThread.id,
{
assistant_id: assistantResponse.id,
},
{ pollIntervalMs: 500 }
);
console.log(`Run created: ${JSON.stringify(runResponse)}`);
// Get the messages
const runMessages: MessagesPage =
await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
for (const item of runMessageDatum.content) {
// types are: "image_file" or "text"
if (item.type === "text") {
console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
}
}
}
出力
Assistant created: {"id":"asst_zXaZ5usTjdD0JGcNViJM2M6N","createdAt":"2024-04-08T19:26:38.000Z","name":"Math Tutor","description":null,"model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"fileIds":[],"metadata":{}}
Thread created: {"id":"thread_KJuyrB7hynun4rvxWdfKLIqy","createdAt":"2024-04-08T19:26:38.000Z","metadata":{}}
Message created: {"id":"msg_o0VkXnQj3juOXXRCnlZ686ff","createdAt":"2024-04-08T19:26:38.000Z","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","role":"user","content":[{"type":"text","text":{"value":"I need to solve the equation `3x + 11 = 14`. Can you help me?","annotations":[]},"imageFile":{}}],"assistantId":null,"runId":null,"fileIds":[],"metadata":{}}
Created run
Run created: {"id":"run_P8CvlouB8V9ZWxYiiVdL0FND","object":"thread.run","status":"queued","model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"metadata":{},"usage":null,"assistantId":"asst_zXaZ5usTjdD0JGcNViJM2M6N","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","fileIds":[],"createdAt":"2024-04-08T19:26:39.000Z","expiresAt":"2024-04-08T19:36:39.000Z","startedAt":null,"completedAt":null,"cancelledAt":null,"failedAt":null}
Message content: "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
Message content: "Yes, of course! To solve the equation \\( 3x + 11 = 14 \\), we can follow these steps:\n\n1. Subtract 11 from both sides of the equation to isolate the term with x.\n2. Then, divide by 3 to find the value of x.\n\nLet me calculate that for you."
Message content: "I need to solve the equation `3x + 11 = 14`. Can you help me?"
コード インタープリターを使用すると、質問をコードに変換し、解に到達するまでそのコードを JavaScript で実行することで、より複雑なクエリに応答する機能がモデルに提供されますが、モデルが質問をコード内の有効な表現に正しく変換したことを確認するには、応答を検証する必要があることに留意することが重要です。
リソースをクリーンアップする
Azure OpenAI リソースをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除できます。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。
サンプル コード
関連項目
- Assistants を使用する方法の詳細については、Assistants の攻略ガイドを参照してください。
- Azure OpenAI Assistants API のサンプル
前提条件
- Azure サブスクリプション - 無料アカウントを作成します
- Python 3.8 以降のバージョン
- サポートされているリージョン内の互換性があるモデルを持つ Azure OpenAI リソース。
- Responsible AI の透明性に関する注意や、その他の責任ある AI に関するリソースを確認して、Azure OpenAI Service の機能と制限事項を十分に理解することをお勧めします。
- この例のテストには、
gpt-4 (1106-preview)
モデルがデプロイされた Azure OpenAI リソースが使用されました。
設定
キーとエンドポイントを取得する
Azure OpenAI に対して正常に呼び出しを行うには、次のものが必要です。
変数名 | 値 |
---|---|
ENDPOINT |
この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、Azure OpenAI Studio>[プレイグラウンド]>[コード ビュー] で値を確認することもできます。 エンドポイントの例: https://docs-test-001.openai.azure.com/ 。 |
API-KEY |
この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 KEY1 または KEY2 を使用できます。 |
DEPLOYMENT-NAME |
この値は、モデルのデプロイ時にデプロイに対して選択したカスタム名に対応します。 この値は、Azure portal の [リソース管理]>[デプロイ] または Azure OpenAI Studio の [管理]>[デプロイ] で確認できます。 |
Azure portal でリソースに移動します。 [エンドポイントとキー] は [リソース管理] セクションにあります。 エンドポイントとアクセス キーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1
または KEY2
を使用できます。 常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。
環境変数
キーとエンドポイントの永続的な環境変数を作成して割り当てます。
重要
API キーを使用する場合は、それを Azure Key Vault などの別の場所に安全に保存します。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。
AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。
setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"
REST API
アシスタントを作成する
Note
Azure OpenAI では、model
パラメーターにモデル デプロイ名が必要です。 モデル デプロイ名が基になるモデルの名前と異なる場合は、コードを "model": "{your-custom-model-deployment-name}"
に調整します。
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.",
"name": "Math Assist",
"tools": [{"type": "code_interpreter"}],
"model": "gpt-4-1106-preview"
}'
ツール
個々のアシスタントは、code interpreter
などの最大 128 個のツールと、ユーザーが関数を使用して作成するカスタム ツールにアクセスできます。
スレッドを作成する
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads \
-H "Content-Type: application/json" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
-d ''
ユーザーの質問をスレッドに追加する
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
-H "Content-Type: application/json" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
-d '{
"role": "user",
"content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
}'
スレッドを実行する
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs \
-H "api-key: $AZURE_OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "asst_abc123",
}'
実行の状態を取得する
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_abc123 \
-H "api-key: $AZURE_OPENAI_API_KEY" \
アシスタントの応答
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
-H "Content-Type: application/json" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
結果を理解する
この例では、コード インタープリターを有効にしてアシスタントを作成します。 数学の問題をアシスタントに質問すると、質問の回答を決定するために、アシスタントによって、質問が Python コードに変換され、サンドボックス化された環境でコードが実行されます。 回答に到達するためにモデルによって作成され、テストされるコードは次のとおりです。
from sympy import symbols, Eq, solve
# Define the variable
x = symbols('x')
# Define the equation
equation = Eq(3*x + 11, 14)
# Solve the equation
solution = solve(equation, x)
solution
コード インタープリターを使用すると、質問をコードに変換し、解に到達するまでそのコードを Python サンドボックスで実行することで、より複雑なクエリに応答する機能がモデルに提供されますが、モデルが質問をコード内の有効な表現に正しく変換したことを確認するには、応答を検証する必要があることに留意することが重要です。
リソースをクリーンアップする
Azure OpenAI リソースをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除できます。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。
関連項目
- Assistants を使用する方法の詳細については、Assistants の攻略ガイドを参照してください。
- Azure OpenAI Assistants API のサンプル