Arbeiten mit Modellen zur Chat-Vervollständigung

• Installieren Sie die OpenAI-Python-Bibliothek: pip install openai.
• Installieren Sie für Microsoft Entra ID Authentifizierung Azure Identity (pip install azure-identity) und die Azure CLI. Weisen Sie Ihrem Benutzerkonto die Rolle Cognitive Services User zu und führen Sie dann az login aus.
• Installieren Sie für das Tokenzählungsbeispiel tiktoken: pip install tiktoken.
• Wenn Sie API-Schlüssel verwenden, legen Sie die Umgebungsvariable AZURE_OPENAI_API_KEY fest.

• Die .NET 8.0 SDK oder höher.
• Installieren Sie für Microsoft Entra ID Authentifizierung die Azure CLI, und weisen Sie Ihrem Benutzerkonto die Rolle Cognitive Services User zu.
• Wenn Sie API-Schlüssel verwenden, legen Sie die Umgebungsvariable AZURE_OPENAI_API_KEY fest.

• Node.js 22 oder höher.
• Installieren Sie für die Microsoft Entra ID-Authentifizierung die Azure CLI, weisen Sie Ihrem Benutzerkonto die Cognitive Services User-Rolle zu, und führen Sie dann az login aus.
• Wenn Sie API-Schlüssel verwenden, legen Sie die Umgebungsvariable AZURE_OPENAI_API_KEY fest.

Einrichten

Speichern Sie jedes vollständige Beispiel als chat.py, und führen Sie es dann mit python chat.py.

Arbeiten mit Modellen zur Chat-Vervollständigung

Der folgende Codeausschnitt zeigt die grundlegendste Methode für die Interaktion mit Modellen, die die Chat-Abschluss-API verwenden.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

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

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

response = client.chat.completions.create(
    model="YOUR-DEPLOYMENT-NAME",  # Replace with your model deployment name.
    messages=[
        {"role": "system", "content": "Assistant is a large language model trained by OpenAI."},
        {"role": "user", "content": "Who were the founders of Microsoft?"}
    ]
)

#print(response)
print(response.model_dump_json(indent=2))
print(response.choices[0].message.content)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

response = client.chat.completions.create(
    model="YOUR-DEPLOYMENT-NAME",  # Replace with your model deployment name.
    messages=[
        {"role": "system", "content": "Assistant is a large language model trained by OpenAI."},
        {"role": "user", "content": "Who were the founders of Microsoft?"}
    ]
)

#print(response)
print(response.model_dump_json(indent=2))
print(response.choices[0].message.content)

{
    "id": "chatcmpl-8GHoQAJ3zN2DJYqOFiVysrMQJfe1P",
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "Microsoft was founded by Bill Gates and Paul Allen. They established the company on April 4, 1975. Bill Gates served as the CEO of Microsoft until 2000 and later as Chairman and Chief Software Architect until his retirement in 2008, while Paul Allen left the company in 1983 but remained on the board of directors until 2000.",
                "role": "assistant"
            },
            "content_filter_results": {
                "hate": {
                    "filtered": false,
                    "severity": "safe"
                },
                "self_harm": {
                    "filtered": false,
                    "severity": "safe"
                },
                "sexual": {
                    "filtered": false,
                    "severity": "safe"
                },
                "violence": {
                    "filtered": false,
                    "severity": "safe"
                }
            }
        }
    ],
    "created": 1698892410,
    "model": "gpt-4o",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 73,
        "prompt_tokens": 29,
        "total_tokens": 102
    },
    "prompt_filter_results": [
        {
            "prompt_index": 0,
            "content_filter_results": {
                "hate": {
                    "filtered": false,
                    "severity": "safe"
                },
                "self_harm": {
                    "filtered": false,
                    "severity": "safe"
                },
                "sexual": {
                    "filtered": false,
                    "severity": "safe"
                },
                "violence": {
                    "filtered": false,
                    "severity": "safe"
                }
            }
        }
    ]
}
Microsoft was founded by Bill Gates and Paul Allen. They established the company on April 4, 1975. Bill Gates served as the CEO of Microsoft until 2000 and later as Chairman and Chief Software Architect until his retirement in 2008, while Paul Allen left the company in 1983 but remained on the board of directors until 2000.

Jede Antwort enthält finish_reason. Folgende Werte finish_reason sind möglich:

• stop: API hat die vollständige Modellausgabe zurückgegeben.
• length: Unvollständige Modellausgabe aufgrund des max_completion_tokens Parameters oder des Tokenlimits.
• content_filter: Ausgelassener Inhalt aufgrund eines Inhaltsfilterflags.
• tool_calls: Das Modell, das als Tool bezeichnet wird.
• function_call: Das Modell, das als Funktion bezeichnet wird. Dieser Wert ist veraltet.

Für Streaming-Antworten ist finish_reasonnull, bis der letzte Chunk die Antwort vervollständigt.

Legen Sie max_completion_tokens für die erwartete Antwort hoch genug fest. Ein höherer Wert verhindert, dass das Modell angehalten wird, bevor es das Ende der Nachricht erreicht.

Arbeiten mit der Chat-Completions-API

OpenAI trainierte Chatabschlussmodelle, um Eingaben zu akzeptieren, die als Unterhaltung formatiert sind. Der Parameter "Nachrichten" akzeptiert ein Array von Nachrichtenobjekten, wobei die Unterhaltung nach Rolle organisiert ist. Wenn Sie die Python-API verwenden, wird eine Liste der Wörterbücher verwendet.

Das Format eines einfachen Chatabschlusses lautet:

messages = [
    {"role": "system", "content": "Provide context or instructions to the model."},
    {"role": "user", "content": "The user's message goes here."},
]

Eine Unterhaltung mit einer Beispielantwort gefolgt von einer Frage würde wie folgt aussehen:

messages = [
    {"role": "system", "content": "Provide context or instructions to the model."},
    {"role": "user", "content": "Example question goes here."},
    {"role": "assistant", "content": "Example answer goes here."},
    {"role": "user", "content": "First question for the model to answer."},
]

Systemrolle

Die Systemrolle, auch als Systemmeldung bezeichnet, befindet sich am Anfang des Arrays. Diese Meldung enthält die anfänglichen Anweisungen für das Modell. Sie können verschiedene Informationen in der Systemrolle bereitstellen, z. B.:

• Eine kurze Beschreibung des Assistenten.
• Persönlichkeitsmerkmale des Assistenten.
• Anweisungen oder Regeln, denen der Assistent folgen soll.
• Daten oder Informationen, die für das Modell erforderlich sind, z. B. relevante Fragen aus einer FAQ.

Passen Sie die Systemrolle für Ihren Anwendungsfall an, oder fügen Sie grundlegende Anweisungen ein. Die Systemmeldung ist optional, enthält jedoch mindestens eine einfache Nachricht, um die besten Ergebnisse zu erzielen.

Nachrichten

Nach der Systemrolle können Sie eine Reihe von Nachrichten zwischen dem user und dem assistant einfügen.

message = {"role": "user", "content": "What is thermodynamics?"}

Um eine Antwort des Modells auszulösen, sollten Sie mit einer Benutzernachricht enden, die angibt, dass nun der Assistent antworten soll. Sie können auch verschiedene Beispielnachrichten zwischen Benutzer/Benutzerin und Assistent einschließen, um Few-Shot-Learning zu verwenden.

Beispiele für Meldungsaufforderungen

Der folgende Abschnitt enthält Beispiele für verschiedene Formatvorlagen von Eingabeaufforderungen, die Sie mit Chatabschlussmodellen verwenden können. Diese Beispiele sind nur ein Ausgangspunkt. Sie können mit verschiedenen Eingabeaufforderungen experimentieren, um das Verhalten für Ihre eigenen Anwendungsfälle anzupassen.

Einfaches Beispiel

Wenn Sie möchten, dass sich ihr Chatvervollständigungsmodell ähnlich wie chatgpt.com verhält, können Sie eine grundlegende Systemnachricht wie Assistant is a large language model trained by OpenAI. verwenden.

messages = [
    {"role": "system", "content": "Assistant is a large language model trained by OpenAI."},
    {"role": "user", "content": "Who were the founders of Microsoft?"},
]

Beispiel mit Anweisungen

In einigen Szenarien möchten Sie dem Modell vielleicht weitere Anweisungen geben, um Schutzmaßnahmen für die Möglichkeiten des Modells festzulegen.

messages = [
    {"role": "system", "content": """Assistant is an intelligent chatbot designed to help users answer tax-related questions.
Instructions: 
- Only answer questions related to taxes. 
- If you're unsure of an answer, say "I don't know" or "I'm not sure" and recommend the IRS website."""},
    {"role": "user", "content": "When are my taxes due?"},
]

Verwenden Sie Daten zur Verankerung

Sie können auch relevante Daten oder Informationen in die Systemmeldung einschließen, um dem Modell zusätzlichen Kontext für die Unterhaltung zu geben. Wenn Sie nur eine kleine Menge an Informationen einschließen müssen, können Sie sie in der Systemmeldung hart codieren. Wenn Sie über eine große Menge an Daten verfügen, die das Modell beachten sollte, können Sie embeddings oder ein Produkt wie Azure KI-Suche verwenden, um die relevantesten Informationen zur Abfragezeit abzurufen.

messages = [
    {"role": "system", "content": """Assistant helps users answer technical questions about Azure OpenAI in Microsoft Foundry Models. Only answer questions using the following context. If the context doesn't contain the answer, say 'I don't know.'

Context:
- Azure OpenAI provides REST API access to OpenAI models, including GPT-5, GPT-4.1, and Embeddings model series.
- Azure OpenAI gives customers advanced language AI with GPT-5, GPT-image, and Embeddings models with the security and enterprise capabilities of Azure. Azure OpenAI co-develops the APIs with OpenAI, ensuring compatibility and a smooth transition between the services.
- At Microsoft, we're committed to advancing AI according to principles that put people first."""},
    {"role": "user", "content": "What is Azure OpenAI?"},
]

Few-Shot-Learning mit Chatvervollständigung

Sie können dem Modell auch einige Few-Shot-Beispiele geben. Der Ansatz für Few-Shot-Learning hat sich aufgrund des neuen Promptformats geringfügig geändert. Sie können jetzt eine Reihe von Nachrichten als Few-Shot-Stichproben zwischen Benutzer/Benutzerin und Assistent in den Prompt einschließen. Mithilfe dieser Beispiele können Sie Antworten auf häufig gestellte Fragen erstellen, um das Modell zu primieren oder bestimmte Verhaltensweisen für das Modell zu vermitteln.

Dieses Beispiel zeigt, wie Sie Few-Shot-Lernen mit aktuellen Chat-Vervollständigungsmodellen wie gpt-5-mini und gpt-5 verwenden. Experimentieren Sie mit verschiedenen Ansätzen, um zu finden, was für Ihren Anwendungsfall am besten geeignet ist.

messages = [
    {"role": "system", "content": "Assistant helps users answer tax-related questions."},
    {"role": "user", "content": "When do I need to file my taxes by?"},
    {"role": "assistant", "content": "Check the current individual filing deadline at https://www.irs.gov/filing/individuals/when-to-file."},
    {"role": "user", "content": "How can I check the status of my tax refund?"},
    {"role": "assistant", "content": "Check your refund status at https://www.irs.gov/refunds."},
]

Verwenden Sie den Chatabschluss in nicht konversationellen Szenarien.

Die Chat Completions API ist für mehrteilige Konversationen ausgelegt, eignet sich aber auch gut für Szenarien ohne Chat.

Für ein Entitätsextraktionsszenario können Sie beispielsweise die folgende Eingabeaufforderung verwenden:

messages = [
    {"role": "system", "content": """You extract entities from text and return them as a JSON object with this format:
{
   "name": "",
   "company": "",
   "phone_number": ""
}"""},
    {"role": "user", "content": "Hello. My name is Robert Smith. I'm calling from Contoso Insurance, Delaware. My colleague mentioned that you are interested in learning about our comprehensive benefits policy. Could you give me a call back at (555) 346-9322 when you get a chance so we can go over the benefits?"},
]

Erstellen einer einfachen Unterhaltungsschleife

Die vorstehenden Beispiele zeigen die grundlegenden Mechanismen der Interaktion mit der Chat-Vervollständigungs-API. In diesem Beispiel wird gezeigt, wie Sie eine Unterhaltungsschleife erstellen, die die folgenden Aktionen ausführt:

• Sie akzeptiert kontinuierlich Konsoleneingaben und formatiert sie korrekt als Teil der Nachrichtenliste als Inhalt der Benutzerrolle.
• Sie gibt Antworten aus, die an die Konsole ausgegeben, formatiert und der Nachrichtenliste als Inhalt der Assistentenrolle hinzugefügt werden.

Jedes Mal, wenn Sie eine neue Frage stellen, sendet die Anforderung das laufende Unterhaltungstranskript zusammen mit der neuesten Frage. Da das Modell keinen Arbeitsspeicher hat, senden Sie ein aktualisiertes Transkript mit jeder Frage, oder das Modell verliert den Kontext früherer Fragen und Antworten.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

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

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

conversation = [{"role": "system", "content": "You are a helpful assistant."}]

while True:
    user_input = input("Q:")
    conversation.append({"role": "user", "content": user_input})

    response = client.chat.completions.create(
        model="YOUR-DEPLOYMENT-NAME",  # Replace with your model deployment name.
        messages=conversation
    )

    conversation.append({"role": "assistant", "content": response.choices[0].message.content})
    print("\n" + response.choices[0].message.content + "\n")

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)

conversation = [{"role": "system", "content": "You are a helpful assistant."}]

while True:
    user_input = input("Q:")
    conversation.append({"role": "user", "content": user_input})

    response = client.chat.completions.create(
        model="YOUR-DEPLOYMENT-NAME",  # Replace with your model deployment name.
        messages=conversation
    )

    conversation.append({"role": "assistant", "content": response.choices[0].message.content})
    print("\n" + response.choices[0].message.content + "\n")

Wenn Sie den vorherigen Code ausführen, erhalten Sie ein leeres Konsolenfenster. Geben Sie Ihre erste Frage in das Fenster ein, und wählen Sie dann den Enter Schlüssel aus. Nachdem die Antwort zurückgegeben wurde, können Sie den Prozess wiederholen und Fragen stellen.

Verwalten von Unterhaltungen

Das vorherige Beispiel läuft, bis Sie die Tokenbegrenzung (Kontextfenster) des Modells erreichen. Sobald jede Frage gestellt und beantwortet wurde, wächst die messages Liste in der Größe. Die kombinierte Tokenanzahl Ihres messages plus der angeforderten Ausgabetoken muss innerhalb des Modellsgrenzwerts bleiben, oder die Anfrage schlägt fehl. Auf der Seite "Modelle " finden Sie aktuelle Tokengrenzwerte.

Es liegt in Ihrer Verantwortung sicherzustellen, dass die Eingabeaufforderung und die Vervollständigung innerhalb des Token-Limits liegen. Dies bedeutet, dass Sie für längere Unterhaltungen die Tokenanzahl nachverfolgen müssen und nur einen Prompt, der innerhalb des Grenzwerts liegt, an das Modell senden dürfen. Alternativ können Sie mit der Antwort-API arbeiten, damit die API das Verkürzen und Verwalten des Gesprächsverlaufs für Sie übernimmt.

Das folgende Codebeispiel verwendet OpenAIs tiktoken-Bibliothek, um eine Konversation bei einem Demonstrationsschwellenwert von 4.096 Token zu kürzen. Legen Sie für die Produktionsverwendung token_limit auf das Kontextfenster Ihres bereitgestellten Modells fest.

Möglicherweise müssen Sie tiktoken aktualisieren, indem Sie pip install --upgrade tiktoken ausführen.

import tiktoken
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

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

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

system_message = {"role": "system", "content": "You are a helpful assistant."}
max_response_tokens = 250
token_limit = 4096
conversation = []
conversation.append(system_message)

def num_tokens_from_messages(messages, model="gpt-4o"):
    """Return the number of tokens used by a list of messages."""
    try:
        encoding = tiktoken.encoding_for_model(model)
    except KeyError:
        print("Warning: model not found. Using o200k_base encoding.")
        encoding = tiktoken.get_encoding("o200k_base")

    if model in {
        "gpt-4o",
        "gpt-4o-mini",
        "gpt-5",
        "gpt-4.1",
        "o1",
        "o1-mini",
        "o3",
        "o3-mini",
        "o4-mini",
    }:
        tokens_per_message = 3
        tokens_per_name = 1

    elif any(model.startswith(prefix) for prefix in [
        "gpt-4o-",
        "gpt-5-",
        "gpt-4.1-",
        "o1-",
        "o3-",
        "o4-mini-",
    ]):
        tokens_per_message = 3
        tokens_per_name = 1
    else:
        raise NotImplementedError(
            f"""num_tokens_from_messages() is not implemented for model {model}. """
        )

    num_tokens = 0
    for message in messages:
        num_tokens += tokens_per_message
        for key, value in message.items():
            num_tokens += len(encoding.encode(value))
            if key == "name":
                num_tokens += tokens_per_name
    num_tokens += 3
    return num_tokens

while True:
    user_input = input("Q:")
    conversation.append({"role": "user", "content": user_input})
    conv_history_tokens = num_tokens_from_messages(conversation, model="gpt-4o")

    while conv_history_tokens + max_response_tokens >= token_limit:
        del conversation[1]
        conv_history_tokens = num_tokens_from_messages(conversation, model="gpt-4o")

    response = client.chat.completions.create(
        model="YOUR-DEPLOYMENT-NAME",
        messages=conversation,
        temperature=0.7,
        max_completion_tokens=max_response_tokens
    )

    conversation.append({"role": "assistant", "content": response.choices[0].message.content})
    print("\n" + response.choices[0].message.content + "\n")

import tiktoken
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)

system_message = {"role": "system", "content": "You are a helpful assistant."}
max_response_tokens = 250
token_limit = 4096
conversation = []
conversation.append(system_message)

def num_tokens_from_messages(messages, model="gpt-4o"):
    """Return the number of tokens used by a list of messages."""
    try:
        encoding = tiktoken.encoding_for_model(model)
    except KeyError:
        print("Warning: model not found. Using o200k_base encoding.")
        encoding = tiktoken.get_encoding("o200k_base")

    if model in {
        "gpt-4o",
        "gpt-4o-mini",
        "gpt-5",
        "gpt-4.1",
        "o1",
        "o1-mini",
        "o3",
        "o3-mini",
        "o4-mini",
    }:
        tokens_per_message = 3
        tokens_per_name = 1

    elif any(model.startswith(prefix) for prefix in [
        "gpt-4o-",
        "gpt-5-",
        "gpt-4.1-",
        "o1-",
        "o3-",
        "o4-mini-",
    ]):
        tokens_per_message = 3
        tokens_per_name = 1
    else:
        raise NotImplementedError(
            f"""num_tokens_from_messages() is not implemented for model {model}. """
        )

    num_tokens = 0
    for message in messages:
        num_tokens += tokens_per_message
        for key, value in message.items():
            num_tokens += len(encoding.encode(value))
            if key == "name":
                num_tokens += tokens_per_name
    num_tokens += 3
    return num_tokens

while True:
    user_input = input("Q:")
    conversation.append({"role": "user", "content": user_input})
    conv_history_tokens = num_tokens_from_messages(conversation, model="gpt-4o")

    while conv_history_tokens + max_response_tokens >= token_limit:
        del conversation[1]
        conv_history_tokens = num_tokens_from_messages(conversation, model="gpt-4o")

    response = client.chat.completions.create(
        model="YOUR-DEPLOYMENT-NAME",
        messages=conversation,
        temperature=0.7,
        max_completion_tokens=max_response_tokens
    )

    conversation.append({"role": "assistant", "content": response.choices[0].message.content})
    print("\n" + response.choices[0].message.content + "\n")

In diesem Beispiel werden nach dem Erreichen der vorgegebenen Tokenanzahl die ältesten Nachrichten im Konversationstranskript entfernt. Aus Effizienzgründen wird del anstelle von pop() verwendet. Wir beginnen mit Index 1, um die Systemnachricht immer beizubehalten und nur Benutzer- oder Assistentennachrichten zu entfernen. Im Laufe der Zeit kann diese Methode zum Verwalten der Unterhaltung dazu führen, dass die Unterhaltungsqualität beeinträchtigt wird, da das Modell allmählich den Kontext der früheren Teile der Unterhaltung verliert.

Ein alternativer Ansatz besteht darin, die Dauer der Unterhaltung auf die maximale Tokenlänge oder eine bestimmte Anzahl von Runden zu beschränken. Nachdem der maximale Tokengrenzwert erreicht wurde, verliert das Modell den Kontext, wenn Sie zulassen würden, dass die Unterhaltung fortgesetzt werden kann. Sie können den Benutzer auffordern, eine neue Unterhaltung zu beginnen und die Nachrichtenliste zu löschen, um eine neue Unterhaltung mit dem vollständigen verfügbaren Tokenlimit zu beginnen.

Der Tokenzählungsteil des zuvor gezeigten Codes ist eine vereinfachte Version eines der OpenAI-Kochbuchbeispiele.

Problembehandlung

Fehler beim Erstellen der Vervollständigung aufgrund ungültiger Unicode-Ausgabe des Modells.

• Fehlercode: 500
• Fehlermeldung:500 - InternalServerError: Error code: 500 - {"error": {"message": "Failed to create completion as the model generated invalid Unicode output"}}
• Problemumgehung: Verringern Sie die Eingabeaufforderungstemperatur auf weniger als 1, und verwenden Sie einen Client mit Wiederholungslogik. Das Wiederholen der Anforderung ist häufig erfolgreich.

Häufige Fehler

• 401/403 (Authentifizierung): Überprüfen Sie Ihren API-Schlüssel, oder bestätigen Sie, dass Sie Microsoft Entra ID Zugriff auf die Azure OpenAI-Ressource haben.
• 400/404 (Bereitstellung nicht gefunden): Vergewissern Sie sich, dass model Ihrem Bereitstellungsnamen entspricht.
• Ungültige URL: Bestätigen Sie, dass base_url mit /openai/v1/ endet.

Einrichten

1. Erstellen Sie eine neue .NET Konsolenanwendung:

   dotnet new console -n chat-completions
   cd chat-completions
   

2. Installieren Sie die erforderlichen NuGet-Pakete:

   dotnet add package OpenAI
   dotnet add package Azure.Identity
   

   Das OpenAI-Paket ist stabil. In den beispielen Microsoft Entra ID wird ein experimenteller benutzerdefinierter Authentifizierungskonstruktor verwendet und die OPENAI001 Warnung unterdrückt.

3. Melden Sie sich bei der schlüssellosen Authentifizierung mit Microsoft Entra ID bei Azure an:

   az login
   

Arbeiten mit Modellen zur Chat-Vervollständigung

Der folgende Codeausschnitt zeigt die grundlegendste Methode für die Interaktion mit Modellen, die die Chat-Abschluss-API verwenden.

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");

ChatClient client = new(
    model: "YOUR-DEPLOYMENT-NAME",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
    }
);

ChatCompletion completion = await client.CompleteChatAsync(
[
    new SystemChatMessage("Assistant is a large language model trained by OpenAI."),
    new UserChatMessage("Who were the founders of Microsoft?"),
]);

Console.WriteLine(completion.Content[0].Text);

using OpenAI;
using OpenAI.Chat;
using System.ClientModel;

ChatClient client = new(
    model: "YOUR-DEPLOYMENT-NAME",
    credential: new ApiKeyCredential(
        Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")),
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
    }
);

ChatCompletion completion = await client.CompleteChatAsync(
[
    new SystemChatMessage("Assistant is a large language model trained by OpenAI."),
    new UserChatMessage("Who were the founders of Microsoft?"),
]);

Console.WriteLine(completion.Content[0].Text);

Microsoft was founded by Bill Gates and Paul Allen. They established the company on April 4, 1975. Bill Gates served as the CEO of Microsoft until 2000 and later as Chairman and Chief Software Architect until his retirement in 2008, while Paul Allen left the company in 1983 but remained on the board of directors until 2000.

Jede Antwort enthält eine FinishReason. Folgende Werte FinishReason sind möglich:

• Stop: Die API hat die vollständige Modellausgabe zurückgegeben.
• Länge: Unvollständige Modellausgabe aufgrund des MaxOutputTokenCount Parameters oder des Tokenlimits.
• ContentFilter: Ausgelassener Inhalt aufgrund eines Inhaltsfilter-Flags.
• ToolCalls: Das Modell, das als Tool bezeichnet wird.
• FunctionCall: Das Modell hat eine Funktion aufgerufen. Dieser Wert ist veraltet.

Legen Sie MaxOutputTokenCount für die erwartete Antwort hoch genug fest. Ein höherer Wert verhindert, dass das Modell angehalten wird, bevor es das Ende der Nachricht erreicht.

Arbeiten mit der Chat-Completions-API

OpenAI trainierte Chatabschlussmodelle, um Eingaben zu akzeptieren, die als Unterhaltung formatiert sind. Der Parameter "Nachrichten" akzeptiert ein Array von Nachrichtenobjekten, wobei die Unterhaltung nach Rolle organisiert ist. Wenn Sie das .NET SDK verwenden, verwenden Sie stark typierte Nachrichtenklassen für jede Rolle.

Das Format eines einfachen Chatabschlusses lautet:

new SystemChatMessage("Provide some context and/or instructions to the model"),
new UserChatMessage("The user's message goes here")

Eine Unterhaltung mit einer Beispielantwort gefolgt von einer Frage würde wie folgt aussehen:

new SystemChatMessage("Provide some context and/or instructions to the model."),
new UserChatMessage("Example question goes here."),
new AssistantChatMessage("Example answer goes here."),
new UserChatMessage("First question/message for the model to actually respond to.")

Systemrolle

Die Systemrolle, auch als Systemmeldung bezeichnet, befindet sich am Anfang des Arrays. Diese Meldung enthält die anfänglichen Anweisungen für das Modell. Sie können verschiedene Informationen in der Systemrolle bereitstellen, z. B.:

• Eine kurze Beschreibung des Assistenten.
• Persönlichkeitsmerkmale des Assistenten.
• Anweisungen oder Regeln, denen der Assistent folgen soll.
• Daten oder Informationen, die für das Modell erforderlich sind, z. B. relevante Fragen aus einer FAQ.

Passen Sie die Systemrolle für Ihren Anwendungsfall an, oder fügen Sie grundlegende Anweisungen ein. Die Systemmeldung ist optional, enthält jedoch mindestens eine einfache Nachricht, um die besten Ergebnisse zu erzielen.

Nachrichten

Nach der Systemrolle können Sie eine Reihe von Nachrichten zwischen dem user und dem assistant einfügen.

new UserChatMessage("What is thermodynamics?")

Um eine Antwort des Modells auszulösen, sollten Sie mit einer Benutzernachricht enden, die angibt, dass nun der Assistent antworten soll. Sie können auch verschiedene Beispielnachrichten zwischen Benutzer/Benutzerin und Assistent einschließen, um Few-Shot-Learning zu verwenden.

Beispiele für Meldungsaufforderungen

Der folgende Abschnitt enthält Beispiele für verschiedene Formatvorlagen von Eingabeaufforderungen, die Sie mit Chatabschlussmodellen verwenden können. Diese Beispiele sind nur ein Ausgangspunkt. Sie können mit verschiedenen Eingabeaufforderungen experimentieren, um das Verhalten für Ihre eigenen Anwendungsfälle anzupassen.

Einfaches Beispiel

Wenn Sie möchten, dass sich ihr Chatvervollständigungsmodell ähnlich wie chatgpt.com verhält, können Sie eine grundlegende Systemnachricht wie Assistant is a large language model trained by OpenAI. verwenden.

new SystemChatMessage("Assistant is a large language model trained by OpenAI."),
new UserChatMessage("Who were the founders of Microsoft?")

Beispiel mit Anweisungen

In einigen Szenarien möchten Sie dem Modell vielleicht weitere Anweisungen geben, um Schutzmaßnahmen für die Möglichkeiten des Modells festzulegen.

new SystemChatMessage(@"Assistant is an intelligent chatbot designed to help users answer their tax related questions.
Instructions:
- Only answer questions related to taxes.
- If you're unsure of an answer, you can say ""I don't know"" or ""I'm not sure"" and recommend users go to the IRS website for more information."),
new UserChatMessage("When are my taxes due?")

Verwenden Sie Daten zur Verankerung

Sie können auch relevante Daten oder Informationen in die Systemmeldung einschließen, um dem Modell zusätzlichen Kontext für die Unterhaltung zu geben. Wenn Sie nur eine kleine Menge an Informationen einschließen müssen, können Sie sie in der Systemmeldung hart codieren. Wenn Sie über eine große Menge an Daten verfügen, die das Modell beachten sollte, können Sie embeddings oder ein Produkt wie Azure KI-Suche verwenden, um die relevantesten Informationen zur Abfragezeit abzurufen.

new SystemChatMessage(@"Assistant is an intelligent chatbot designed to help users answer technical questions about Azure OpenAI in Microsoft Foundry Models. Only answer questions using the context below and if you're not sure of an answer, you can say 'I don't know'.

Context:
- Azure OpenAI provides REST API access to OpenAI models, including GPT-5, GPT-4.1, and Embeddings model series.
- Azure OpenAI gives customers advanced language AI with GPT-5, GPT-image, and Embeddings models with the security and enterprise capabilities of Azure. Azure OpenAI co-develops the APIs with OpenAI, ensuring compatibility and a smooth transition between the services.
- At Microsoft, we're committed to the advancement of AI driven by principles that put people first. Microsoft has made significant investments to help guard against abuse and unintended harm, which includes requiring applicants to show well-defined use cases, incorporating Microsoft's principles for responsible AI use."),
new UserChatMessage("What is Azure OpenAI?")

Few-Shot-Learning mit Chatvervollständigung

Sie können dem Modell auch einige Few-Shot-Beispiele geben. Sie können mehrere Nachrichten als Few-Shot-Beispiele zwischen Benutzenden und dem Assistenten in Prompts einschließen. Mithilfe dieser Beispiele können Sie Antworten auf häufig gestellte Fragen erstellen, um das Modell zu primieren oder bestimmte Verhaltensweisen für das Modell zu vermitteln.

In diesem Beispiel werden aktuelle Chat-Completion-Modelle wie gpt-5-mini und gpt-5 verwendet.

new SystemChatMessage("Assistant is an intelligent chatbot designed to help users answer their tax related questions."),
new UserChatMessage("When do I need to file my taxes by?"),
new AssistantChatMessage("Check the current individual filing deadline at https://www.irs.gov/filing/individuals/when-to-file."),
new UserChatMessage("How can I check the status of my tax refund?"),
new AssistantChatMessage("Check your refund status at https://www.irs.gov/refunds.")

Verwenden Sie den Chatabschluss in nicht konversationellen Szenarien.

Die Chat Completions API ist für mehrteilige Konversationen ausgelegt, eignet sich aber auch gut für Szenarien ohne Chat.

Für ein Entitätsextraktionsszenario können Sie beispielsweise die folgende Eingabeaufforderung verwenden:

new SystemChatMessage(@"You are an assistant designed to extract entities from text. Users will paste in a string of text and you will respond with entities you've extracted from the text as a JSON object. Here's an example of your output format:
{
   ""name"": """",
   ""company"": """",
   ""phone_number"": """"
}"),
new UserChatMessage("Hello. My name is Robert Smith. I'm calling from Contoso Insurance, Delaware. My colleague mentioned that you are interested in learning about our comprehensive benefits policy. Could you give me a call back at (555) 346-9322 when you get a chance so we can go over the benefits?")

Erstellen einer einfachen Unterhaltungsschleife

Die vorstehenden Beispiele zeigen die grundlegenden Mechanismen der Interaktion mit der Chat-Vervollständigungs-API. In diesem Beispiel wird gezeigt, wie Sie eine Unterhaltungsschleife erstellen, die die folgenden Aktionen ausführt:

• Sie akzeptiert kontinuierlich Konsoleneingaben und formatiert sie korrekt als Teil der Nachrichtenliste als Inhalt der Benutzerrolle.
• Sie gibt Antworten aus, die an die Konsole ausgegeben, formatiert und der Nachrichtenliste als Inhalt der Assistentenrolle hinzugefügt werden.

Jedes Mal, wenn Sie eine neue Frage stellen, sendet die Anforderung das laufende Unterhaltungstranskript zusammen mit der neuesten Frage. Da das Modell keinen Arbeitsspeicher hat, senden Sie ein aktualisiertes Transkript mit jeder Frage, oder das Modell verliert den Kontext früherer Fragen und Antworten.

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");

ChatClient client = new(
    model: "YOUR-DEPLOYMENT-NAME",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
    }
);

List<ChatMessage> conversation =
[
    new SystemChatMessage("You are a helpful assistant."),
];

while (true)
{
    Console.Write("Q: ");
    string? userInput = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(userInput)) break;

    conversation.Add(new UserChatMessage(userInput));

    ChatCompletion response = await client.CompleteChatAsync(conversation);
    string assistantMessage = response.Content[0].Text;

    conversation.Add(new AssistantChatMessage(assistantMessage));
    Console.WriteLine($"\n{assistantMessage}\n");
}

using OpenAI;
using OpenAI.Chat;
using System.ClientModel;

ChatClient client = new(
    model: "YOUR-DEPLOYMENT-NAME",
    credential: new ApiKeyCredential(
        Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")),
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
    }
);

List<ChatMessage> conversation =
[
    new SystemChatMessage("You are a helpful assistant."),
];

while (true)
{
    Console.Write("Q: ");
    string? userInput = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(userInput)) break;

    conversation.Add(new UserChatMessage(userInput));

    ChatCompletion response = await client.CompleteChatAsync(conversation);
    string assistantMessage = response.Content[0].Text;

    conversation.Add(new AssistantChatMessage(assistantMessage));
    Console.WriteLine($"\n{assistantMessage}\n");
}

Wenn Sie den vorherigen Code ausführen, erhalten Sie ein leeres Konsolenfenster. Geben Sie Ihre erste Frage in das Fenster ein, und wählen Sie dann den Enter Schlüssel aus. Nachdem die Antwort zurückgegeben wurde, können Sie den Prozess wiederholen und Fragen stellen.

Verwalten von Unterhaltungen

Im vorherigen Beispiel läuft das Modell, bis der Tokengrenzwert (Kontextfenster) erreicht ist. Sobald jede Frage gestellt und beantwortet wurde, wächst die conversation Liste in der Größe. Die kombinierte Tokenanzahl Ihrer Nachrichten sowie die angeforderten Ausgabetoken müssen innerhalb des Grenzwerts des Modells bleiben, oder die Anforderung schlägt fehl. Auf der Seite "Modelle " finden Sie aktuelle Tokengrenzwerte.

Es liegt in Ihrer Verantwortung sicherzustellen, dass die Eingabeaufforderung und die Vervollständigung innerhalb des Token-Limits liegen. Dies bedeutet, dass Sie für längere Unterhaltungen die Tokenanzahl nachverfolgen müssen und nur einen Prompt, der innerhalb des Grenzwerts liegt, an das Modell senden dürfen. Alternativ kann die Reaktions-API für Sie das Abschneiden und Verwalten des Unterhaltungsverlaufs übernehmen.

Das folgende Codebeispiel kürzt die Konversation bei einem Demonstrationsgrenzwert von 4.096 Token. Legen Sie für die Produktionsverwendung TokenLimit auf das Kontextfenster Ihres bereitgestellten Modells fest. Im Beispiel werden die ältesten nicht systemfremden Nachrichten entfernt, um die Unterhaltung in Grenzen zu halten.

Installieren Sie die pakete Microsoft.ML.ML.Tokenizers und Microsoft.ML.Tokenizers.Data.O200kBase für die genaue Tokenzählung:

dotnet add package Microsoft.ML.Tokenizers
dotnet add package Microsoft.ML.Tokenizers.Data.O200kBase

using Azure.Identity;
using Microsoft.ML.Tokenizers;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");

ChatClient client = new(
    model: "YOUR-DEPLOYMENT-NAME",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
    }
);

const int MaxResponseTokens = 250;
const int TokenLimit = 4096;

var tokenizer = TiktokenTokenizer.CreateForModel("gpt-4o");

List<ChatMessage> conversation =
[
    new SystemChatMessage("You are a helpful assistant."),
];

static int CountTokens(TiktokenTokenizer tokenizer, IEnumerable<ChatMessage> messages)
{
    int count = 3; // base overhead for reply priming
    foreach (var message in messages)
    {
        count += 4; // per-message overhead
        string content = message switch
        {
            SystemChatMessage s => s.Content[0].Text ?? string.Empty,
            UserChatMessage u => u.Content[0].Text ?? string.Empty,
            AssistantChatMessage a => a.Content[0].Text ?? string.Empty,
            _ => string.Empty
        };
        count += tokenizer.CountTokens(content);
    }
    return count;
}

while (true)
{
    Console.Write("Q: ");
    string? userInput = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(userInput)) break;

    conversation.Add(new UserChatMessage(userInput));

    int historyTokens = CountTokens(tokenizer, conversation);
    while (historyTokens + MaxResponseTokens >= TokenLimit && conversation.Count > 2)
    {
        conversation.RemoveAt(1); // remove oldest non-system message
        historyTokens = CountTokens(tokenizer, conversation);
    }

    ChatCompletionOptions options = new() { MaxOutputTokenCount = MaxResponseTokens };
    ChatCompletion response = await client.CompleteChatAsync(conversation, options);
    string assistantMessage = response.Content[0].Text;

    conversation.Add(new AssistantChatMessage(assistantMessage));
    Console.WriteLine($"\n{assistantMessage}\n");
}

using Microsoft.ML.Tokenizers;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel;

ChatClient client = new(
    model: "YOUR-DEPLOYMENT-NAME",
    credential: new ApiKeyCredential(
        Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")),
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
    }
);

const int MaxResponseTokens = 250;
const int TokenLimit = 4096;

var tokenizer = TiktokenTokenizer.CreateForModel("gpt-4o");

List<ChatMessage> conversation =
[
    new SystemChatMessage("You are a helpful assistant."),
];

static int CountTokens(TiktokenTokenizer tokenizer, IEnumerable<ChatMessage> messages)
{
    int count = 3; // base overhead for reply priming
    foreach (var message in messages)
    {
        count += 4; // per-message overhead
        string content = message switch
        {
            SystemChatMessage s => s.Content[0].Text ?? string.Empty,
            UserChatMessage u => u.Content[0].Text ?? string.Empty,
            AssistantChatMessage a => a.Content[0].Text ?? string.Empty,
            _ => string.Empty
        };
        count += tokenizer.CountTokens(content);
    }
    return count;
}

while (true)
{
    Console.Write("Q: ");
    string? userInput = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(userInput)) break;

    conversation.Add(new UserChatMessage(userInput));

    int historyTokens = CountTokens(tokenizer, conversation);
    while (historyTokens + MaxResponseTokens >= TokenLimit && conversation.Count > 2)
    {
        conversation.RemoveAt(1); // remove oldest non-system message
        historyTokens = CountTokens(tokenizer, conversation);
    }

    ChatCompletionOptions options = new() { MaxOutputTokenCount = MaxResponseTokens };
    ChatCompletion response = await client.CompleteChatAsync(conversation, options);
    string assistantMessage = response.Content[0].Text;

    conversation.Add(new AssistantChatMessage(assistantMessage));
    Console.WriteLine($"\n{assistantMessage}\n");
}

In diesem Beispiel werden nach dem Erreichen der vorgegebenen Tokenanzahl die ältesten Nachrichten im Konversationstranskript entfernt. Wir behalten die Systemnachricht immer bei und entfernen nur Benutzer- oder Assistentennachrichten. Im Laufe der Zeit kann diese Methode zum Verwalten der Unterhaltung dazu führen, dass die Unterhaltungsqualität beeinträchtigt wird, da das Modell allmählich den Kontext der früheren Teile der Unterhaltung verliert.

Ein alternativer Ansatz besteht darin, die Dauer der Unterhaltung auf die maximale Tokenlänge oder eine bestimmte Anzahl von Runden zu beschränken. Nachdem der maximale Tokengrenzwert erreicht wurde, verliert das Modell den Kontext, wenn Sie zulassen würden, dass die Unterhaltung fortgesetzt werden kann. Sie können den Benutzer auffordern, eine neue Unterhaltung zu beginnen und die Nachrichtenliste zu löschen, um eine neue Unterhaltung mit dem vollständigen verfügbaren Tokenlimit zu beginnen.

Problembehandlung

Fehler beim Erstellen der Vervollständigung aufgrund ungültiger Unicode-Ausgabe des Modells.

• Fehlercode: 500
• Fehlermeldung:500 - InternalServerError: Error code: 500 - {"error": {"message": "Failed to create completion as the model generated invalid Unicode output"}}
• Problemumgehung: Setzen Sie Temperature in ChatCompletionOptions auf einen Wert kleiner als 1 und verwenden Sie einen Client mit Wiederholungslogik. Das Wiederholen der Anforderung ist häufig erfolgreich.

Häufige Fehler

• 401/403 (Authentifizierung): Überprüfen Sie Ihren API-Schlüssel, oder bestätigen Sie, dass Sie Microsoft Entra ID Zugriff auf die Azure OpenAI-Ressource haben.
• 400/404 (Bereitstellung nicht gefunden): Vergewissern Sie sich, dass der an den ChatClient Konstruktor übergebene Modellname ihrem Bereitstellungsnamen entspricht.
• Ungültiger Endpunkt: Bestätigen Sie, dass der Endpoint URI in OpenAIClientOptions auf https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ zeigt.

Einrichten

1. Installieren Sie Node.js 22 oder höher.

2. Erstellen Sie ein TypeScript-Projekt, und installieren Sie die erforderlichen Pakete.

   npm init --yes
   npm install openai @azure/identity
   npm install --save-dev typescript tsx @types/node
   

3. Speichern Sie jedes vollständige Beispiel als chat.ts, und führen Sie es aus.

   npx tsx chat.ts
   

Arbeiten mit Modellen zur Chat-Vervollständigung

Die folgenden Beispiele zeigen die grundlegende Methode zur Interaktion mit Modellen, die die Chat-Vervollständigungs-API verwenden.

import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";
import OpenAI from "openai";

const tokenProvider = getBearerTokenProvider(
  new DefaultAzureCredential(),
  "https://ai.azure.com/.default",
);
const openai = new OpenAI({
  baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  apiKey: tokenProvider,
});

const completion = await openai.chat.completions.create({
  model: "YOUR-DEPLOYMENT-NAME",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Who were the founders of Microsoft?" },
  ],
});

console.log(completion.choices[0]?.message.content);
console.log(`Finish reason: ${completion.choices[0]?.finish_reason}`);

import OpenAI from "openai";

const apiKey = process.env["AZURE_OPENAI_API_KEY"];
if (!apiKey) throw new Error("AZURE_OPENAI_API_KEY is required.");

const openai = new OpenAI({
  baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  apiKey,
});

const completion = await openai.chat.completions.create({
  model: "YOUR-DEPLOYMENT-NAME",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Who were the founders of Microsoft?" },
  ],
});

console.log(completion.choices[0]?.message.content);
console.log(`Finish reason: ${completion.choices[0]?.finish_reason}`);

Die folgende Ausgabe ist ein Beispiel. Der genaue Wortlaut kann variieren:

Microsoft was founded by Bill Gates and Paul Allen.
Finish reason: stop

Das vollständige Azure OpenAI v1-Clientmuster finden Sie im Beispiel "OpenAI Node Azure Chat Completions".

Jede Antwort enthält finish_reason. Mögliche Werte sind:

• stop: Die API hat die vollständige Modellausgabe zurückgegeben.
• length: Das Modell hat aufgrund von max_completion_tokens oder des Token-Limits angehalten.
• content_filter: Ein Inhaltsfilter hat Inhalte ausgelassen.
• tool_calls: Das Modell, das als Tool bezeichnet wird.
• function_call: Das Modell, das als Funktion bezeichnet wird. Dieser Wert ist veraltet.

Für Streaming-Antworten ist finish_reasonnull, bis der letzte Chunk die Antwort vervollständigt.

Legen Sie max_completion_tokens für die erwartete Antwort hoch genug fest. Ein höherer Wert verhindert, dass das Modell angehalten wird, bevor es das Ende der Nachricht erreicht.

Arbeiten mit der Chat-Completions-API

Chatabschlussmodelle akzeptieren Eingaben, die als Unterhaltung formatiert sind. Der messages Parameter verwendet ein Array von Nachrichtenobjekten, bei dem eine Unterhaltung nach Rolle organisiert ist. Geben Sie das Array als OpenAI.Chat.ChatCompletionMessageParam[] an, wenn Sie es außerhalb der Anfrage definieren.

Das Format eines einfachen Chatabschlusses lautet:

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  { role: "system", content: "Provide context or instructions to the model." },
  { role: "user", content: "The user's message goes here." },
];

Eine Unterhaltung mit einer Beispielantwort, gefolgt von einer Frage, sieht wie folgt aus:

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  { role: "system", content: "Provide context or instructions to the model." },
  { role: "user", content: "Example question goes here." },
  { role: "assistant", content: "Example answer goes here." },
  { role: "user", content: "First question for the model to answer." },
];

Systemrolle

Schließen Sie die Systemrolle ein, die auch als Systemmeldung bezeichnet wird, am Anfang des Arrays. Diese Meldung enthält die anfänglichen Anweisungen für das Modell. Es kann den Zweck, das Verhalten, die Regeln oder die Grounding-Daten des Assistenten definieren.

Die Systemmeldung ist optional, enthält jedoch mindestens eine einfache Nachricht, um die besten Ergebnisse zu erzielen.

Nachrichten

Fügen Sie nach der Systemrolle eine Reihe von Nachrichten zwischen dem user und dem assistant ein:

const message: OpenAI.Chat.ChatCompletionUserMessageParam = {
  role: "user",
  content: "What is thermodynamics?",
};

Schließen Sie mit einer Benutzernachricht ab, um zu kennzeichnen, dass der Assistent an der Reihe ist zu antworten. Sie können auch Beispielnachrichten zwischen dem Benutzer und dem Assistenten einfügen, um Few-Shot-Lernen zu ermöglichen.

Beispiele für Meldungsaufforderungen

Verwenden Sie diese Beispiele als Ausgangspunkt für Aufforderungen, die Sie an Ihre Anwendung anpassen können.

Einfaches Beispiel

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Who were the founders of Microsoft?" },
];

Beispiel mit Anweisungen

Verwenden Sie die Systemmeldung, um Grenzen für die Antworten des Modells zu definieren:

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  {
    role: "system",
    content: `You help users answer tax-related questions.
Only answer questions about taxes.
If you don't know an answer, recommend the IRS website.`,
  },
  { role: "user", content: "When are my taxes due?" },
];

Verwenden Sie Daten zur Verankerung

Nehmen Sie eine kleine Menge an relevanten Daten in die Systemnachricht auf, um die Antwort des Modells besser zu fundieren:

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  {
    role: "system",
    content: `Answer only from this context. If the answer isn't present,
say "I don't know."

Context: Azure OpenAI provides REST API access to OpenAI models.`,
  },
  { role: "user", content: "What does Azure OpenAI provide?" },
];

Verwenden Sie für größere Grounding-Datensätze embeddings oder Azure KI-Suche, um bei der Anfrage relevante Informationen abzurufen.

Few-Shot-Lernen verwenden

Beispielnachrichten für Benutzer und Assistenten vor der endgültigen Frage einschließen:

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  { role: "system", content: "You help users answer tax questions." },
  { role: "user", content: "When do I need to file my taxes?" },
  { role: "assistant", content: "Check the current deadline at irs.gov." },
  { role: "user", content: "How can I check my refund status?" },
];

Verwenden Sie den Chatabschluss in nicht konversationellen Szenarien.

Die Chat-Vervollständigungs-API unterstützt auch Nichtchataufgaben, z. B. entitätsextraktion:

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  {
    role: "system",
    content: "Extract names and companies. Return a JSON object.",
  },
  {
    role: "user",
    content: "Robert Smith is calling from Contoso Insurance.",
  },
];

Erstellen einer einfachen Unterhaltungsschleife

Im folgenden Beispiel werden Fragen aus der Konsole gelesen, die vollständige Unterhaltung an das Modell gesendet und jede Antwort zum Unterhaltungsverlauf hinzugefügt. Da das Modell keinen Arbeitsspeicher hat, senden Sie den aktualisierten Verlauf mit jeder Anforderung.

import { stdin, stdout } from "node:process";
import { createInterface } from "node:readline/promises";
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";
import OpenAI from "openai";

const tokenProvider = getBearerTokenProvider(
  new DefaultAzureCredential(),
  "https://ai.azure.com/.default",
);
const openai = new OpenAI({
  baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  apiKey: tokenProvider,
});
const conversation: OpenAI.Chat.ChatCompletionMessageParam[] = [
  { role: "system", content: "You are a helpful assistant." },
];
const consoleInput = createInterface({ input: stdin, output: stdout });

while (true) {
  const question = await consoleInput.question("Q: ");
  if (!question.trim()) break;
  conversation.push({ role: "user", content: question });
  const response = await openai.chat.completions.create({
    model: "YOUR-DEPLOYMENT-NAME",
    messages: conversation,
  });
  const answer =
    response.choices[0]?.message.content ?? "No response returned.";
  conversation.push({ role: "assistant", content: answer });
  console.log(`\n${answer}\n`);
}
consoleInput.close();

Wenn Sie den Code ausführen, geben Sie an der Q: Eingabeaufforderung eine Frage ein. Geben Sie eine leere Zeile ein, um die Anwendung zu schließen.

Verwalten von Unterhaltungen

Die Konversationsschleife läuft, bis die Konversation die Grenzen des Kontextfensters des Modells erreicht. Die kombinierte Tokenanzahl von messages und der angeforderten Ausgabe muss innerhalb des Modelllimits bleiben. Aktuelle Tokenbeschränkungen finden Sie auf der Modellseite. Das OpenAI Node SDK meldet die Tokenverwendung nach jeder Anforderung durch response.usage, enthält aber keinen Tokenizer zum Schätzen der nächsten Anforderung. Um die Tokennutzung vor einer Anforderung zu schätzen, wählen Sie einen Tokenizer aus, der Ihr Modell und die Codierung unterstützt, und bewerten Sie sie vor der Einführung.

Verwenden Sie für längere Unterhaltungen einen der folgenden Ansätze:

• Entfernen Sie die ältesten vollständigen Interaktionsschritte von Benutzer und Assistent unter Beibehaltung der Systemnachricht. Behalten Sie eine großzügige Sicherheitsmarge bei, da die Anzahl von Zeichen oder Sprecherwechseln keine exakten Token-Zahlen darstellen.
• Starten Sie nach einer festgelegten Anzahl von Gesprächswechseln eine neue Unterhaltung.
• Verwenden Sie die Responses API, die serverseitig verwalteten Konversationsstatus und Trunkierung unterstützt.

Problembehandlung

Fehler beim Erstellen der Vervollständigung aufgrund ungültiger Unicode-Ausgabe des Modells.

• Fehlercode: 500
• Fehlermeldung:Failed to create completion as the model generated invalid Unicode output
• Problemumgehung: Setzen Sie temperature für Modelle, die dies unterstützen, auf weniger als 1. Das OpenAI Node SDK ruft Verbindungsfehler und ausgewählte HTTP-Fehler zweimal standardmäßig erneut auf. Legen Sie maxRetries auf dem OpenAI-Client fest, um dieses Verhalten zu ändern.

Häufige Fehler

• 401/403 (Authentifizierung):Überprüfen Sie den API-Schlüssel, oder bestätigen Sie, dass die angemeldete Identität auf die Azure OpenAI-Ressource zugreifen kann.
• 400/404 (Bereitstellung nicht gefunden): Vergewissern Sie sich, dass model der Bereitstellungsname entspricht.
• Ungültige URL: Bestätigen Sie, dass baseURL mit /openai/v1/ endet.