Vinculação de entrada de consulta do assistente do Azure OpenAI para o Funções do Azure

Importante

A extensão do Azure OpenAI para o Funções do Azure está atualmente em visualização.

A vinculação de entrada de consulta do assistente OpenAI do Azure permite integrar consultas de API de Assistentes em suas execuções de código.

Para obter informações sobre detalhes de instalação e configuração da extensão do Azure OpenAI, consulte Extensões do Azure OpenAI para Funções do Azure. Para saber mais sobre os assistentes do Azure OpenAI, consulte Azure OpenAI Assistants API.

Nota

Referências e exemplos são fornecidos apenas para o modelo Node.js v4.

Nota

Referências e exemplos são fornecidos apenas para o modelo Python v2.

Nota

Embora ambos os modelos de processo C# sejam suportados, apenas exemplos de modelos de trabalho isolados são fornecidos.

Exemplo

O suporte Go não está atualmente disponível para esta ligação.

Este exemplo demonstra o processo de criação, onde a função HTTP GET que consulta o histórico de conversas do bot de chat assistente. A resposta ao prompt é retornada na resposta 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);
}

Este exemplo demonstra o processo de criação, onde a função HTTP GET que consulta o histórico de conversas do bot de chat assistente. A resposta ao prompt é retornada na resposta 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();
}

Este exemplo demonstra o processo de criação, onde a função HTTP GET que consulta o histórico de conversas do bot de chat assistente. A resposta ao prompt é retornada na resposta 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 }
    }
})

Este exemplo demonstra o processo de criação, onde a função HTTP GET que consulta o histórico de conversas do bot de chat assistente. A resposta ao prompt é retornada na resposta 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 }
    }
})

Este exemplo demonstra o processo de criação, onde a função HTTP GET que consulta o histórico de conversas do bot de chat assistente. A resposta ao prompt é retornada na resposta HTTP.

Aqui está o arquivo function.json para Obter estado de bate-papo:

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

Para obter mais informações sobre function.json propriedades do arquivo, consulte a seção Configuração .

using namespace System.Net

param($Request, $TriggerMetadata, $State)

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

Este exemplo demonstra o processo de criação, onde a função HTTP GET que consulta o histórico de conversas do bot de chat assistente. A resposta ao prompt é retornada na resposta 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")

Atributos

Aplique o AssistantQuery atributo para definir uma associação de entrada de consulta assistente, que suporta estes parâmetros:

Parâmetro Descrição
ID Obtém a ID do assistente a consultar.
TimeStampUtc Opcional. Obtém ou define o carimbo de data/hora da mensagem mais antiga no histórico de bate-papo a ser buscado. O carimbo de data/hora deve estar no formato ISO 8601 - por exemplo, 2023-08-01T00:00:00Z.

Anotações

A assistantQuery anotação permite definir uma associação de entrada de consulta assistente, que suporta estes parâmetros:

Elemento Descrição
Designação Obtém ou define o nome da ligação de entrada.
ID Obtém a ID do assistente a consultar.
timeStampUtc Opcional. Obtém ou define o carimbo de data/hora da mensagem mais antiga no histórico de bate-papo a ser buscado. O carimbo de data/hora deve estar no formato ISO 8601 - por exemplo, 2023-08-01T00:00:00Z.

Decoradores

Durante a visualização, defina a ligação de entrada como uma generic_input_binding associação do tipo assistantQuery, que suporta estes parâmetros:

Parâmetro Descrição
arg_name O nome da variável que representa o parâmetro de ligação.
ID Obtém a ID do assistente a consultar.
time_stamp_utc Opcional. Obtém ou define o carimbo de data/hora da mensagem mais antiga no histórico de bate-papo a ser buscado. O carimbo de data/hora deve estar no formato ISO 8601 - por exemplo, 2023-08-01T00:00:00Z.

Configuração

A associação suporta essas propriedades de configuração definidas no arquivo function.json.

Propriedade Descrição
tipo Deve ser assistantQuery.
direção Deve ser in.
Designação O nome da ligação de entrada.
ID Obtém a ID do assistente a consultar.
timeStampUtc Opcional. Obtém ou define o carimbo de data/hora da mensagem mais antiga no histórico de bate-papo a ser buscado. O carimbo de data/hora deve estar no formato ISO 8601 - por exemplo, 2023-08-01T00:00:00Z.

Configuração

A associação suporta estas propriedades, que são definidas no seu código:

Propriedade Descrição
ID Obtém a ID do assistente a consultar.
timeStampUtc Opcional. Obtém ou define o carimbo de data/hora da mensagem mais antiga no histórico de bate-papo a ser buscado. O carimbo de data/hora deve estar no formato ISO 8601 - por exemplo, 2023-08-01T00:00:00Z.

Utilização

Consulte a seção Exemplo para obter exemplos completos.

Connections

Para usar a extensão de ligação Azure OpenAI, precisa de especificar uma ligação a uma definição de modelo OpenAI. Defina a ligação do modelo OpenAI nas suas ligações usando uma destas abordagens:

  • Use a AIConnectionName propriedade binding (preferida para Azure OpenAI).
  • Definir AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_KEY nas definições da aplicação (para Azure OpenAI).
  • Definir apenas Open_API_Key nas definições da aplicação (para https://api.openai.com).

A forma como se define a ligação depende tanto da API do modelo como do método de autenticação, conforme indicado na tabela seguinte:

API de Autenticação/Modelo Azure OpenAI OpenAI (https://api.openai.com)
Ligação de identidade gerida AIConnectionName Não suportado
Referência ao Key Vault AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key
Referência de configuração da aplicação AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key
Segredo partilhado AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key

Use ligações geridas baseadas em identidade e a propriedade AIConnectionName .

Quando usa AIConnectionName, o valor desta definição de propriedade depende do tipo de ligação:

  • Ligação de identidade gerida: A AIConnectionName propriedade é <CONNECTION_NAME_PREFIX> partilhada por um grupo de definições que, em conjunto, definem uma ligação baseada em identidade ao Azure OpenAI. Para mais informações, consulte Definir ligações de identidade.
  • Referência Key Vault: A AIConnectionName definição de propriedade devolve uma referência Azure Key Vault ao local onde a chave API é mantida centralmente. Para mais informações, consulte Definir ligações ao Key Vault.
  • Referência App Configuration: A AIConnectionName definição de propriedade devolve uma referência Azure App Configuration que devolve uma chave API ou uma referência ao Key Vault. Para mais informações, consulte Azure App Configuration no artigo de ligações.
  • Chave API: A AIConnectionName definição de propriedade resolve para as definições da aplicação que contêm diretamente o endpoint e a chave. Como as chaves partilhadas podem ser comprometidas, utilize ligações de identidade geridas sempre que possível. Para mais informações, veja Definir ligações.

Para saber mais sobre ligações de bindings, consulte Gerir ligações no Funções do Azure.

As ligações OpenAI incluem uma AIConnectionName propriedade que pode usar para especificar <ConnectionNamePrefix> o grupo de definições da aplicação que definem a ligação ao Azure OpenAI:

Nome da configuração Descrição
<CONNECTION_NAME_PREFIX>__endpoint Define o endpoint URI do serviço Azure OpenAI. Essa configuração é sempre necessária.
<CONNECTION_NAME_PREFIX>__clientId Define a identidade específica atribuída pelo usuário a ser usada ao obter um token de acesso. Requer que <CONNECTION_NAME_PREFIX>__credential esteja definido como managedidentity. A propriedade aceita um ID de cliente correspondente a uma identidade atribuída pelo usuário atribuída ao aplicativo. É inválido especificar uma ID de recurso e uma ID de cliente. Se não especificar esta propriedade, é usada a identidade atribuída pelo sistema. Esta propriedade é usada de forma diferente em cenários de desenvolvimento local, quando credential não deveria ser definida.
<CONNECTION_NAME_PREFIX>__credential Define como um token de acesso é obtido para a ligação. Use managedidentity para autenticação de identidade gerenciada. Esse valor só é válido quando uma identidade gerenciada está disponível no ambiente de hospedagem.
<CONNECTION_NAME_PREFIX>__managedIdentityResourceId Quando credential está definido como managedidentity, defina esta propriedade para especificar o Identificador de recurso a usar ao obter um token. A propriedade aceita um identificador de recurso correspondente ao ID do recurso da identidade gerenciada definida pelo usuário. É inválido especificar um ID de recurso e um ID de cliente. Se não especificar nenhum dos dois, é usada a identidade atribuída pelo sistema. Esta propriedade é usada de forma diferente em cenários de desenvolvimento local, quando credential não deveria ser definida.
<CONNECTION_NAME_PREFIX>__key Define a chave secreta partilhada necessária para aceder ao endpoint do serviço Azure OpenAI usando autenticação baseada em chaves. Como melhor prática de segurança, utilize sempre o Microsoft Entra ID com identidades geridas para autenticação.

Considere estas definições de ligação de identidade gerida quando definir a AIConnectionName propriedade para myAzureOpenAI:

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

Em tempo de execução, o anfitrião interpreta estas definições como uma única myAzureOpenAI definição:

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

Quando usar identidades geridas, certifique-se de adicionar a sua identidade ao papel de Utilizador OpenAI de Serviços Cognitivos .

Ao executar localmente, adicione estas definições ao ficheirolocal.settings.json projeto. Para obter mais informações, consulte Desenvolvimento local com conexões baseadas em identidade.

Para obter mais informações, consulte Trabalhar com configurações do aplicativo.