Azure Functions の Azure OpenAI セマンティック検索入力バインド

Von Bedeutung

現在、Azure Functions 用の Azure OpenAI 拡張機能はプレビュー段階です。

Azure OpenAI セマンティック検索入力バインドを使用すると、埋め込みでセマンティック検索を使用できます。

Azure OpenAI 拡張機能のセットアップと構成の詳細については、「Azure Functions 用の Azure OpenAI 拡張機能」を参照してください。 Azure AI 検索でのセマンティック ランク付けの詳細については、「Azure AI 検索 でのセマンティック ランク付け」を参照してください。

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

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

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

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

この例では、ファイルに対してセマンティック検索を実行する方法を示します。

[Function("PromptFile")]
public static IActionResult PromptFile(
    [HttpTrigger(AuthorizationLevel.Function, "post")] SemanticSearchRequest unused,
    [SemanticSearchInput("AISearchEndpoint", "openai-index", Query = "{prompt}", ChatModel = "%CHAT_MODEL_DEPLOYMENT_NAME%", EmbeddingsModel = "%EMBEDDING_MODEL_DEPLOYMENT_NAME%", AIConnectionName = "AzureOpenAI")] SemanticSearchContext result)
{
    return new ContentResult { Content = result.Response, ContentType = "text/plain" };
}

この例では、ファイルに対してセマンティック検索を実行する方法を示します。

@FunctionName("PromptFile")
public HttpResponseMessage promptFile(
    @HttpTrigger(
        name = "req", 
        methods = {HttpMethod.POST},
        authLevel = AuthorizationLevel.FUNCTION)
        HttpRequestMessage<SemanticSearchRequest> request,
    @SemanticSearch(name = "search", searchConnectionName = "AISearchEndpoint", collection = "openai-index", query = "{prompt}", chatModel = "%CHAT_MODEL_DEPLOYMENT_NAME%", embeddingsModel = "%EMBEDDING_MODEL_DEPLOYMENT_NAME%", isReasoningModel = false, aiConnectionName = "AzureOpenAI" ) String semanticSearchContext,
    final ExecutionContext context) {
        String response = new JSONObject(semanticSearchContext).getString("Response");
        return request.createResponseBuilder(HttpStatus.OK)
        .header("Content-Type", "application/json")
        .body(response)
        .build();        
}
public class SemanticSearchRequest {
    public String prompt;
    public String getPrompt() {
        return prompt;
    }
    public void setPrompt(String prompt) {
        this.prompt = prompt;
    }        
}

この例では、ファイルに対してセマンティック検索を実行する方法を示します。

const semanticSearchInput = input.generic({
    type: "semanticSearch",
    searchConnectionName: "AISearchEndpoint",
    collection: "openai-index",
    query: "{prompt}",
    chatModel: "%CHAT_MODEL_DEPLOYMENT_NAME%",
    embeddingsModel: "%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
    aiConnectionName: 'AzureOpenAI',
});

app.http('PromptFile', {
    methods: ['POST'],
    authLevel: 'function',
    extraInputs: [semanticSearchInput],
    handler: async (_request, context) => {
        var responseBody = context.extraInputs.get(semanticSearchInput)

        return { status: 200, body: responseBody.Response.trim() }
    }
});
const semanticSearchInput = input.generic({
    type: "semanticSearch",
    searchConnectionName: "AISearchEndpoint",
    collection: "openai-index",
    query: "{prompt}",
    chatModel: "%CHAT_MODEL_DEPLOYMENT_NAME%",
    aiConnectionName: 'AzureOpenAI',
    embeddingsModel: "%EMBEDDING_MODEL_DEPLOYMENT_NAME%"
});

app.http('PromptFile', {
    methods: ['POST'],
    authLevel: 'function',
    extraInputs: [semanticSearchInput],
    handler: async (_request, context) => {
        var responseBody: any = context.extraInputs.get(semanticSearchInput)

        return { status: 200, body: responseBody.Response.trim() }
    }
});

この例では、ファイルに対してセマンティック検索を実行する方法を示します。

ファイルを求める function.json ファイルを次に示します。

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "name": "SemanticSearchInput",
      "type": "semanticSearch",
      "direction": "in",
      "searchConnectionName": "AISearchEndpoint",
      "collection": "openai-index",
      "query": "{prompt}",
      "chatModel": "%CHAT_MODEL_DEPLOYMENT_NAME%",
      "embeddingsModel": "%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
      "aiConnectionName": "AzureOpenAI"
    }
  ]
}

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

using namespace System.Net

param($Request, $TriggerMetadata, $SemanticSearchInput)

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
        StatusCode = [HttpStatusCode]::OK
        Body       = $SemanticSearchInput.Response
    })

この例では、ファイルに対してセマンティック検索を実行する方法を示します。

@app.function_name("PromptFile")
@app.route(methods=["POST"])
@app.semantic_search_input(
    arg_name="result",
    search_connection_name="AISearchEndpoint",
    collection="openai-index",
    query="{prompt}",
    embeddings_model="%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
    ai_connection_name="AzureOpenAI",
    chat_model="%CHAT_MODEL_DEPLOYMENT_NAME%",
)
def prompt_file(req: func.HttpRequest, result: str) -> func.HttpResponse:
    result_json = json.loads(result)
    response_json = {
        "content": result_json.get("Response"),
        "content_type": "text/plain",
    }
    return func.HttpResponse(
        json.dumps(response_json), status_code=200, mimetype="application/json"
    )

属性

SemanticSearchInput属性を適用して、次のパラメーターをサポートするセマンティック検索入力バインドを定義します。

パラメーター 説明
SearchConnectionName 接続文字列の値を含むアプリ設定または環境変数の名前。 このプロパティは、バインド式をサポートしています。
コレクション 検索するコレクション、テーブル、またはインデックスの名前。 このプロパティは、バインド式をサポートしています。
クエリ 検索に使用するセマンティック クエリ テキスト。 このプロパティは、バインド式をサポートしています。
EmbeddingsModel オプション。 埋め込み用に使用するモデルの ID。 既定値は text-embedding-3-small です。 このプロパティは、バインド式をサポートしています。
ChatModel オプション。 チャット応答用に呼び出す大きな言語モデルの名前を取得または設定します。 既定値は gpt-3.5-turbo です。 このプロパティは、バインド式をサポートしています。
AIConnectionName オプション。 AI サービス接続設定の構成セクションの名前を取得または設定します。 Azure OpenAI の場合: 指定した場合は、この構成セクションで "Endpoint" と "Key" の値を探します。 指定されていない場合、またはセクションが存在しない場合は、環境変数 (AZURE_OPENAI_ENDPOINTとAZURE_OPENAI_KEY) にフォールバックします。 ユーザー割り当てマネージド ID 認証の場合、このプロパティは必須です。 OpenAI サービス (Azure 以外) の場合は、OPENAI_API_KEY環境変数を設定します。
SystemPrompt オプション。 大規模な言語モデルのプロンプトに使用するシステム プロンプトを取得または設定します。 システム プロンプトには、 Queryの結果としてフェッチされるナレッジが追加されます。 結合されたプロンプトが OpenAI チャット API に送信されます。 このプロパティは、バインド式をサポートしています。
MaxKnowledgeCount オプションSystemPromptに挿入するナレッジ項目の数を取得または設定します。
IsReasoningModel オプション。 チャット完了モデルが推論モデルであるかどうかを示す値を取得または設定します。 このオプションは試験段階であり、すべてのモデルが予期されるプロパティにパリティを持ち、既定値が false になるまで推論モデルに関連付けられます。

注釈

SemanticSearchInput注釈を使用すると、次のパラメーターをサポートするセマンティック検索入力バインドを定義できます。

要素 説明
名前 入力バインドの名前を取得または設定します。
searchConnectionName 接続文字列の値を含むアプリ設定または環境変数の名前。 このプロパティは、バインド式をサポートしています。
コレクション 検索するコレクション、テーブル、またはインデックスの名前。 このプロパティは、バインド式をサポートしています。
クエリ 検索に使用するセマンティック クエリ テキスト。 このプロパティは、バインド式をサポートしています。
embeddingsModel オプション。 埋め込み用に使用するモデルの ID。 既定値は text-embedding-3-small です。 このプロパティは、バインド式をサポートしています。
chatModel オプション。 チャット応答用に呼び出す大きな言語モデルの名前を取得または設定します。 既定値は gpt-3.5-turbo です。 このプロパティは、バインド式をサポートしています。
aiConnectionName オプション。 AI サービス接続設定の構成セクションの名前を取得または設定します。 Azure OpenAI の場合: 指定した場合は、この構成セクションで "Endpoint" と "Key" の値を探します。 指定されていない場合、またはセクションが存在しない場合は、環境変数 (AZURE_OPENAI_ENDPOINTとAZURE_OPENAI_KEY) にフォールバックします。 ユーザー割り当てマネージド ID 認証の場合、このプロパティは必須です。 OpenAI サービス (Azure 以外) の場合は、OPENAI_API_KEY環境変数を設定します。
systemPrompt オプション。 大規模な言語モデルのプロンプトに使用するシステム プロンプトを取得または設定します。 システム プロンプトには、 Queryの結果としてフェッチされるナレッジが追加されます。 結合されたプロンプトが OpenAI チャット API に送信されます。 このプロパティは、バインド式をサポートしています。
maxKnowledgeCount オプションSystemPromptに挿入するナレッジ項目の数を取得または設定します。
isReasoningModel オプション。 チャット完了モデルが推論モデルであるかどうかを示す値を取得または設定します。 このオプションは試験段階であり、すべてのモデルが予期されるプロパティにパリティを持ち、既定値が false になるまで推論モデルに関連付けられます。

デコレータ

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

パラメーター 説明
arg_name バインド パラメーターを表す変数の名前。
search_connection_name 接続文字列の値を含むアプリ設定または環境変数の名前。 このプロパティは、バインド式をサポートしています。
コレクション 検索するコレクション、テーブル、またはインデックスの名前。 このプロパティは、バインド式をサポートしています。
クエリ 検索に使用するセマンティック クエリ テキスト。 このプロパティは、バインド式をサポートしています。
embeddings_model オプション。 埋め込み用に使用するモデルの ID。 既定値は text-embedding-3-small です。 このプロパティは、バインド式をサポートしています。
chat_model オプション。 チャット応答用に呼び出す大きな言語モデルの名前を取得または設定します。 既定値は gpt-3.5-turbo です。 このプロパティは、バインド式をサポートしています。
ai_connection_name オプション。 AI サービス接続設定の構成セクションの名前を取得または設定します。 Azure OpenAI の場合: 指定した場合は、この構成セクションで "Endpoint" と "Key" の値を探します。 指定されていない場合、またはセクションが存在しない場合は、環境変数 (AZURE_OPENAI_ENDPOINTとAZURE_OPENAI_KEY) にフォールバックします。 ユーザー割り当てマネージド ID 認証の場合、このプロパティは必須です。 OpenAI サービス (Azure 以外) の場合は、OPENAI_API_KEY環境変数を設定します。
system_prompt オプション。 大規模な言語モデルのプロンプトに使用するシステム プロンプトを取得または設定します。 システム プロンプトには、 Queryの結果としてフェッチされるナレッジが追加されます。 結合されたプロンプトが OpenAI チャット API に送信されます。 このプロパティは、バインド式をサポートしています。
max_knowledge_count オプションSystemPromptに挿入するナレッジ項目の数を取得または設定します。
is_reasoning _model オプション。 チャット完了モデルが推論モデルであるかどうかを示す値を取得または設定します。 このオプションは試験段階であり、すべてのモデルが予期されるプロパティにパリティを持ち、既定値が false になるまで推論モデルに関連付けられます。

コンフィギュレーション

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

プロパティ 説明
タイプ semanticSearchである必要があります。
方向 inである必要があります。
名前 入力バインドの名前。
searchConnectionName 接続文字列値を含むアプリ設定または環境変数の名前を取得または設定します。 このプロパティは、バインド式をサポートしています。
コレクション 検索するコレクション、テーブル、またはインデックスの名前。 このプロパティは、バインド式をサポートしています。
クエリ 検索に使用するセマンティック クエリ テキスト。 このプロパティは、バインド式をサポートしています。
embeddingsModel オプション。 埋め込み用に使用するモデルの ID。 既定値は text-embedding-3-small です。 このプロパティは、バインド式をサポートしています。
chatModel オプション。 チャット応答用に呼び出す大きな言語モデルの名前を取得または設定します。 既定値は gpt-3.5-turbo です。 このプロパティは、バインド式をサポートしています。
aiConnectionName オプション。 AI サービス接続設定の構成セクションの名前を取得または設定します。 Azure OpenAI の場合: 指定した場合は、この構成セクションで "Endpoint" と "Key" の値を探します。 指定されていない場合、またはセクションが存在しない場合は、環境変数 (AZURE_OPENAI_ENDPOINTとAZURE_OPENAI_KEY) にフォールバックします。 ユーザー割り当てマネージド ID 認証の場合、このプロパティは必須です。 OpenAI サービス (Azure 以外) の場合は、OPENAI_API_KEY環境変数を設定します。
systemPrompt オプション。 大規模な言語モデルのプロンプトに使用するシステム プロンプトを取得または設定します。 システム プロンプトには、 Queryの結果としてフェッチされるナレッジが追加されます。 結合されたプロンプトが OpenAI チャット API に送信されます。 このプロパティは、バインド式をサポートしています。
maxKnowledgeCount オプションSystemPromptに挿入するナレッジ項目の数を取得または設定します。
isReasoningModel オプション。 チャット完了モデルが推論モデルであるかどうかを示す値を取得または設定します。 このオプションは試験段階であり、すべてのモデルが予期されるプロパティにパリティを持ち、既定値が false になるまで推論モデルに関連付けられます。

コンフィギュレーション

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

プロパティ 説明
searchConnectionName 接続文字列の値を含むアプリ設定または環境変数の名前。 このプロパティは、バインド式をサポートしています。
コレクション 検索するコレクション、テーブル、またはインデックスの名前。 このプロパティは、バインド式をサポートしています。
クエリ 検索に使用するセマンティック クエリ テキスト。 このプロパティは、バインド式をサポートしています。
embeddingsModel オプション。 埋め込み用に使用するモデルの ID。 既定値は text-embedding-3-small です。 このプロパティは、バインド式をサポートしています。
chatModel オプション。 チャット応答用に呼び出す大きな言語モデルの名前を取得または設定します。 既定値は gpt-3.5-turbo です。 このプロパティは、バインド式をサポートしています。
aiConnectionName オプション。 AI サービス接続設定の構成セクションの名前を取得または設定します。 Azure OpenAI の場合: 指定した場合は、この構成セクションで "Endpoint" と "Key" の値を探します。 指定されていない場合、またはセクションが存在しない場合は、環境変数 (AZURE_OPENAI_ENDPOINTとAZURE_OPENAI_KEY) にフォールバックします。 ユーザー割り当てマネージド ID 認証の場合、このプロパティは必須です。 OpenAI サービス (Azure 以外) の場合は、OPENAI_API_KEY環境変数を設定します。
systemPrompt オプション。 大規模な言語モデルのプロンプトに使用するシステム プロンプトを取得または設定します。 システム プロンプトには、 Queryの結果としてフェッチされるナレッジが追加されます。 結合されたプロンプトが OpenAI チャット API に送信されます。 このプロパティは、バインド式をサポートしています。
maxKnowledgeCount オプションSystemPromptに挿入するナレッジ項目の数を取得または設定します。
isReasoningModel オプション。 チャット完了モデルが推論モデルであるかどうかを示す値を取得または設定します。 このオプションは試験段階であり、すべてのモデルが予期されるプロパティにパリティを持ち、既定値が false になるまで推論モデルに関連付けられます。

使用方法

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

接続

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

  • AIConnectionName bindingプロパティ(OpenAI Azure推奨)を使いましょう。
  • OpenAI Azureのアプリ設定でAZURE_OPENAI_ENDPOINTAZURE_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>__credentialmanagedidentity に設定する必要があります。 このプロパティは、アプリケーションに割り当てられたユーザー割り当て ID に相当するクライアント ID を受け取ります。 リソース ID とクライアント ID の両方を指定することは無効です。 このプロパティを指定しない場合は、システムが割り当てたアイデンティティが使われます。 このプロパティは、 を設定しないとき、credentialで異なる方法で使用されます。
<CONNECTION_NAME_PREFIX>__credential 接続のaccess トークンを取得する方法を定義します。 マネージド ID 認証には managedidentity を使用します。 この値は、ホスティング環境でマネージド ID が使用できる場合にのみ有効です。
<CONNECTION_NAME_PREFIX>__managedIdentityResourceId credentialmanagedidentityに設定されている場合、このプロパティでトークンを取得する際に使用するリソース識別子を指定します。 プロパティは、ユーザー定義マネージド 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": "aaaaaaaa-bbbb-cccc-1111-222222222222"
}

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

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

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