Wyzwalacz asystenta usługi Azure OpenAI dla usługi Azure Functions

Ważne

Rozszerzenie Azure OpenAI dla usługi Azure Functions jest obecnie dostępne w wersji zapoznawczej.

Wyzwalacz asystenta usługi Azure OpenAI umożliwia uruchamianie kodu na podstawie niestandardowego czatbota lub żądania umiejętności skierowanego do asystenta.

Aby uzyskać informacje na temat konfigurowania i konfigurowania rozszerzenia Azure OpenAI, zobacz Azure OpenAI extensions for Azure Functions (Rozszerzenia azure OpenAI dla usługi Azure Functions). Aby dowiedzieć się więcej na temat asystentów usługi Azure OpenAI, zobacz Interfejs API asystentów usługi Azure OpenAI.

Uwaga

Odwołania i przykłady są udostępniane tylko dla modelu Node.js w wersji 4.

Uwaga

Odwołania i przykłady są udostępniane tylko dla modelu języka Python w wersji 2.

Uwaga

Chociaż oba modele procesów języka C# są obsługiwane, udostępniane są tylko izolowane przykłady modeli procesów roboczych.

Przykład

Wsparcie Go nie jest obecnie dostępne dla tego przypisania.

W tym przykładzie pokazano, jak utworzyć asystenta, który dodaje nowe zadanie do wykonania do bazy danych. Wyzwalacz zawiera statyczny Create a new todo task opis używany przez model. Sama funkcja przyjmuje ciąg, który reprezentuje nowe zadanie do dodania. Po wykonaniu funkcja dodaje zadanie jako nowy element zadania do wykonania w magazynie niestandardowych elementów i zwraca odpowiedź ze sklepu.

[Function(nameof(AddTodo))]
public Task AddTodo([AssistantSkillTrigger("Create a new todo task")] string taskDescription)
{
    if (string.IsNullOrEmpty(taskDescription))
    {
        throw new ArgumentException("Task description cannot be empty");
    }

    this.logger.LogInformation("Adding todo: {task}", taskDescription);

    string todoId = Guid.NewGuid().ToString()[..6];
    return this.todoManager.AddTodoAsync(new TodoItem(todoId, taskDescription));
}

W tym przykładzie pokazano, jak utworzyć asystenta, który dodaje nowe zadanie do wykonania do bazy danych. Wyzwalacz zawiera statyczny Create a new todo task opis używany przez model. Sama funkcja przyjmuje ciąg, który reprezentuje nowe zadanie do dodania. Po wykonaniu funkcja dodaje zadanie jako nowy element zadania do wykonania w magazynie niestandardowych elementów i zwraca odpowiedź ze sklepu.

/**
 * Called by the assistant to create new todo tasks.
 */
@FunctionName("AddTodo")
public void addTodo(
    @AssistantSkillTrigger(
            name = "assistantSkillCreateTodo",
            functionDescription = "Create a new todo task"
    ) String taskDescription,
    final ExecutionContext context) {

    if (taskDescription == null || taskDescription.isEmpty()) {
        throw new IllegalArgumentException("Task description cannot be empty");
    }
    context.getLogger().info("Adding todo: " + taskDescription);

    String todoId = UUID.randomUUID().toString().substring(0, 6);
    TodoItem todoItem = new TodoItem(todoId, taskDescription);
    todoManager.addTodo(todoItem);
}

W tym przykładzie pokazano, jak utworzyć asystenta, który dodaje nowe zadanie do wykonania do bazy danych. Wyzwalacz zawiera statyczny Create a new todo task opis używany przez model. Sama funkcja przyjmuje ciąg, który reprezentuje nowe zadanie do dodania. Po wykonaniu funkcja dodaje zadanie jako nowy element zadania do wykonania w magazynie niestandardowych elementów i zwraca odpowiedź ze sklepu.

const { app, trigger } = require("@azure/functions");
const { TodoItem, CreateTodoManager } = require("../services/todoManager");
const { randomUUID } = require('crypto');

const todoManager = CreateTodoManager()

app.generic('AddTodo', {
    trigger: trigger.generic({
        type: 'assistantSkillTrigger',
        functionDescription: 'Create a new todo task'
    }),
    handler: async (taskDescription, context) => {
        if (!taskDescription) {
            throw new Error('Task description cannot be empty')
        }

        context.log(`Adding todo: ${taskDescription}`)

        const todoId = randomUUID().substring(0, 6)
        return todoManager.AddTodo(new TodoItem(todoId, taskDescription))
    }
})
import { InvocationContext, app, trigger } from "@azure/functions"
import { TodoItem, ITodoManager, CreateTodoManager } from "../services/todoManager"
import { randomUUID } from 'crypto';

const todoManager: ITodoManager = CreateTodoManager()

app.generic('AddTodo', {
    trigger: trigger.generic({
        type: 'assistantSkillTrigger',
        functionDescription: 'Create a new todo task'
    }),
    handler: async (taskDescription: string, context: InvocationContext) => {
        if (!taskDescription) {
            throw new Error('Task description cannot be empty')
        }

        context.log(`Adding todo: ${taskDescription}`)

        const todoId = randomUUID().substring(0, 6)
        return todoManager.AddTodo(new TodoItem(todoId, taskDescription))
    }
})

W tym przykładzie pokazano, jak utworzyć asystenta, który dodaje nowe zadanie do wykonania do bazy danych. Wyzwalacz zawiera statyczny Create a new todo task opis używany przez model. Sama funkcja przyjmuje ciąg, który reprezentuje nowe zadanie do dodania. Po wykonaniu funkcja dodaje zadanie jako nowy element zadania do wykonania w magazynie niestandardowych elementów i zwraca odpowiedź ze sklepu.

Oto plik function.json dodawania zadań do wykonania:

{
  "bindings": [
    {
      "name": "TaskDescription",
      "type": "assistantSkillTrigger",
      "dataType": "string",
      "direction": "in",
      "functionDescription": "Create a new todo task"
    }
  ]
}

Aby uzyskać więcej informacji na temat function.json właściwości pliku, zobacz sekcję Konfiguracja.

using namespace System.Net

param($TaskDescription, $TriggerMetadata)
$ErrorActionPreference = "Stop"

if (-not $TaskDescription) {
    throw "Task description cannot be empty"
}

Write-Information "Adding todo: $TaskDescription"
$todoID = [Guid]::NewGuid().ToString().Substring(0, 5)
Add-Todo $todoId $TaskDescription

W tym przykładzie pokazano, jak utworzyć asystenta, który dodaje nowe zadanie do wykonania do bazy danych. Wyzwalacz zawiera statyczny Create a new todo task opis używany przez model. Sama funkcja przyjmuje ciąg, który reprezentuje nowe zadanie do dodania. Po wykonaniu funkcja dodaje zadanie jako nowy element zadania do wykonania w magazynie niestandardowych elementów i zwraca odpowiedź ze sklepu.

@skills.function_name("AddTodo")
@skills.assistant_skill_trigger(
    arg_name="taskDescription", function_description="Create a new todo task"
)
def add_todo(taskDescription: str) -> None:
    if not taskDescription:
        raise ValueError("Task description cannot be empty")

    logging.info(f"Adding todo: {taskDescription}")

    todo_id = str(uuid.uuid4())[0:6]
    todo_manager.add_todo(TodoItem(id=todo_id, task=taskDescription))
    return

Atrybuty

Zastosuj atrybut, AssistantSkillTrigger aby zdefiniować wyzwalacz asystenta, który obsługuje następujące parametry:

Parametr Opis
FunctionDescription Pobiera opis funkcji asystenta, która jest dostarczana do modelu.
Nazwa funkcji Opcjonalne. Pobiera lub ustawia nazwę funkcji wywoływanej przez asystenta.
ParameterDescriptionJson Opcjonalne. Pobiera lub ustawia opis JSON parametru funkcji, który jest udostępniany modelowi. Aby uzyskać więcej informacji, zobacz Użycie.

Adnotacje

Adnotacja AssistantSkillTrigger umożliwia zdefiniowanie wyzwalacza asystenta, który obsługuje następujące parametry:

Składnik Opis
nazwa Pobiera lub ustawia nazwę powiązania wejściowego.
functionDescription Pobiera opis funkcji asystenta, która jest dostarczana do modelu.
functionName Opcjonalne. Pobiera lub ustawia nazwę funkcji wywoływanej przez asystenta.
parameterDescriptionJson Opcjonalne. Pobiera lub ustawia opis JSON parametru funkcji, który jest udostępniany modelowi. Aby uzyskać więcej informacji, zobacz Użycie.

Dekoratory

W wersji zapoznawczej zdefiniuj powiązanie wejściowe jako generic_trigger powiązanie typu assistantSkillTrigger, które obsługuje następujące parametry:

Parametr Opis
function_description Pobiera opis funkcji asystenta, która jest dostarczana do modelu.
function_name Opcjonalne. Pobiera lub ustawia nazwę funkcji wywoływanej przez asystenta.
parameterDescriptionJson Opcjonalne. Pobiera lub ustawia opis JSON parametru funkcji, który jest udostępniany modelowi. Aby uzyskać więcej informacji, zobacz Użycie.

Konfigurowanie

Powiązanie obsługuje te właściwości konfiguracji ustawione w pliku function.json.

Właściwości Opis
typ Musi mieć wartość AssistantSkillTrigger.
kierunek Musi mieć wartość in.
nazwa Nazwa wyzwalacza.
functionName Pobiera lub ustawia nazwę funkcji wywoływanej przez asystenta.
functionDescription Pobiera opis funkcji asystenta, która jest dostarczana do modelu językowego.
parameterDescriptionJson Opcjonalne. Pobiera lub ustawia opis JSON parametru funkcji, który jest udostępniany modelowi. Aby uzyskać więcej informacji, zobacz Użycie.

Konfigurowanie

Powiązanie obsługuje te właściwości zdefiniowane w kodzie:

Właściwości Opis
typ Musi mieć wartość AssistantSkillTrigger.
nazwa Nazwa wyzwalacza.
functionName Pobiera lub ustawia nazwę funkcji wywoływanej przez asystenta.
functionDescription Pobiera opis funkcji asystenta, która jest dostarczana do usługi LLM
parameterDescriptionJson Opcjonalne. Pobiera lub ustawia opis JSON parametru funkcji, który jest udostępniany modelowi. Aby uzyskać więcej informacji, zobacz Użycie.

Zobacz sekcję Przykład, aby zapoznać się z kompletnymi przykładami.

Użycie

Jeśli parameterDescriptionJson wartość JSON nie zostanie podana, zostanie wygenerowana automatycznie. Więcej informacji o składni tego obiektu można znaleźć w dokumentacji funkcji wywołań OpenAI.

Connections

Aby korzystać z rozszerzenia Azure OpenAI, musisz określić połączenie z definicją modelu OpenAI. Ustaw połączenie modelu OpenAI w swoich bindingach, stosując jedno z następujących podejść:

  • Użyj właściwości wiązania AIConnectionName (preferowanej dla Azure OpenAI).
  • Ustaw AZURE_OPENAI_ENDPOINT i AZURE_OPENAI_KEY w ustawieniach aplikacji (dla Azure OpenAI).
  • Ustaw tylko Open_API_Key w ustawieniach aplikacji (dla https://api.openai.com).

Sposób, w jaki ustawiasz połączenie, zależy zarówno od API modelu, jak i metody uwierzytelniania, jak pokazano w poniższej tabeli:

API uwierzytelniania/modelu Azure OpenAI OpenAI (https://api.openai.com)
Połączenie zarządzanej tożsamości AIConnectionName Niewspierane
Odniesienie do Key Vault AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key
Referencja konfiguracji aplikacji AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key
Wspólny klucz tajny AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
Open_API_Key

Użyj połączeń opartych na zarządzanej tożsamości oraz właściwości AIConnectionName .

Gdy używamy AIConnectionName, wartość tego ustawienia właściwości zależy od typu połączenia:

  • Połączenie zarządzanej tożsamości: Własność AIConnectionName jest współdzielona <CONNECTION_NAME_PREFIX> przez grupę ustawień, które razem definiują połączenie oparte na tożsamości z Azure OpenAI. Więcej informacji można znaleźć w artykule Definiuj powiązania tożsamości.
  • Key Vault referencja: Ustawienie AIConnectionName właściwości zwraca referencję Azure Key Vault do miejsca, w którym klucz API jest centralnie przechowywany. Więcej informacji można znaleźć w artykule Definiuj połączenia Key Vault.
  • Referencja konfiguracji aplikacji: Ustawienie AIConnectionName właściwości zwraca referencję Azure App Configuration, która zwraca klucz API lub referencję do Key Vault. Więcej informacji można znaleźć w artykule o połączeniach w sekcji Azure App Configuration.
  • Klucz API: Ustawienie AIConnectionName właściwości rozwiązuje się bezpośrednio do ustawień aplikacji zawierających punkt końcowy i klucz. Ponieważ klucze współdzielone mogą zostać zagrożone, stosuj połączenia zarządzane tożsamości, gdy to możliwe. Więcej informacji można znaleźć w artykule Definiuj połączenia.

Aby dowiedzieć się więcej o powiązaniach wiązanych, zobacz Zarządzanie połączeniami w Azure Functions.

Powiązania OpenAI zawierają właściwośćAIConnectionName, którą możesz użyć do określenia <ConnectionNamePrefix> grupy ustawień aplikacji definiujących połączenie z Azure OpenAI:

Nazwa ustawień Opis
<CONNECTION_NAME_PREFIX>__endpoint Sets endpoint URI usługi Azure OpenAI. To ustawienie jest zawsze wymagane.
<CONNECTION_NAME_PREFIX>__clientId Ustawia określoną tożsamość przypisaną przez użytkownika do użycia podczas uzyskiwania tokenu dostępu. Wymaga, aby <CONNECTION_NAME_PREFIX>__credential było ustawione na managedidentity. Właściwość akceptuje identyfikator klienta odpowiadający tożsamości przypisanej przez użytkownika do aplikacji. Jest to nieprawidłowe określenie zarówno identyfikatora zasobu, jak i identyfikatora klienta. Jeśli nie określisz tej właściwości, używana jest tożsamość przypisana przez system. Ta właściwość jest używana inaczej w lokalnych scenariuszach programowania, gdy credential nie należy ich ustawiać.
<CONNECTION_NAME_PREFIX>__credential Definiuje sposób uzyskiwania tokenu access dla połączenia. Służy managedidentity do uwierzytelniania tożsamości zarządzanej. Ta wartość jest prawidłowa tylko wtedy, gdy tożsamość zarządzana jest dostępna w środowisku hostingu.
<CONNECTION_NAME_PREFIX>__managedIdentityResourceId Gdy credential jest ustawione na managedidentity, ustaw tę właściwość, aby określić identyfikator zasobu, którego ma się użyć przy uzyskaniu tokena. Właściwość akceptuje identyfikator zasobu odpowiadający identyfikatorowi zasobu tożsamości zarządzanej zdefiniowanej przez użytkownika. Nie można określić zarówno identyfikatora zasobu, jak i identyfikatora klienta. Jeśli nie określisz żadnej z tych funkcji, używa się tożsamości przypisanej przez system. Ta właściwość jest używana inaczej w lokalnych scenariuszach programowania, gdy credential nie należy ich ustawiać.
<CONNECTION_NAME_PREFIX>__key Ustawia wspólny tajny klucz potrzebny do dostępu do punktu końcowego usługi Azure OpenAI, korzystając z uwierzytelniania opartego na kluczu. Jako najlepszą praktykę bezpieczeństwa zawsze używaj Microsoft Entra ID z zarządzanymi tożsamościami do uwierzytelniania.

Rozważ te ustawienia zarządzania połączeniem tożsamości, gdy ustawiasz AIConnectionName własność na:myAzureOpenAI

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

W czasie działania host interpretuje te ustawienia jako jedno myAzureOpenAI ustawienie:

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

Korzystając z zarządzanych tożsamości, upewnij się, że dodajesz swoją tożsamość do roli użytkownika OpenAI w Usługach Kognitywnych .

Podczas uruchamiania lokalnie dodaj te ustawienia do pliku projektu local.settings.json . Aby uzyskać więcej informacji, zobacz Programowanie lokalne przy użyciu połączeń opartych na tożsamościach.

Aby uzyskać więcej informacji, zobacz Praca z ustawieniami aplikacji.