L'assistente OpenAI di Azure crea l'associazione di output per Funzioni di Azure

Importante

L'estensione OpenAI di Azure per Funzioni di Azure è attualmente in anteprima.

L'assistente Azure OpenAI crea associazione di output consente di creare un nuovo chatbot assistente dall'esecuzione del codice della funzione.

Per informazioni sull'installazione e la configurazione dell'estensione OpenAI di Azure, vedere Estensioni OpenAI di Azure per Funzioni di Azure. Per altre informazioni sugli assistenti OpenAI di Azure, vedere API Assistenti OpenAI di Azure.

Nota

I riferimenti e gli esempi vengono forniti solo per il modello Node.js v4.

Nota

I riferimenti e gli esempi vengono forniti solo per il modello Python v2.

Nota

Anche se sono supportati entrambi i modelli di processo C#, vengono forniti solo esempi di modelli di lavoro isolati.

Esempio

Il supporto Go non è attualmente disponibile per questo binding.

In questo esempio viene illustrato il processo di creazione, in cui la funzione HTTP PUT che crea un nuovo chatbot assistente con l'ID specificato. La risposta alla richiesta viene restituita nella risposta HTTP.

/// <summary>
/// HTTP PUT function that creates a new assistant chat bot with the specified ID.
/// </summary>
[Function(nameof(CreateAssistant))]
public static async Task<CreateChatBotOutput> CreateAssistant(
    [HttpTrigger(AuthorizationLevel.Function, "put", Route = "assistants/{assistantId}")] HttpRequestData req,
    string assistantId)
{
    string instructions =
       """
        Don't make assumptions about what values to plug into functions.
        Ask for clarification if a user request is ambiguous.
        """;

    using StreamReader reader = new(req.Body);

    string request = await reader.ReadToEndAsync();


    return new CreateChatBotOutput
    {
        HttpResponse = new ObjectResult(new { assistantId }) { StatusCode = 201 },
        ChatBotCreateRequest = new AssistantCreateRequest(assistantId, instructions)
        {
            ChatStorageConnectionSetting = DefaultChatStorageConnectionSetting,
            CollectionName = DefaultCollectionName,
        },
    };
}

public class CreateChatBotOutput
{
    [AssistantCreateOutput()]
    public AssistantCreateRequest? ChatBotCreateRequest { get; set; }

    [HttpResult]
    public IActionResult? HttpResponse { get; set; }
}

In questo esempio viene illustrato il processo di creazione, in cui la funzione HTTP PUT che crea un nuovo chatbot assistente con l'ID specificato. La risposta alla richiesta viene restituita nella risposta HTTP.

/**
 * The default storage account setting for the table storage account.
 * This constant is used to specify the connection string for the table storage
 * account
 * where chat data will be stored.
 */
final String DEFAULT_CHATSTORAGE = "AzureWebJobsStorage";

/**
 * The default collection name for the table storage account.
 * This constant is used to specify the collection name for the table storage
 * account
 * where chat data will be stored.
 */
final String DEFAULT_COLLECTION = "ChatState";

/*
 * HTTP PUT function that creates a new assistant chat bot with the specified ID.
 */
@FunctionName("CreateAssistant")
public HttpResponseMessage createAssistant(
    @HttpTrigger(
        name = "req", 
        methods = {HttpMethod.PUT}, 
        authLevel = AuthorizationLevel.FUNCTION, 
        route = "assistants/{assistantId}") 
        HttpRequestMessage<Optional<String>> request,
    @BindingName("assistantId") String assistantId,
    @AssistantCreate(name = "AssistantCreate") OutputBinding<AssistantCreateRequest> message,
    final ExecutionContext context) {
        context.getLogger().info("Java HTTP trigger processed a request.");
        
        String instructions = "Don't make assumptions about what values to plug into functions.\n" +
                "Ask for clarification if a user request is ambiguous.";

        AssistantCreateRequest assistantCreateRequest = new AssistantCreateRequest(assistantId, instructions);
        assistantCreateRequest.setChatStorageConnectionSetting(DEFAULT_CHATSTORAGE);
        assistantCreateRequest.setCollectionName(DEFAULT_COLLECTION);

        message.setValue(assistantCreateRequest);
        JSONObject response = new JSONObject();
        response.put("assistantId", assistantId);
        
        return request.createResponseBuilder(HttpStatus.CREATED)
            .header("Content-Type", "application/json")
            .body(response.toString())
            .build();    
}

In questo esempio viene illustrato il processo di creazione, in cui la funzione HTTP PUT che crea un nuovo chatbot assistente con l'ID specificato. La risposta alla richiesta viene restituita nella risposta HTTP.

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

const CHAT_STORAGE_CONNECTION_SETTING = "AzureWebJobsStorage";
const COLLECTION_NAME = "ChatState";

const chatBotCreateOutput = output.generic({
    type: 'assistantCreate'
})
app.http('CreateAssistant', {
    methods: ['PUT'],
    route: 'assistants/{assistantId}',
    authLevel: 'function',
    extraOutputs: [chatBotCreateOutput],
    handler: async (request, context) => {
        const assistantId = request.params.assistantId
        const instructions =
            `
            Don't make assumptions about what values to plug into functions.
            Ask for clarification if a user request is ambiguous.
            `
        const createRequest = {
            id: assistantId,
            instructions: instructions,
            chatStorageConnectionSetting: CHAT_STORAGE_CONNECTION_SETTING,
            collectionName: COLLECTION_NAME
        }
        context.extraOutputs.set(chatBotCreateOutput, createRequest)
        return { status: 202, jsonBody: { assistantId: assistantId } }
    }
})

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

const CHAT_STORAGE_CONNECTION_SETTING = "AzureWebJobsStorage";
const COLLECTION_NAME = "ChatState";

const chatBotCreateOutput = output.generic({
    type: 'assistantCreate'
})
app.http('CreateAssistant', {
    methods: ['PUT'],
    route: 'assistants/{assistantId}',
    authLevel: 'function',
    extraOutputs: [chatBotCreateOutput],
    handler: async (request: HttpRequest, context: InvocationContext) => {
        const assistantId = request.params.assistantId
        const instructions =
            `
            Don't make assumptions about what values to plug into functions.
            Ask for clarification if a user request is ambiguous.
            `
        const createRequest = {
            id: assistantId,
            instructions: instructions,
            chatStorageConnectionSetting: CHAT_STORAGE_CONNECTION_SETTING,
            collectionName: COLLECTION_NAME
        }
        context.extraOutputs.set(chatBotCreateOutput, createRequest)
        return { status: 202, jsonBody: { assistantId: assistantId } }
    }
})

In questo esempio viene illustrato il processo di creazione, in cui la funzione HTTP PUT che crea un nuovo chatbot assistente con l'ID specificato. La risposta alla richiesta viene restituita nella risposta HTTP.

Ecco il file function.json per l'Assistente creazione:

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "route": "assistants/{assistantId}",
      "methods": [
        "put"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "assistantCreate",
      "direction": "out",
      "dataType": "string",
      "name": "Requests"
    }
  ]
}

Per altre informazioni sulle proprietà dei file function.json, vedere la sezione configurazione.

{{Deriva dal commento del codice di esempio}}

using namespace System.Net

param($Request, $TriggerMetadata)

$assistantId = $Request.params.assistantId

$instructions = "Don't make assumptions about what values to plug into functions."
$instructions += "\nAsk for clarification if a user request is ambiguous."

$create_request = @{
    "id" = $assistantId
    "instructions" = $instructions
    "chatStorageConnectionSetting" = "AzureWebJobsStorage"
    "collectionName" = "ChatState"
}

Push-OutputBinding -Name Requests -Value (ConvertTo-Json $create_request)

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

In questo esempio viene illustrato il processo di creazione, in cui la funzione HTTP PUT che crea un nuovo chatbot assistente con l'ID specificato. La risposta alla richiesta viene restituita nella risposta HTTP.

DEFAULT_CHAT_STORAGE_SETTING = "AzureWebJobsStorage"
DEFAULT_CHAT_COLLECTION_NAME = "ChatState"


@apis.function_name("CreateAssistant")
@apis.route(route="assistants/{assistantId}", methods=["PUT"])
@apis.assistant_create_output(arg_name="requests")
def create_assistant(
    req: func.HttpRequest, requests: func.Out[str]
) -> func.HttpResponse:
    assistantId = req.route_params.get("assistantId")
    instructions = """
            Don't make assumptions about what values to plug into functions.
            Ask for clarification if a user request is ambiguous.
            """
    create_request = {
        "id": assistantId,
        "instructions": instructions,
        "chatStorageConnectionSetting": DEFAULT_CHAT_STORAGE_SETTING,
        "collectionName": DEFAULT_CHAT_COLLECTION_NAME,
    }
    requests.set(json.dumps(create_request))
    response_json = {"assistantId": assistantId}
    return func.HttpResponse(
        json.dumps(response_json), status_code=202, mimetype="application/json"
    )

Attributi

Applicare l'attributo CreateAssistant per definire un'associazione di output creata dall'assistente, che supporta questi parametri:

Parametro	Descrizione
id	Identificatore dell'assistente da creare.
Istruzioni	Facoltativo. Le istruzioni fornite per l'assistente da seguire.
ChatStorageConnectionSetting	Facoltativo. Nome della sezione di configurazione per le impostazioni della tabella per l'archiviazione chat. Il valore predefinito è AzureWebJobsStorage.
CollectionName	Facoltativo. Nome della raccolta di tabelle per l'archiviazione chat. Il valore predefinito è ChatState.

Annotazioni

L'annotazione CreateAssistant consente di definire un'associazione di output creata dall'assistente, che supporta questi parametri:

Elemento	Descrizione
nome	Ottiene o imposta il nome dell'associazione di output.
ID	Identificatore dell'assistente da creare.
istruzioni	Facoltativo. Le istruzioni fornite per l'assistente da seguire.
chatStorageConnectionSetting	Facoltativo. Nome della sezione di configurazione per le impostazioni della tabella per l'archiviazione chat. Il valore predefinito è AzureWebJobsStorage.
collectionName	Facoltativo. Nome della raccolta di tabelle per l'archiviazione chat. Il valore predefinito è ChatState.

Elementi Decorator

Durante l'anteprima, definire l'associazione di output come associazione generic_output_binding di tipo createAssistant, che supporta questi parametri:

Parametro	Descrizione
arg_name	Nome della variabile che rappresenta il parametro di associazione.
ID	Identificatore dell'assistente da creare.
istruzioni	Facoltativo. Le istruzioni fornite per l'assistente da seguire.
chat_storage_connection_setting	Facoltativo. Nome della sezione di configurazione per le impostazioni della tabella per l'archiviazione chat. Il valore predefinito è AzureWebJobsStorage.
collection_name	Facoltativo. Nome della raccolta di tabelle per l'archiviazione chat. Il valore predefinito è ChatState.

Impostazione

L'associazione supporta queste proprietà di configurazione impostate nel file function.json.

Proprietà	Descrizione
tipo	Deve essere CreateAssistant.
direzione	Deve essere out.
nome	Nome dell'associazione di output.
ID	Identificatore dell'assistente da creare.
istruzioni	Facoltativo. Le istruzioni fornite per l'assistente da seguire.
chatStorageConnectionSetting	Facoltativo. Nome della sezione di configurazione per le impostazioni della tabella per l'archiviazione chat. Il valore predefinito è AzureWebJobsStorage.
collectionName	Facoltativo. Nome della raccolta di tabelle per l'archiviazione chat. Il valore predefinito è ChatState.

Impostazione

Il binding supporta queste proprietà, definite nel codice:

Proprietà	Descrizione
ID	Identificatore dell'assistente da creare.
istruzioni	Facoltativo. Le istruzioni fornite per l'assistente da seguire.
chatStorageConnectionSetting	Facoltativo. Nome della sezione di configurazione per le impostazioni della tabella per l'archiviazione chat. Il valore predefinito è AzureWebJobsStorage.
collectionName	Facoltativo. Nome della raccolta di tabelle per l'archiviazione chat. Il valore predefinito è ChatState.

Utilizzo

Per esempi completi, vedere la sezione di esempio.

Connections

Per utilizzare l'estensione di binding Azure OpenAI, è necessario specificare una connessione a una definizione di modello OpenAI. Imposta la connessione del modello OpenAI nei tuoi bindings usando uno di questi approcci:

• Usa la AIConnectionName proprietà binding (preferita per Azure OpenAI).
• Imposta AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_KEY nelle impostazioni dell'app (per Azure OpenAI).
• Imposta solo Open_API_Key nelle impostazioni dell'app (per https://api.openai.com).

Il modo in cui si imposta la connessione dipende sia dall'API del modello sia dal metodo di autenticazione, come indicato dalla seguente tabella:

API di autenticazione/modello	Azure OpenAI	OpenAI (https://api.openai.com)
Connessione di identità gestita	AIConnectionName	Non supportato
Riferimento Key Vault	AZURE_OPENAI_ENDPOINT AZURE_OPENAI_KEY	Open_API_Key
Riferimento alla configurazione dell'app	AZURE_OPENAI_ENDPOINT AZURE_OPENAI_KEY	Open_API_Key
Segreto condiviso	AZURE_OPENAI_ENDPOINT AZURE_OPENAI_KEY	Open_API_Key

Usa connessioni gestite basate sull'identità e la AIConnectionName proprietà.

Quando si usa AIConnectionName, il valore di questa impostazione di proprietà dipende dal tipo di connessione:

• Connessione di identità gestita: La AIConnectionName proprietà è <CONNECTION_NAME_PREFIX> condivisa da un gruppo di impostazioni che insieme definiscono una connessione basata sull'identità con Azure OpenAI. Per ulteriori informazioni, vedi Definire connessioni identitari.
• Riferimento Key Vault: L'impostazione AIConnectionName della proprietà restituisce un riferimento Azure Key Vault alla posizione in cui la chiave API è mantenuta centralmente. Per maggiori informazioni, vedi Definire le connessioni Key Vault.
• Riferimento App Configuration: L'impostazione AIConnectionName della proprietà restituisce un riferimento Configurazione app di Azure che restituisce una chiave API o un riferimento a Key Vault. Per ulteriori informazioni, consulta Configurazione app di Azure nell'articolo sulle connessioni.
• Chiave API: L'impostazione AIConnectionName della proprietà si risolve nelle impostazioni dell'app che contengono direttamente l'endpoint e la chiave. Poiché le chiavi condivise possono essere compromesse, usa le connessioni di identità gestite quando possibile. Per maggiori informazioni, vedi Definisci le connessioni.

Per saperne di più sulle connessioni dei binding, consulta Manage connections in Funzioni di Azure.

AIConnectionName, proprietà

I bindings di OpenAI includono una AIConnectionName proprietà che puoi usare per specificare <ConnectionNamePrefix> il gruppo di impostazioni dell'app che definiscono la connessione ad Azure OpenAI:

Nome della impostazione	Descrizione
<CONNECTION_NAME_PREFIX>__endpoint	Imposta l'endpoint URI del servizio Azure OpenAI. Questa impostazione è sempre obbligatoria.
<CONNECTION_NAME_PREFIX>__clientId	Imposta l'identità assegnata dall'utente specifica da usare per ottenere un token di accesso. Richiede che <CONNECTION_NAME_PREFIX>__credential sia impostato su managedidentity. La proprietà accetta un ID client corrispondente a un'identità assegnata dall'utente assegnata all'applicazione. Non è valido specificare sia un ID risorsa che un ID client. Se non specifichi questa proprietà, viene utilizzata l'identità assegnata dal sistema. Questa proprietà viene usata in modo diverso in scenari di sviluppo locale, quando non è consigliabile impostare credential.
<CONNECTION_NAME_PREFIX>__credential	Definisce il modo in cui viene ottenuto un token access per la connessione. Usare managedidentity per l'autenticazione dell'identità gestita. Questo valore è valido solo quando un'identità gestita è disponibile nell'ambiente di hosting.
<CONNECTION_NAME_PREFIX>__managedIdentityResourceId	Quando credential è impostato su managedidentity, imposta questa proprietà per specificare l'Identificatore della risorsa da utilizzare quando si ottiene un token. La proprietà accetta un identificatore di risorsa corrispondente all'ID risorsa dell'identità gestita definita dall'utente. Non è valido specificare sia un ID risorsa che un ID client. Se non specifichi nessuno dei due, viene utilizzata l'identità assegnata dal sistema. Questa proprietà viene usata in modo diverso in scenari di sviluppo locale, quando non è consigliabile impostare credential.
<CONNECTION_NAME_PREFIX>__key	Imposta la chiave segreta condivisa necessaria per accedere all'endpoint del servizio Azure OpenAI utilizzando l'autenticazione basata su chiavi. Come buona pratica di sicurezza, usa sempre Microsoft Entra ID con identità gestite per l'autenticazione.

Considera queste impostazioni di connessione di identità gestita quando imposti la AIConnectionName proprietà su myAzureOpenAI:

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

Durante l'esecuzione, l'host interpreta queste impostazioni come un'unica myAzureOpenAI impostazione:

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

Quando usi le identità gestite, assicurati di aggiungere la tua identità al ruolo Cognitive Services OpenAI User .

Quando si esegue in località, aggiungi queste impostazioni al filelocal.settings.json progetto. Per altre informazioni, vedere Sviluppo locale con connessioni basate su identità.

Variabili di ambiente

Per supportare app e provider legacy diversi da Azure OpenAI, definisci l'autenticazione basata su chiavi per OpenAI utilizzando queste variabili di ambiente.

Nome variabile	Descrizione
AZURE_OPENAI_ENDPOINT	Imposta l'endpoint URI dell'istanza di Azure OpenAI. Non usare con Open_API_Key.
AZURE_OPENAI_KEY	Imposta la chiave segreta condivisa necessaria per accedere al tuo endpoint Azure OpenAI (AZURE_OPENAI_ENDPOINT) utilizzando l'autenticazione basata su chiave.
Open_API_Key	Imposta la chiave segreta condivisa necessaria per accedere all'endpoint https://api.openai.com utilizzando l'autenticazione basata su chiavi.

Imposta queste variabili nelle impostazioni dell'app.

Quando si esegue in località, aggiungi queste impostazioni al filelocal.settings.json progetto.

Per altre informazioni, vedere Work with application settings.For more information, see Work with application settings.

Contenuto correlato

• Esempi di assistente
• Estensione OpenAI di Azure
• Trigger dell'assistente OpenAI di Azure
• Associazione di input delle query per l'assistente Azure OpenAI
• Associazione post-input dell'assistente OpenAI di Azure