Abfrageeingabebindung des Azure OpenAI-Assistenten für Azure Functions

Wichtig

Die Azure OpenAI-Erweiterung für Azure Functions befindet sich derzeit in der Vorschau.

Mit der Abfrageeingabebindung des Azure OpenAI-Assistenten können Sie Assistenten-API-Abfragen in Ihre Codeausführungen integrieren.

Informationen zu Einrichtungs- und Konfigurationsdetails der Azure OpenAI-Erweiterung finden Sie unter Azure OpenAI-Erweiterungen für Azure Functions. Weitere Informationen zu Azure OpenAI-Assistenten finden Sie unter API für Azure OpenAI-Assistenten.

Hinweis

Referenzen und Beispiele werden nur für das Node.js v4-Modell bereitgestellt.

Hinweis

Referenzen und Beispiele werden nur für das Python v2-Modell bereitgestellt.

Hinweis

Während beide C#-Prozessmodelle unterstützt werden, werden nur Isolierte Arbeitsmodellbeispiele bereitgestellt.

Beispiel

Go-Support ist derzeit nicht für diese Bindung verfügbar.

In diesem Beispiel wird der Erstellungsprozess veranschaulicht, bei dem die HTTP GET-Funktion den Unterhaltungsverlauf des Assistenten-Chatbots abfragt. Die Antwort auf den Prompt wird in der HTTP-Antwort zurückgegeben.

/// <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);
}

In diesem Beispiel wird der Erstellungsprozess veranschaulicht, bei dem die HTTP GET-Funktion den Unterhaltungsverlauf des Assistenten-Chatbots abfragt. Die Antwort auf den Prompt wird in der HTTP-Antwort zurückgegeben.

/*
 * 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();
}

In diesem Beispiel wird der Erstellungsprozess veranschaulicht, bei dem die HTTP GET-Funktion den Unterhaltungsverlauf des Assistenten-Chatbots abfragt. Die Antwort auf den Prompt wird in der HTTP-Antwort zurückgegeben.

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 }
    }
})

In diesem Beispiel wird der Erstellungsprozess veranschaulicht, bei dem die HTTP GET-Funktion den Unterhaltungsverlauf des Assistenten-Chatbots abfragt. Die Antwort auf den Prompt wird in der HTTP-Antwort zurückgegeben.

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 }
    }
})

In diesem Beispiel wird der Erstellungsprozess veranschaulicht, bei dem die HTTP GET-Funktion den Unterhaltungsverlauf des Assistenten-Chatbots abfragt. Die Antwort auf den Prompt wird in der HTTP-Antwort zurückgegeben.

Dies ist die function.json Datei für "Chatstatus abrufen":

{
  "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"
    }
  ]
}

Weitere Informationen zu den Dateieigenschaften von function.json finden Sie im Abschnitt Konfiguration.

using namespace System.Net

param($Request, $TriggerMetadata, $State)

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

In diesem Beispiel wird der Erstellungsprozess veranschaulicht, bei dem die HTTP GET-Funktion den Unterhaltungsverlauf des Assistenten-Chatbots abfragt. Die Antwort auf den Prompt wird in der HTTP-Antwort zurückgegeben.

@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")

Attribute

Wenden Sie das Attribut AssistantQuery an, um eine Abfrageeingabebindung für den Assistenten zu definieren, die diese Parameter unterstützt:

Parameter Beschreibung
Id Ruft die ID des Assistenten ab, der abgefragt werden soll.
ZeitstempelUtc Optional. Ruft den Zeitstempel der frühesten Nachricht im Chatverlauf ab, die abgerufen werden soll, oder legt diesen Zeitstempel fest. Der Zeitstempel muss im ISO 8601-Format vorliegen, z. B. 2023-08-01T00:00:00Z.

Anmerkungen

Mit der Anmerkung assistantQuery können Sie eine Abfrageeingabebindung für den Assistenten definieren, die diese Parameter unterstützt:

Element Beschreibung
Name Ruft den Namen der Eingabebindung ab oder legt ihn fest.
id Ruft die ID des Assistenten ab, der abgefragt werden soll.
ZeitstempelUtc Optional. Ruft den Zeitstempel der frühesten Nachricht im Chatverlauf ab, die abgerufen werden soll, oder legt diesen Zeitstempel fest. Der Zeitstempel muss im ISO 8601-Format vorliegen, z. B. 2023-08-01T00:00:00Z.

Decorator-Elemente

Definieren Sie während der Vorschau die Eingabebindung als generic_input_binding-Bindung vom Typ assistantQuery, die diese Parameter unterstützt:

Parameter Beschreibung
arg_name Der Name der Variablen, die den Bindungsparameter darstellt.
id Ruft die ID des Assistenten ab, der abgefragt werden soll.
time_stamp_utc Optional. Ruft den Zeitstempel der frühesten Nachricht im Chatverlauf ab, die abgerufen werden soll, oder legt diesen Zeitstempel fest. Der Zeitstempel muss im ISO 8601-Format vorliegen, z. B. 2023-08-01T00:00:00Z.

Konfiguration

Die Bindung unterstützt diese Konfigurationseigenschaften, die Sie in der Datei „function.json“ festlegen.

Eigenschaft Beschreibung
Typ Muss assistantQuerylauten.
Richtung Muss inlauten.
Name Der Name der Eingabebindung.
id Ruft die ID des Assistenten ab, der abgefragt werden soll.
ZeitstempelUtc Optional. Ruft den Zeitstempel der frühesten Nachricht im Chatverlauf ab, die abgerufen werden soll, oder legt diesen Zeitstempel fest. Der Zeitstempel muss im ISO 8601-Format vorliegen, z. B. 2023-08-01T00:00:00Z.

Konfiguration

Die Bindung unterstützt diese Eigenschaften, die in Ihrem Code definiert sind:

Eigenschaft Beschreibung
id Ruft die ID des Assistenten ab, der abgefragt werden soll.
ZeitstempelUtc Optional. Ruft den Zeitstempel der frühesten Nachricht im Chatverlauf ab, die abgerufen werden soll, oder legt diesen Zeitstempel fest. Der Zeitstempel muss im ISO 8601-Format vorliegen, z. B. 2023-08-01T00:00:00Z.

Verbrauch

Vollständige Beispiele finden Sie im Abschnitt Beispiele.

Verbindungen

Um die Azure OpenAI-Bindungserweiterung zu verwenden, muss man eine Verbindung zu einer OpenAI-Modelldefinition angeben. Stellen Sie die OpenAI-Modellverbindung in Ihren Bindings mit einem dieser Ansätze ein:

  • Verwenden Sie die AIConnectionName Binding-Eigenschaft (bevorzugt für Azure OpenAI).
  • Setze AZURE_OPENAI_ENDPOINT und AZURE_OPENAI_KEY in den App-Einstellungen (für Azure OpenAI).
  • Setze nur Open_API_Key in den App-Einstellungen (für https://api.openai.com).

Die Art und Weise, wie Sie die Verbindung einstellen, hängt sowohl von der Modell-API als auch von der Authentifizierungsmethode ab, wie in der folgenden Tabelle angegeben:

Authentifizierungs-/Modell-API Azure OpenAI OpenAI (https://api.openai.com)
Managed Identity-Verbindung AIConnectionName Nicht unterstützt
Key Vault-Referenz AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key
App-Konfigurationsreferenz AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key
Gemeinsames Geheimnis AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key

Nutzen Sie verwaltete Identitätsbasierte Verbindungen und die Immobilie AIConnectionName .

Wenn Sie verwenden AIConnectionName, hängt der Wert dieser Eigenschaftseinstellung vom Verbindungstyp ab:

  • Managed Identity-Verbindung: Die AIConnectionName Eigenschaft wird <CONNECTION_NAME_PREFIX> von einer Gruppe von Settings geteilt, die zusammen eine identitätsbasierte Verbindung zu Azure OpenAI definieren. Weitere Informationen finden Sie unter Identitätsverbindungen definieren.
  • Key Vault-Referenz: Die AIConnectionName Property-Einstellung liefert eine Azure Key Vault-Referenz auf den Standort, an dem der API-Schlüssel zentral verwaltet wird. Weitere Informationen finden Sie unter Define Key Vault connections.
  • App Configuration Reference: Die AIConnectionName Eigenschaftseinstellung liefert eine Azure App Configuration-Referenz, die einen API-Schlüssel oder eine Key Vault-Referenz zurückgibt. Weitere Informationen finden Sie unter Azure App Configuration im Artikel über Verbindungen.
  • API-Schlüssel: Die AIConnectionName Eigenschaftseinstellung wird direkt auf App-Einstellungen umgesetzt, die den Endpunkt und den Schlüssel enthalten. Da gemeinsame Schlüssel kompromittiert werden können, sollten Sie wenn möglich verwaltete Identitätsverbindungen verwenden. Weitere Informationen finden Sie unter Zusammenhänge definieren.

Um mehr über Bindungsverbindungen zu erfahren, siehe Verbindungen verwalten in Azure Functions.

Die OpenAI-Bindungen enthalten eine AIConnectionName Eigenschaft, mit der Sie die <ConnectionNamePrefix> für die Gruppe von App-Einstellungen festlegen können, die die Verbindung zu Azure OpenAI definieren:

Einstellungsname Beschreibung
<CONNECTION_NAME_PREFIX>__endpoint Setzt das URI-Endpunkt des Azure OpenAI-Dienstes. Diese Einstellung ist immer erforderlich.
<CONNECTION_NAME_PREFIX>__clientId Legt die bestimmte vom Benutzer zugewiesene Identität fest, die beim Abrufen eines Zugriffstokens verwendet werden soll. Erfordert, dass <CONNECTION_NAME_PREFIX>__credential auf managedidentity festgelegt wird. Die Eigenschaft akzeptiert eine Client-ID, die einer vom Benutzer zugewiesenen Identität entspricht, die der Anwendung zugeordnet ist. Es ist nicht möglich, sowohl eine Ressourcen-ID als auch eine Client-ID anzugeben. Wenn Sie diese Eigenschaft nicht spezifizieren, wird die systemzugewiesene Identität verwendet. Diese Eigenschaft wird in Szenarien für die lokale Entwicklung anders verwendet, in denen credential nicht festgelegt werden darf.
<CONNECTION_NAME_PREFIX>__credential Definiert, wie ein access-Token für die Verbindung abgerufen wird. Verwenden Sie managedidentity für die Authentifizierung der verwalteten Identität. Dieser Wert ist nur gültig, wenn eine verwaltete Identität in der Hostingumgebung verfügbar ist.
<CONNECTION_NAME_PREFIX>__managedIdentityResourceId Wenn credential auf gesetzt ist managedidentity, setzen Sie diese Eigenschaft so, dass sie die Ressourcen-Identifikator angibt, die beim Erlangen eines Tokens verwendet werden soll. Die Eigenschaft akzeptiert einen Ressourcenbezeichner, der der Ressourcen-ID der benutzerdefinierten verwalteten Identität entspricht. Es ist nicht möglich, sowohl eine Ressourcen-ID als auch eine Client-ID anzugeben. Wenn Sie keines von beiden angeben, wird die systemzugewiesene Identität verwendet. Diese Eigenschaft wird in Szenarien für die lokale Entwicklung anders verwendet, in denen credential nicht festgelegt werden darf.
<CONNECTION_NAME_PREFIX>__key Setzt den gemeinsamen geheimen Schlüssel, der für den Zugriff auf den Endpunkt des Azure OpenAI-Dienstes erforderlich ist, mittels schlüsselbasierter Authentifizierung. Als Sicherheitsbest-Practice sollten Sie immer Microsoft Entra ID mit verwalteten Identitäten zur Authentifizierung verwenden.

Betrachten Sie diese Managed Identity Connection-Einstellungen, wenn Sie die Eigenschaft AIConnectionName auf myAzureOpenAIsetzen:

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

Zur Laufzeit interpretiert der Host diese Einstellungen als eine einzige myAzureOpenAI Einstellung:

"myAzureOpenAI":
{
    "endpoint": "https://contoso.openai.azure.com/",
    "credential": "managedidentity",
    "clientId": "aaaaaaaa-bbbb-cccc-1111-222222222222"
}

Wenn Sie verwaltete Identitäten verwenden, fügen Sie Ihre Identität unbedingt der Cognitive Services OpenAI User Rolle hinzu.

Beim lokalen Ausführen fügen Sie diese Einstellungen der local.settings.json Projektdatei hinzu. Weitere Informationen finden Sie unter "Lokale Entwicklung mit identitätsbasierten Verbindungen".

Weitere Informationen finden Sie unter Verwenden von Anwendungseinstellungen.