Azure Functions 用の Azure OpenAI アシスタント クエリ入力バインド

Warning

Azure Functions用のAzure OpenAI拡張は2027年4月20日に廃止されます。 プレビュー拡張バンドルバージョン4.60.0以降には拡張が含まれていません。

状況に応じて、OpenAI、Microsoft Foundry、またはAzure AI 検索のSDKに直接移行してください。 既存のアプリは、host.jsonでバージョン範囲を[4.*, 4.60.0)に設定することで、4.60.0以前のプレビュー拡張機能バンドルバージョンを利用できます。 .NETアプリは対応するAzure OpenAI拡張機能のNuGetパッケージを直接使用し続けられます。 古いバンドルをピン留めすることも、NuGetパッケージの使用を継続しても、2027年4月20日以降のサポートは延長されません。

Azure OpenAI アシスタント クエリ入力バインドを使用すると、Assistants API クエリをコード実行に統合できます。

Azure OpenAI 拡張機能のセットアップと構成の詳細については、「Azure Functions 用の Azure OpenAI 拡張機能」を参照してください。 Azure OpenAI アシスタントの詳細については、「Azure OpenAI Assistants API」を参照してください。

注

リファレンスと例は、Node.js v4 モデルに対してのみ提供されています。

注

リファレンスと例は、Python v2 モデルに対してのみ提供されます。

注

両方の C# プロセス モデルがサポートされていますが、 isolated worker モデル 例のみが提供されます。

例

このバインドに関しては現在、Goのサポートは利用できません。

この例では、アシスタント チャット ボットの会話履歴に対するクエリを実行する HTTP GET 関数の作成プロセスを示します。 プロンプトに対する応答は HTTP 応答で返されます。

/// <summary>
/// HTTP GET function that queries the conversation history of the assistant chat bot.
/// </summary>
[Function(nameof(GetChatState))]
public static IActionResult GetChatState(
   [HttpTrigger(AuthorizationLevel.Function, "get", Route = "assistants/{assistantId}")] HttpRequestData req,
   string assistantId,
   [AssistantQueryInput("{assistantId}", TimestampUtc = "{Query.timestampUTC}", ChatStorageConnectionSetting = DefaultChatStorageConnectionSetting, CollectionName = DefaultCollectionName)] AssistantState state)
{
    return new OkObjectResult(state);
}

この例では、アシスタント チャット ボットの会話履歴に対するクエリを実行する HTTP GET 関数の作成プロセスを示します。 プロンプトに対する応答は HTTP 応答で返されます。

/*
 * HTTP GET function that queries the conversation history of the assistant chat bot.
 */   
@FunctionName("GetChatState")
public HttpResponseMessage getChatState(
    @HttpTrigger(
        name = "req",
        methods = {HttpMethod.GET}, 
        authLevel = AuthorizationLevel.FUNCTION,
        route = "assistants/{assistantId}") 
        HttpRequestMessage<Optional<String>> request,
    @BindingName("assistantId") String assistantId,        
    @AssistantQuery(name = "AssistantState", id = "{assistantId}", timestampUtc = "{Query.timestampUTC}", chatStorageConnectionSetting = DEFAULT_CHATSTORAGE, collectionName = DEFAULT_COLLECTION) AssistantState state,
    final ExecutionContext context) {
        return request.createResponseBuilder(HttpStatus.OK)
            .header("Content-Type", "application/json")
            .body(state)
            .build();
}

この例では、アシスタント チャット ボットの会話履歴に対するクエリを実行する HTTP GET 関数の作成プロセスを示します。 プロンプトに対する応答は HTTP 応答で返されます。

const { app, input, output } = require("@azure/functions");

const chatBotQueryInput = input.generic({
    type: 'assistantQuery',
    id: '{assistantId}',
    timestampUtc: '{Query.timestampUTC}',
    chatStorageConnectionSetting: CHAT_STORAGE_CONNECTION_SETTING,
    collectionName: COLLECTION_NAME
})
app.http('GetChatState', {
    methods: ['GET'],
    route: 'assistants/{assistantId}',
    authLevel: 'function',
    extraInputs: [chatBotQueryInput],
    handler: async (_, context) => {
        const state = context.extraInputs.get(chatBotQueryInput)
        return { status: 200, jsonBody: state }
    }
})

この例では、アシスタント チャット ボットの会話履歴に対するクエリを実行する HTTP GET 関数の作成プロセスを示します。 プロンプトに対する応答は HTTP 応答で返されます。

import { HttpRequest, InvocationContext, app, input, output } from "@azure/functions"

const chatBotQueryInput = input.generic({
    type: 'assistantQuery',
    id: '{assistantId}',
    timestampUtc: '{Query.timestampUTC}',
    chatStorageConnectionSetting: CHAT_STORAGE_CONNECTION_SETTING,
    collectionName: COLLECTION_NAME
})
app.http('GetChatState', {
    methods: ['GET'],
    route: 'assistants/{assistantId}',
    authLevel: 'function',
    extraInputs: [chatBotQueryInput],
    handler: async (_, context) => {
        const state: any = context.extraInputs.get(chatBotQueryInput)
        return { status: 200, jsonBody: state }
    }
})

この例では、アシスタント チャット ボットの会話履歴に対するクエリを実行する HTTP GET 関数の作成プロセスを示します。 プロンプトに対する応答は HTTP 応答で返されます。

チャット状態を取得するための function.json ファイルを次に示します。

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "route": "assistants/{assistantId}",
      "methods": [
        "get"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "name": "State",
      "type": "assistantQuery",
      "direction": "in",
      "dataType": "string",
      "id": "{assistantId}",
      "timestampUtc": "{Query.timestampUTC}",
      "chatStorageConnectionSetting": "AzureWebJobsStorage",
      "collectionName": "ChatState"
    }
  ]
}

function.json ファイルのプロパティについて詳しくは、「構成」セクションをご覧ください。

using namespace System.Net

param($Request, $TriggerMetadata, $State)

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body       = $State
    Headers    = @{
        "Content-Type" = "application/json"
    }
})

この例では、アシスタント チャット ボットの会話履歴に対するクエリを実行する HTTP GET 関数の作成プロセスを示します。 プロンプトに対する応答は HTTP 応答で返されます。

@apis.function_name("GetChatState")
@apis.route(route="assistants/{assistantId}", methods=["GET"])
@apis.assistant_query_input(
    arg_name="state",
    id="{assistantId}",
    timestamp_utc="{Query.timestampUTC}",
    chat_storage_connection_setting=DEFAULT_CHAT_STORAGE_SETTING,
    collection_name=DEFAULT_CHAT_COLLECTION_NAME,
)
def get_chat_state(req: func.HttpRequest, state: str) -> func.HttpResponse:
    return func.HttpResponse(state, status_code=200, mimetype="application/json")

属性

AssistantQuery 属性を適用して、これらのパラメーターをサポートするアシスタント クエリ入力バインドを定義します。

パラメーター 内容
身分証明書 クエリを実行するアシスタントの ID を取得します。
タイムスタンプUTC 省略可。 取得するチャット履歴内の最も古いメッセージのタイムスタンプを取得または設定します。 タイムスタンプは ISO 8601 形式である必要があります (例: 2023-08-01T00:00:00Z)。

注釈

assistantQuery 注釈を使用すると、これらのパラメーターをサポートするアシスタント クエリ入力バインドを定義できます。

要素 内容
名前 入力バインドの名前を取得または設定します。
ID クエリを実行するアシスタントの ID を取得します。
タイムスタンプUTC 省略可。 取得するチャット履歴内の最も古いメッセージのタイムスタンプを取得または設定します。 タイムスタンプは ISO 8601 形式である必要があります (例: 2023-08-01T00:00:00Z)。

デコレーター

プレビュー中に、入力バインドを次のパラメーターをサポートする generic_input_binding 型の assistantQuery バインドとして定義します。

パラメーター 内容
arg_name バインド パラメーターを表す変数の名前。
ID クエリを実行するアシスタントの ID を取得します。
time_stamp_utc 省略可。 取得するチャット履歴内の最も古いメッセージのタイムスタンプを取得または設定します。 タイムスタンプは ISO 8601 形式である必要があります (例: 2023-08-01T00:00:00Z)。

構成

このバインドでは、function.json ファイルで設定したこれらの構成プロパティをサポートします。

プロパティ 内容
タイプ assistantQueryである必要があります。
方向 inである必要があります。
名前 入力バインドの名前。
ID クエリを実行するアシスタントの ID を取得します。
タイムスタンプUTC 省略可。 取得するチャット履歴内の最も古いメッセージのタイムスタンプを取得または設定します。 タイムスタンプは ISO 8601 形式である必要があります (例: 2023-08-01T00:00:00Z)。

構成

このバインドでは、コードで定義されている、これらのプロパティをサポートします。

プロパティ 内容
ID クエリを実行するアシスタントの ID を取得します。
タイムスタンプUTC 省略可。 取得するチャット履歴内の最も古いメッセージのタイムスタンプを取得または設定します。 タイムスタンプは ISO 8601 形式である必要があります (例: 2023-08-01T00:00:00Z)。

使用方法

完全な例については、セクションの例を参照してください。

接続

この接続ガイダンスは、2027年4月20日に廃止されるAzure OpenAI拡張機能を使用している既存アプリに適用されます。 ダイレクトSDKコールに移行する際は、拡張機能のバインディング設定を使うのではなく、選択したSDKの認証および接続ガイダンスに従ってください。

Azure OpenAIのバインディング拡張を使うには、OpenAIモデル定義への接続を指定する必要があります。 以下のいずれかの方法を使って、バインディング内でOpenAIモデル接続を設定します。

  • AIConnectionName bindingプロパティ(OpenAI Azure推奨)を使いましょう。
  • OpenAI Azureのアプリ設定でAZURE_OPENAI_ENDPOINTとAZURE_OPENAI_KEYを設定してください。
  • アプリの設定で Open_API_Key だけに設定してください( https://api.openai.com用)。

接続の設定方法は、モデルAPIと認証方法の両方に依存し、以下の表に示されています:

認証/モデルAPI Azure OpenAI OpenAI(https://api.openai.com)
マネージド・アイデンティティ接続 AIConnectionName サポートしていません
Key Vault 参照 AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key
アプリ設定リファレンス AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key
共有シークレット AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key

管理型アイデンティティベースの接続と AIConnectionName プロパティを活用してください。

AIConnectionNameを使う場合、このプロパティ設定の値は接続の種類によって異なります。

  • マネージド・アイデンティティ接続:AIConnectionNameプロパティ<CONNECTION_NAME_PREFIX>は、複数の設定群が共有するものであり、これらが共同でOpenAIへのアイデンティティベースの接続を定義しますAzure。 詳細については、「 同一性接続の定義」を参照してください。
  • Key Vault参照:AIConnectionNameプロパティ設定は、APIキーが中央管理されている場所へのAzure Key Vault参照を返します。 詳細については、「Key Vault connectionsの定義」をご覧ください。
  • App Configuration reference:AIConnectionNameプロパティ設定はAPIキーまたはKey Vault参照を返すAzure App Configuration参照を返します。 詳細については、接続記事のAzure App Configurationをご覧ください。
  • APIキー: AIConnectionName プロパティ設定はエンドポイントとキーを含むアプリ設定に解決されます。 共有鍵は漏洩する可能性があるため、可能な限り管理型ID接続を使用してください。 詳細については、「 接続の定義」を参照してください。

バインディング接続について詳しく知りたい方は、「Azure Functionsの接続管理」をご覧ください。

OpenAIのバインディングには、OpenAIとの接続を定義するアプリ設定群のAIConnectionNameを指定するための<ConnectionNamePrefix>プロパティAzure含まれています。

設定名 内容
<CONNECTION_NAME_PREFIX>__endpoint Azure OpenAIサービスのURIエンドポイントを設定します。 この設定は常に必須です。
<CONNECTION_NAME_PREFIX>__clientId アクセス トークンを取得するときに使用する特定のユーザー割り当て ID を設定します。 <CONNECTION_NAME_PREFIX>__credential を managedidentity に設定する必要があります。 このプロパティは、アプリケーションに割り当てられたユーザー割り当て ID に相当するクライアント ID を受け取ります。 リソース ID とクライアント ID の両方を指定することは無効です。 このプロパティを指定しない場合は、システムが割り当てたアイデンティティが使われます。 このプロパティは、 を設定しないとき、credentialで異なる方法で使用されます。
<CONNECTION_NAME_PREFIX>__credential 接続のaccess トークンを取得する方法を定義します。 マネージド ID 認証には managedidentity を使用します。 この値は、ホスティング環境でマネージド ID が使用できる場合にのみ有効です。
<CONNECTION_NAME_PREFIX>__managedIdentityResourceId credentialがmanagedidentityに設定されている場合、このプロパティでトークンを取得する際に使用するリソース識別子を指定します。 プロパティは、ユーザー定義マネージド ID のリソース ID に対応するリソース識別子を受け取ります。 リソース ID とクライアント ID の両方を指定することは無効です。 どちらかを指定しなければ、システムが割り当てたアイデンティティが使われます。 このプロパティは、 を設定しないとき、credentialで異なる方法で使用されます。
<CONNECTION_NAME_PREFIX>__key 鍵ベースの認証を用いて、Azure OpenAIサービスのエンドポイントにアクセスするために必要な共有秘密鍵を設定します。 セキュリティのベストプラクティスとして、認証には必ず管理されたIDと共にMicrosoft Entra IDを使用してください。

AIConnectionNameプロパティをmyAzureOpenAIに設定する際は、以下の管理されたID接続設定を考慮してください。

  • myAzureOpenAI__endpoint=https://contoso.openai.azure.com/
  • myAzureOpenAI__credential=managedidentity
  • myAzureOpenAI__clientId=aaaaaaaa-bbbb-cccc-1111-222222222222

実行時には、ホストはこれらの設定を単一の myAzureOpenAI 設定として解釈します。

"myAzureOpenAI":
{
    "endpoint": "https://contoso.openai.azure.com/",
    "credential": "managedidentity",
    "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

マネージドIDを使う場合は、必ず Cognitive Services OpenAIユーザー ロールに自分のIDを追加してください。

ローカルで動作する場合は、これらの設定を local.settings.json プロジェクトファイルに追加してください。 詳細については、「 ID ベースの接続を使用したローカル開発」を参照してください。

詳細については、アプリケーション設定の操作に関する記事を参照してください。