Teilen über

Schnellstart: Erste Schritte mit Azure OpenAI Assistants (Vorschau)

  • Artikel

Mit Azure OpenAI Assistants (Preview) können Sie KI-Assistenten erstellen, die dank benutzerdefinierte Anweisungen auf Ihre Anforderungen zugeschnitten sind und durch erweiterte Tools wie Codedolmetscher und benutzerdefinierte Funktionen ergänzt werden.

Wichtig

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

Voraussetzungen

Navigieren zu Azure KI Studio (Vorschau)

Mit Azure KI Studio können Sie v2-Assistenten verwenden, die mehrere Upgrades bieten. Das Dateisuche-Tool ist etwa schneller und unterstützt mehr Dateien.

  1. Melden Sie sich beim Azure KI Studio an.

  2. Wechseln Sie zu Ihrem Projekt oder erstellen Sie ein neues Projekt in Azure KI Studio.

  3. Wählen Sie in der Projektübersicht Assistentenaus. Dies befindet sich unter Projekt-Playground.

    Mit dem Assistants-Playground können Sie KI-Assistenten erkunden, prototypisieren und testen, ohne Code ausführen zu müssen. Auf dieser Seite können Sie neue Ideen ganz einfach schrittweise erkunden und mit ihnen experimentieren.

    Der Playground bietet mehrere Optionen zum Konfigurieren des Assistenten. In den folgenden Schritten werden Sie den Bereich Assistenten-Setup, um einen neuen KI-Assistenten zu erstellen.

    Name Beschreibung
    Assistentenname Ihr Bereitstellungsname, der einem bestimmten Modell zugeordnet ist.
    Anweisungen Anweisungen ähneln Systemmeldungen, die dem Modell Anleitungen dazu geben, wie es sich verhalten soll und auf welche Kontexte es beim Generieren von Antworten verweisen soll. Sie können die Persönlichkeit des Assistenten beschreiben, ihm sagen, was er beantworten soll und was nicht, und ihm sagen, wie Antworten formatiert werden sollen. Sie können auch Beispiele für die Schritte bereitstellen, die es beim Beantworten von Antworten ausführen soll.
    Bereitstellung Hier legen Sie fest, welche Modellimplementierung mit Ihrem Assistenten verwendet werden soll.
    Funktionen Erstellen Sie benutzerdefinierte Funktionsdefinitionen für die Modelle zum Formulieren von API-Aufrufen und strukturieren Sie Datenausgaben basierend auf Ihren Spezifikationen. In dieser Schnellstartanleitung nicht verwendet.
    Codeinterpreter Codeinterpreter bietet Zugriff auf eine Sandbox-Python-Umgebung, mit der das Modell Code testen und ausführen kann.
    Dateien Sie können bis zu 10.000 Dateien mit einer maximalen Dateigröße von 512 MB hochladen, um sie mit Tools zu verwenden. In dieser Schnellstartanleitung nicht verwendet.

    Screenshot: Bildschirm mit der Konfiguration des Assistenten ohne ausgefüllte Werte.

Erstellen Ihres ersten Assistenten

  1. Wählen Sie Ihre Bereitstellung in der Dropdownliste Bereitstellungen aus.

  2. Wählen Sie im Dropdownmenü „Assistenten-Setup“ die Option Neu aus.

  3. Geben Sie Ihrem Assistenten einen Namen.

  4. Geben Sie die folgenden Anweisungen ein: „Du bist ein KI-Assistent, der Code schreiben kann, um mathematische Fragen zu beantworten“.

  5. Wählen Sie eine Modellimplementierung aus. Es wird empfohlen, für Tests die neuesten gpt-4-Modelle zu verwenden.

  6. Wählen Sie den Umschalter zum Aktivieren des Codeinterpreters aus.

  7. Wählen Sie Speichern.

    Screenshot: Assistent mit eingegebenen Konfigurationsdetails.

  8. Geben Sie eine Frage ein, die der Assistent benatworten soll: „Ich muss die Rechnung 3x + 11 = 14 lösen. Kannst du mir helfen?“

  9. Wählen Sie die Schaltfläche Hinzufügen und Ausführen aus. 

    The solution to the equation (3x + 11 = 14) is (x = 1).

    Wir sehen zwar, dass die Antwort richtig ist, aber um zu bestätigen, dass das Modell den Codeinterpreter verwendet hat, um zu dieser Antwort zu gelangen, und dass der von ihm geschriebene Code gültig ist und nicht einfach eine Antwort aus den Trainingsdaten des Modells wiederholt, müssen wir eine weitere Frage stellen.

  10. Geben Sie Folgendes ein: „Zeige mir den Code an, den du ausgeführt hast, um diese Lösung zu erhalten.“

    Sure. The code is very straightforward

    # calculation
x = (14 - 11) / 3
x


    First, we subtract 11 from 14, then divide the result by 3. This gives us the value of x which is 1.0.

    Screenshot: Unterhaltungssitzung im Playground des Assistenten.

Sie können auch die Protokolle im rechten Bereich konsultieren, um sicherzustellen, dass der Codeinterpreter verwendet wurde, und um den Code zu überprüfen, der zur Generierung der Antwort ausgeführt wurde. Es ist wichtig zu beachten, dass der Codeinterpreter das Modell zwar in die Lage versetzt, auf komplexere mathematische Fragen zu reagieren, indem er die Fragen in Code konvertiert und in einer Sandbox-Python-Umgebung ausgeführt. Dennoch müssen Sie die Antwort überprüfen, um sicherzustellen, dass das Modell Ihre Frage korrekt in eine gültige Codedarstellung übersetzt hat.

Wichtige Begriffe

Beachten Sie bei der Verwendung des Assistenten-Playgrounds die folgenden Konzepte.

Extras

Ein einzelner Assistent kann auf bis zu 128 Tools code interpretersowie auf alle benutzerdefinierten Tools, die Sie über Funktionen erstellen, zugreifen.

Chat-Sitzung

Die Chatsitzung, die innerhalb der API des Assistenten auch als Thread bezeichnet wird, ist der Ort, an dem die Unterhaltung zwischen Benutzer*innen und dem Assistenten stattfindet. Im Gegensatz zu herkömmlichen Chatabschlussaufrufen ist die Anzahl der Nachrichten in einem Thread nicht begrenzt. Der Assistent komprimiert automatisch Anforderungen, um den Eingabetokengrenzwert des Modells anzupassen.

Das bedeutet auch, dass Sie nicht steuern, wie viele Token während jeder Unterhaltung an das Modell übergeben werden. Das Verwalten von Token wird vollständig von der Assistants-API abstrahiert und verarbeitet.

Wählen Sie die Schaltfläche Chat löschen aus, um den aktuellen Konversationsverlauf zu löschen.

Unterhalb des Texteingabefelds gibt es zwei Schaltflächen:

  • Nachricht ohne Ausführung hinzufügen.
  • Hinzufügen und Ausführen.

Protokolle

Protokolle bieten eine detaillierte Momentaufnahme der API-Aktivität des Assistenten.

Anzeigen von Bereichen

Standardmäßig gibt es drei Bereiche: Assistenteneinrichtung, Chatsitzung und Protokolle. Mit Bereiche anzeigen können Sie die Bereiche hinzufügen, entfernen und neu anordnen. Wenn Sie jemals einen Bereich schließen und ihn wiederherstellen müssen, verwenden Sie Bereiche anzeigen, um den geschlossenen Bereich wiederherzustellen.

Bereinigen von Ressourcen

Wenn Sie eine Azure OpenAI-Ressource bereinigen und entfernen möchten, können Sie die Ressource selbst oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Alternativ können Sie den Assistentenoder Thread über die API des Assistenten löschen.

Weitere Informationen

Referenzdokumentation | Quellcode der Bibliothek | Paket (PyPi) |

Voraussetzungen

Für die kennwortlose Authentifizierung müssen Sie die folgenden Schritte ausführen:

  1. Verwenden Sie das Paket azure-identity.
  2. Weisen Sie Ihrem Benutzerkonto die Cognitive Services User-Rolle zu. Navigieren Sie hierzu im Azure-Portal zu Zugriffssteuerung (IAM)>Rollenzuweisungen hinzufügen.
  3. Melden Sie sich mit der Azure CLI an (z. B. az login).

Einrichten

  1. Installieren Sie die OpenAI Python-Clientbibliothek mit:
pip install openai
  1. Für die empfohlene kennwortlose Authentifizierung:
pip install azure-identity

Hinweis

  • Die Dateisuche kann bis zu 10.000 Dateien pro Assistent erfassen – 500 mal mehr als bisher. Sie ist schnell, unterstützt parallele Abfragen durch Multithreadsuchvorgänge und beinhaltet verbesserte Funktionen für Neusortierung und das Umschreiben von Abfragen.
    • Der Vektorspeicher ist ein neues Objekt in der API. Sobald eine Datei einem Vektorspeicher hinzugefügt wurde, wird sie automatisch geparst, aufgeteilt und eingebettet, damit sie durchsucht werden kann. Vektorspeicher können über Assistenten und Threads hinweg verwendet werden und vereinfachen so die Dateiverwaltung und Abrechnung.
  • Wir haben Unterstützung für den tool_choice-Parameter hinzugefügt. Dieser kann verwendet werden, um die Nutzung eines bestimmten Tools (z. B. Dateisuche, Codeinterpreter oder eine Funktion) in einer bestimmten Ausführung zu erzwingen.

Hinweis

Diese Bibliothek wird von OpenAI verwaltet. Lesen Sie den Versionsverlauf, um die neuesten Updates für die Bibliothek nachzuverfolgen.

Abrufen von Schlüssel und Endpunkt

Um erfolgreich einen Aufruf im Azure OpenAI Service auszuführen, benötigen Sie Folgendes:

Variablenname Wert
ENDPOINT Diesen Wert finden Sie im Abschnitt Schlüssel und Endpunkt, wenn Sie die Ressource über das Azure-Portal untersuchen. Sie finden den Endpunkt auch über die Seite Bereitstellungen in Azure KI Studio. Ein Beispielendpunkt ist https://docs-test-001.openai.azure.com/.
API-KEY Diesen Wert finden Sie im Abschnitt Schlüssel und Endpunkt, wenn Sie die Ressource über das Azure-Portal untersuchen. Sie können KEY1 oder KEY2 verwenden.
DEPLOYMENT-NAME Dieser Wert entspricht dem benutzerdefinierten Namen, den Sie während der Bereitstellung eines Modells für die Bereitstellung ausgewählt haben. Diesen Wert finden Sie unter Ressourcenverwaltung>Modellimplementierungen im Azure-Portal oder auf der Seite Bereitstellungen in Azure KI Studio.

Wechseln Sie zu Ihrer Ressource im Azure-Portal. Die Werte für Schlüssel und Endpunkt finden Sie im Abschnitt Ressourcenverwaltung. Kopieren Sie die Werte für Endpunkt und Zugriffsschlüssel, da Sie beide für die Authentifizierung Ihrer API-Aufrufe benötigen. Sie können KEY1 oder KEY2 verwenden. Wenn Sie jederzeit zwei Schlüssel zur Verfügung haben, können Sie die Schlüssel auf sichere Weise rotieren und neu generieren, ohne Dienstunterbrechungen zu verursachen.

Screenshot des Übersichtsblatts für eine Azure OpenAI-Ressource im Azure-Portal mit rot umrandeten Speicherort für Endpunkt und Zugriffsschlüssel

Umgebungsvariablen

Erstellen und Zuweisen von beständigen Umgebungsvariablen für Ihren Schlüssel und Endpunkt.

Wichtig

Wenn Sie einen API-Schlüssel verwenden, speichern Sie ihn an einer anderen Stelle sicher, z. B. in Azure Key Vault. Fügen Sie den API-Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich zugänglich.

Weitere Informationen zur Sicherheit von KI Services finden Sie unter Authentifizieren von Anforderungen an Azure KI Services.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Erstellen eines Assistenten

In unserem Code geben wir die folgenden Werte an:

Name Beschreibung
Assistentenname Ihr Bereitstellungsname, der einem bestimmten Modell zugeordnet ist.
Anweisungen Anweisungen ähneln Systemmeldungen, die dem Modell Anleitungen dazu geben, wie es sich verhalten soll und auf welche Kontexte es beim Generieren von Antworten verweisen soll. Sie können die Persönlichkeit des Assistenten beschreiben, ihm sagen, was er beantworten soll und was nicht, und ihm sagen, wie Antworten formatiert werden sollen. Sie können auch Beispiele für die Schritte bereitstellen, die es beim Beantworten von Antworten ausführen soll.
Modell Hier legen Sie fest, welcher Modellimplementierungsname mit Ihrem Assistenten verwendet werden soll. Das Abruftool erfordert oder Modell gpt-35-turbo (1106) oder gpt-4 (1106-preview). Legen Sie diesen Wert auf Ihren Bereitstellungsnamen fest, nicht auf den Modellnamen, es sei denn, die Namen sind identisch.
Codeinterpreter Codeinterpreter bietet Zugriff auf eine Sandbox-Python-Umgebung, mit der das Modell Code testen und ausführen kann.

Extras

Ein einzelner Assistent kann auf bis zu 128 Tools code interpretersowie auf alle benutzerdefinierten Tools, die Sie über Funktionen erstellen, zugreifen.

Erstellen der Python-App

Melden Sie sich mit az login bei Azure an, und erstellen Sie anschließend mit dem folgenden empfohlenen kennwortlosen Python-Beispiel einen Assistenten:

import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

Um den API-Dienstschlüssel für die Authentifizierung zu verwenden, können Sie einen Assistenten mit dem folgenden Python-Beispiel erstellen und ausführen:

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

Output

Ausführung abgeschlossen mit dem Status: Abgeschlossen

{
  "data": [
    {
      "id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
      "assistant_id": "asst_cYqL1RuwLyFV3HU1gkaE2k0K",
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
          },
          "type": "text"
        }
      ],
      "created_at": 1716397091,
      "metadata": {},
      "object": "thread.message",
      "role": "assistant",
      "run_id": "run_hFgBPbUtO8ZNTnNPC8PgpH1S",
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    },
    {
      "id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
      "assistant_id": null,
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
          },
          "type": "text"
        }
      ],
      "created_at": 1716397025,
      "metadata": {},
      "object": "thread.message",
      "role": "user",
      "run_id": null,
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    }
  ],
  "object": "list",
  "first_id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
  "last_id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
  "has_more": false
}

Verstehen der Ergebnisse

In diesem Beispiel erstellen wir einen Assistenten mit aktivierten Codeinterpreter. Wenn wir dem Assistenten eine mathematische Frage stellen, übersetzt dieser die Frage in Python-Code und führt den Code in der Sandbox-Umgebung aus, um die Antwort auf die Frage zu finden. Der Code, den das Modell erstellt und testet, um zu einer Antwort zu gelangen, lautet:

from sympy import symbols, Eq, solve  
  
# Define the variable  
x = symbols('x')  
  
# Define the equation  
equation = Eq(3*x + 11, 14)  
  
# Solve the equation  
solution = solve(equation, x)  
solution

Es ist wichtig zu beachten, dass der Codeinterpreter das Modell zwar in die Lage versetzt, auf komplexere Abfragen zu reagieren, indem er die Fragen in Code konvertiert und diesen iterativ in einer Python-Sandbox ausführt, bis er eine Lösung findet. Dennoch müssen Sie die Antwort überprüfen, um sicherzustellen, dass das Modell Ihre Frage korrekt in eine gültige Codedarstellung übersetzt hat.

Bereinigen von Ressourcen

Wenn Sie eine Azure OpenAI-Ressource bereinigen und entfernen möchten, können Sie die Ressource selbst oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Siehe auch

Referenzdokumentation | Quellcode | Paket (NuGet)

Voraussetzungen

Einrichten

Erstellen einer neuen .NET Core-Anwendung

  1. Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen azure-openai-quickstart:

    dotnet new console -n azure-openai-assistants-quickstart

  2. Wechseln Sie in das Verzeichnis des neu erstellten App-Ordners, und erstellen Sie die App mit dem Befehl dotnet build:

    dotnet build

    Die Buildausgabe sollte keine Warnungen oder Fehler enthalten.

    ...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

  3. Installieren Sie die OpenAI .NET-Clientbibliothek mit dem Befehl dotnet add package:

    dotnet add package Azure.AI.OpenAI --prerelease

Abrufen von Schlüssel und Endpunkt

Für erfolgreiche Azure OpenAI-Aufrufe benötigen Sie einen Endpunkt und einen Schlüssel.

Variablenname Wert
ENDPOINT Der Dienstendpunkt befindet sich im Abschnitt Schlüssel und Endpunkt, wenn Sie Ihre Ressource aus dem Azure-Portal untersuchen. Alternativ können Sie den Endpunkt über die Seite Bereitstellungen in Azure KI Studio finden. Ein Beispielendpunkt ist https://docs-test-001.openai.azure.com/.
API-KEY Diesen Wert finden Sie im Abschnitt Schlüssel und Endpunkt, wenn Sie die Ressource über das Azure-Portal untersuchen. Sie können KEY1 oder KEY2 verwenden.

Wechseln Sie zu Ihrer Ressource im Azure-Portal. Den Abschnitt Schlüssel und Endpunkt finden Sie im Abschnitt Ressourcenverwaltung. Kopieren Sie die Werte für Endpunkt und Zugriffsschlüssel, da Sie beide für die Authentifizierung Ihrer API-Aufrufe benötigen. Sie können KEY1 oder KEY2 verwenden. Wenn Sie jederzeit zwei Schlüssel zur Verfügung haben, können Sie die Schlüssel auf sichere Weise rotieren und neu generieren, ohne Dienstunterbrechungen zu verursachen.

Screenshot der Benutzeroberfläche mit der Übersicht über eine Azure OpenAI-Ressource im Azure-Portal, in der die Speicherorte für Endpunkt und Zugriffsschlüssel rot umrandet sind

Umgebungsvariablen

Erstellen und Zuweisen von beständigen Umgebungsvariablen für Ihren Schlüssel und Endpunkt.

Wichtig

Wenn Sie einen API-Schlüssel verwenden, speichern Sie ihn an einer anderen Stelle sicher, z. B. in Azure Key Vault. Fügen Sie den API-Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich zugänglich.

Weitere Informationen zur Sicherheit von KI Services finden Sie unter Authentifizieren von Anforderungen an Azure KI Services.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Die passwortlose Authentifizierung ist sicherer als schlüsselbasierte Alternativen und ist der empfohlene Ansatz für die Verbindung mit Azure-Diensten. Wenn Sie die passwortlose Authentifizierung auswählen, müssen Sie Folgendes ausführen:

  1. Fügen Sie das Paket Azure.Identity hinzu.

    dotnet add package Azure.Identity

  2. Weisen Sie Ihrem Benutzerkonto die Cognitive Services User-Rolle zu. Dies kann im Azure-Portal auf Ihrer OpenAI-Ressource unter Access Control (IAM)>Rollenzuweisung hinzufügen erfolgen.

  3. Melden Sie sich mit Visual Studio oder der Azure CLI über az login in Azure an.

Erstellen des Assistenten

Aktualisieren Sie die Program.cs-Datei mit dem folgenden Code, um einen Assistenten zu erstellen:

using Azure;
using Azure.AI.OpenAI.Assistants;

// Assistants is a beta API and subject to change
// Acknowledge its experimental status by suppressing the matching warning.
string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");

var openAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));

// Use for passwordless auth
//var openAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()); 

FileClient fileClient = openAIClient.GetFileClient();
AssistantClient assistantClient = openAIClient.GetAssistantClient();

// First, let's contrive a document we'll use retrieval with and upload it.
using Stream document = BinaryData.FromString("""
            {
                "description": "This document contains the sale history data for Contoso products.",
                "sales": [
                    {
                        "month": "January",
                        "by_product": {
                            "113043": 15,
                            "113045": 12,
                            "113049": 2
                        }
                    },
                    {
                        "month": "February",
                        "by_product": {
                            "113045": 22
                        }
                    },
                    {
                        "month": "March",
                        "by_product": {
                            "113045": 16,
                            "113055": 5
                        }
                    }
                ]
            }
            """).ToStream();

OpenAIFileInfo salesFile = await fileClient.UploadFileAsync(
    document,
    "monthly_sales.json",
    FileUploadPurpose.Assistants);

// Now, we'll create a client intended to help with that data
AssistantCreationOptions assistantOptions = new()
{
    Name = "Example: Contoso sales RAG",
    Instructions =
        "You are an assistant that looks up sales data and helps visualize the information based"
        + " on user queries. When asked to generate a graph, chart, or other visualization, use"
        + " the code interpreter tool to do so.",
    Tools =
            {
                new FileSearchToolDefinition(),
                new CodeInterpreterToolDefinition(),
            },
    ToolResources = new()
    {
        FileSearch = new()
        {
            NewVectorStores =
                    {
                        new VectorStoreCreationHelper([salesFile.Id]),
                    }
        }
    },
};

Assistant assistant = await assistantClient.CreateAssistantAsync(deploymentName, assistantOptions);

// Create and run a thread with a user query about the data already associated with the assistant
ThreadCreationOptions threadOptions = new()
{
    InitialMessages = { "How well did product 113045 sell in February? Graph its trend over time." }
};

ThreadRun threadRun = await assistantClient.CreateThreadAndRunAsync(assistant.Id, threadOptions);

// Check back to see when the run is done
do
{
    Thread.Sleep(TimeSpan.FromSeconds(1));
    threadRun = assistantClient.GetRun(threadRun.ThreadId, threadRun.Id);
} while (!threadRun.Status.IsTerminal);

// Finally, we'll print out the full history for the thread that includes the augmented generation
AsyncCollectionResult<ThreadMessage> messages
    = assistantClient.GetMessagesAsync(
        threadRun.ThreadId,
        new MessageCollectionOptions() { Order = MessageCollectionOrder.Ascending });

await foreach (ThreadMessage message in messages)
{
    Console.Write($"[{message.Role.ToString().ToUpper()}]: ");
    foreach (MessageContent contentItem in message.Content)
    {
        if (!string.IsNullOrEmpty(contentItem.Text))
        {
            Console.WriteLine($"{contentItem.Text}");

            if (contentItem.TextAnnotations.Count > 0)
            {
                Console.WriteLine();
            }

            // Include annotations, if any.
            foreach (TextAnnotation annotation in contentItem.TextAnnotations)
            {
                if (!string.IsNullOrEmpty(annotation.InputFileId))
                {
                    Console.WriteLine($"* File citation, file ID: {annotation.InputFileId}");
                }
                if (!string.IsNullOrEmpty(annotation.OutputFileId))
                {
                    Console.WriteLine($"* File output, new file ID: {annotation.OutputFileId}");
                }
            }
        }
        if (!string.IsNullOrEmpty(contentItem.ImageFileId))
        {
            OpenAIFileInfo imageInfo = await fileClient.GetFileAsync(contentItem.ImageFileId);
            BinaryData imageBytes = await fileClient.DownloadFileAsync(contentItem.ImageFileId);
            using FileStream stream = File.OpenWrite($"{imageInfo.Filename}.png");
            imageBytes.ToStream().CopyTo(stream);

            Console.WriteLine($"<image: {imageInfo.Filename}.png>");
        }
    }
    Console.WriteLine();
}

Führen Sie die Anwendung mit dem Befehl dotnet run aus:

dotnet run

Die Konsolenausgabe sollte wie folgt aussehen:

[USER]: How well did product 113045 sell in February? Graph its trend over time.

[ASSISTANT]: Product 113045 sold 22 units in February. Let's visualize its sales trend over the given months (January through March).

I'll create a graph to depict this trend.

[ASSISTANT]: <image: 553380b7-fdb6-49cf-9df6-e8e6700d69f4.png>
The graph above visualizes the sales trend for product 113045 from January to March. As seen, the sales peaked in February with 22 units sold, and fluctuated over the period from January (12 units) to March (16 units).

If you need further analysis or more details, feel free to ask!

Bereinigen von Ressourcen

Wenn Sie eine Azure OpenAI-Ressource bereinigen und entfernen möchten, können Sie die Ressource selbst oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Siehe auch

Referenzdokumentation | Quellcode der Bibliothek | Paket (npm) |

Voraussetzungen

Für die kennwortlose Authentifizierung müssen Sie die folgenden Schritte ausführen:

  1. Verwenden Sie das @azure/identity-Paket.
  2. Weisen Sie Ihrem Benutzerkonto die Cognitive Services User-Rolle zu. Navigieren Sie hierzu im Azure-Portal zu Zugriffssteuerung (IAM)>Rollenzuweisungen hinzufügen.
  3. Melden Sie sich mit der Azure CLI an (z. B. az login).

Einrichten

  1. Erstellen Sie einen neuen Ordner assistants-quickstart für die Anwendung, und öffnen Sie Visual Studio Code in diesem Ordner mit dem folgenden Befehl:

    mkdir assistants-quickstart && code assistants-quickstart

  2. Erstellen Sie package.json mit dem folgenden Befehl:

    npm init -y

  3. Aktualisieren Sie package.json mit dem folgenden Befehl auf ECMAScript:

    npm pkg set type=module

  4. Installieren Sie mit dem folgenden Code die Clientbibliothek für OpenAI-Assistenten für JavaScript:

    npm install openai

  5. Für die empfohlene kennwortlose Authentifizierung:

    npm install @azure/identity

Abrufen von Ressourceninformationen

Achtung

Um die empfohlene schlüssellose Authentifizierung mit dem SDK zu verwenden, stellen Sie sicher, dass die Umgebungsvariable AZURE_OPENAI_API_KEY nicht festgelegt ist.

Variablenname Wert
AZURE_OPENAI_ENDPOINT Diesen Wert finden Sie im Abschnitt Schlüssel und Endpunkt, wenn Sie die Ressource über das Azure-Portal untersuchen.
AZURE_OPENAI_DEPLOYMENT_NAME Dieser Wert entspricht dem benutzerdefinierten Namen, den Sie während der Bereitstellung eines Modells für die Bereitstellung ausgewählt haben. Diesen Wert finden Sie unter Ressourcenverwaltung>Modellbereitstellungen im Azure-Portal.
OPENAI_API_VERSION Erfahren Sie mehr über API-Versionen.

Erfahren Sie mehr über schlüssellose Authentifizierung und das Festlegen von Umgebungsvariablen.

Achtung

Legen Sie AZURE_OPENAI_API_KEY bei Verwendung der schlüssellosen Authentifizierung nicht fest.

Erstellen eines Assistenten

In unserem Code geben wir die folgenden Werte an:

Name Beschreibung
Assistentenname Ihr Bereitstellungsname, der einem bestimmten Modell zugeordnet ist.
Anweisungen Anweisungen ähneln Systemmeldungen, die dem Modell Anleitungen dazu geben, wie es sich verhalten soll und auf welche Kontexte es beim Generieren von Antworten verweisen soll. Sie können die Persönlichkeit des Assistenten beschreiben, ihm sagen, was er beantworten soll und was nicht, und ihm sagen, wie Antworten formatiert werden sollen. Sie können auch Beispiele für die Schritte bereitstellen, die es beim Beantworten von Antworten ausführen soll.
Modell Dies ist der Bereitstellungsname.
Codeinterpreter Codeinterpreter bietet Zugriff auf eine Sandbox-Python-Umgebung, mit der das Modell Code testen und ausführen kann.

Extras

Ein einzelner Assistent kann auf bis zu 128 Tools, einschließlich code interpreter, sowie auf alle benutzerdefinierten Tools zugreifen, die Sie über Funktionen erstellen.

  1. Erstellen Sie die Datei index.ts mit dem folgenden Code:

    import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Add `Cognitive Services User` to identity for Azure OpenAI resource
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";

// Get environment variables
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please ensure to set AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_ENDPOINT in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    azureADTokenProvider,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

  2. Erstellen Sie die Datei tsconfig.json, um den TypeScript-Code zu transpilieren, und kopieren Sie den folgenden Code für ECMAScript.

    {
    "compilerOptions": {
      "module": "NodeNext",
      "target": "ES2022", // Supports top-level await
      "moduleResolution": "NodeNext",
      "skipLibCheck": true, // Avoid type errors from node_modules
      "strict": true // Enable strict type-checking options
    },
    "include": ["*.ts"]
}

  3. Transpilieren Sie von TypeScript in JavaScript:

    tsc

  4. Melden Sie sich mithilfe des folgenden Befehls bei Azure an:

    az login

  5. Führen Sie den Code mithilfe des folgenden Befehls aus:

    node index.js

Bereinigen von Ressourcen

Wenn Sie eine Azure OpenAI-Ressource bereinigen und entfernen möchten, können Sie die Ressource selbst oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Beispielcode

Weitere Informationen

Voraussetzungen

Einrichten

Abrufen von Schlüssel und Endpunkt

Um erfolgreich einen Aufruf für Azure OpenAI auszuführen, benötigen Sie Folgendes:

Variablenname Wert
ENDPOINT Der Dienstendpunkt befindet sich im Abschnitt Schlüssel und Endpunkt, wenn Sie Ihre Ressource aus dem Azure-Portal untersuchen. Alternativ können Sie den Endpunkt über die Seite Bereitstellungen in Azure KI Studio finden. Ein Beispielendpunkt ist https://docs-test-001.openai.azure.com/.
API-KEY Diesen Wert finden Sie im Abschnitt Schlüssel und Endpunkt, wenn Sie die Ressource über das Azure-Portal untersuchen. Sie können KEY1 oder KEY2 verwenden.
DEPLOYMENT-NAME Dieser Wert entspricht dem benutzerdefinierten Namen, den Sie während der Bereitstellung eines Modells für die Bereitstellung ausgewählt haben. Diesen Wert finden Sie unter Ressourcenverwaltung>Bereitstellungen im Azure-Portal oder auf der Seite Bereitstellungen in Azure KI Studio.

Wechseln Sie zu Ihrer Ressource im Azure-Portal. Die Werte für Endpunkt und Schlüssel finden Sie im Abschnitt Ressourcenverwaltung. Kopieren Sie die Werte für Endpunkt und Zugriffsschlüssel, da Sie beide für die Authentifizierung Ihrer API-Aufrufe benötigen. Sie können KEY1 oder KEY2 verwenden. Wenn Sie jederzeit zwei Schlüssel zur Verfügung haben, können Sie die Schlüssel auf sichere Weise rotieren und neu generieren, ohne Dienstunterbrechungen zu verursachen.

Screenshot des Übersichtsblatts für eine Azure OpenAI-Ressource im Azure-Portal mit rot umrandeten Speicherort für Endpunkt und Zugriffsschlüssel

Umgebungsvariablen

Erstellen und Zuweisen von beständigen Umgebungsvariablen für Ihren Schlüssel und Endpunkt.

Wichtig

Wenn Sie einen API-Schlüssel verwenden, speichern Sie ihn an einer anderen Stelle sicher, z. B. in Azure Key Vault. Fügen Sie den API-Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich zugänglich.

Weitere Informationen zur Sicherheit von KI Services finden Sie unter Authentifizieren von Anforderungen an Azure KI Services.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

REST-API

Erstellen eines Assistenten

Hinweis

Bei Azure OpenAI erfordert der model-Parameter den Modellimplementierungsnamen. Wenn sich der Name der Modellimplementierung von dem zugrunde liegenden Modellnamen unterscheidet, ändern Sie den Code zu "model": "{your-custom-model-deployment-name}".

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "name": "Math Assist",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-1106-preview"
  }'

Extras

Ein einzelner Assistent kann auf bis zu 128 Tools code interpretersowie auf alle benutzerdefinierten Tools, die Sie über Funktionen erstellen, zugreifen.

Erstellen eines Threads

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d ''

Hinzufügen einer Benutzerfrage zum Thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

Ausführen des Threads

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Abrufen des Ausführungsstatus

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_abc123 \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Antwort des Assistenten

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Verstehen der Ergebnisse

In diesem Beispiel erstellen wir einen Assistenten mit aktivierten Codeinterpreter. Wenn wir dem Assistenten eine mathematische Frage stellen, übersetzt dieser die Frage in Python-Code und führt den Code in der Sandbox-Umgebung aus, um die Antwort auf die Frage zu finden. Der Code, den das Modell erstellt und testet, um zu einer Antwort zu gelangen, lautet:

    from sympy import symbols, Eq, solve  
      
    # Define the variable  
    x = symbols('x')  
      
    # Define the equation  
    equation = Eq(3*x + 11, 14)  
      
    # Solve the equation  
    solution = solve(equation, x)  
    solution

Es ist wichtig zu beachten, dass der Codeinterpreter das Modell zwar in die Lage versetzt, auf komplexere Abfragen zu reagieren, indem er die Fragen in Code konvertiert und diesen iterativ in einer Python-Sandbox ausführt, bis er eine Lösung findet. Dennoch müssen Sie die Antwort überprüfen, um sicherzustellen, dass das Modell Ihre Frage korrekt in eine gültige Codedarstellung übersetzt hat.

Bereinigen von Ressourcen

Wenn Sie eine Azure OpenAI-Ressource bereinigen und entfernen möchten, können Sie die Ressource selbst oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Siehe auch