Trabajar con modelos de finalización de chat

En este artículo, enviarás solicitudes de autocompletado de chat, crearás una conversación de varios turnos y administrarás el presupuesto de tokens de la conversación.

Los modelos de chat son modelos de lenguaje optimizados para interfaces conversacionales. A diferencia de los modelos anteriores de finalización de texto y de salida de texto, los modelos de chat aceptan una transcripción de mensajes y devuelven un mensaje generado por el modelo. Este formato admite conversaciones de varios turnos y escenarios ajenos al chat.

Utiliza el formato de mensaje descrito en este artículo en lugar de dar instrucciones a modelos de chat como harías con los antiguos modelos de finalización. De lo contrario, los modelos pueden producir respuestas verbosas o menos útiles.

Tip

Para las aplicaciones nuevas, considere desarrollar con la Responses API en lugar de Chat Completions. Para actualizar una aplicación existente, consulte Azure OpenAI to Responses and Upgrade your Azure OpenAI app from Chat Completions to the Responses API (Actualización de la aplicación OpenAI desde finalizaciones de chat a la API de respuestas).

Nota

Los modelos de razonamiento, como la serie GPT-5, se comportan de forma diferente en esta API. Usan max_completion_tokens en lugar de max_tokensy no admiten temperature, top_po los parámetros de penalización. En los modelos gpt-5.6 y posteriores, una solicitud de Chat Completions que incluye herramientas de funciones falla a menos que establezca reasoning_effort en none. Use la API de respuestas para llamar a herramientas con modelos de razonamiento. Para obtener más información, consulte los modelos de razonamiento de Azure OpenAI.

Requisitos previos

  • Instale la biblioteca de Python openAI: pip install openai.
  • Para la autenticación de Microsoft Entra ID, instale Azure Identity (pip install azure-identity) y el CLI de Azure. Asigne el Cognitive Services User rol a la cuenta de usuario y, a continuación, ejecute az login.
  • Para el ejemplo de recuento de tokens, instale tiktoken: pip install tiktoken.
  • Si usa claves de API, establezca la variable del entorno AZURE_OPENAI_API_KEY.
  • El SDK de .NET 8.0 o posterior.
  • Para autenticación de Microsoft Entra ID, instale CLI de Azure y asigne el rol Cognitive Services User a su cuenta de usuario.
  • Si usa claves de API, establezca la variable del entorno AZURE_OPENAI_API_KEY.
  • Node.js 22 o posterior.
  • Para Microsoft Entra ID autenticación, instale el CLI de Azure, asigne el Cognitive Services User rol a la cuenta de usuario y, a continuación, ejecute az login.
  • Si usa claves de API, establezca la variable del entorno AZURE_OPENAI_API_KEY.

En los ejemplos de código, reemplace por YOUR-RESOURCE-NAME el nombre del recurso de OpenAI de Azure y YOUR-DEPLOYMENT-NAME por el nombre de implementación del modelo.

Configurar

Guarde cada ejemplo completo como chat.pyy, a continuación, ejecútelo con python chat.py.

Trabajar con modelos de finalización de chat

El siguiente fragmento de código muestra la manera más básica de interactuar con los modelos que usan la API de finalizaciones de chat.

Nota

La API de respuestas usa el mismo estilo de interacción de chat, pero admite las características más recientes que no están disponibles con la API de finalizaciones de chat anteriores.

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)

{
    "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.

Cada respuesta incluye finish_reason. Los valores posibles para finish_reason son:

  • stop: la API devolvió la salida completa del modelo.
  • length: salida incompleta del modelo debido al max_completion_tokens parámetro o al límite del token.
  • content_filter: contenido omitido debido a una marca de filtro de contenido.
  • tool_calls: el modelo denominado herramienta.
  • function_call: el modelo denominado función. Este valor está en desuso.

Para las respuestas de streaming, finish_reason es null hasta que el fragmento final completa la respuesta.

Establezca max_completion_tokens lo suficientemente alto como para la respuesta esperada. Un valor mayor ayuda a evitar que el modelo se detenga antes de que llegue al final del mensaje.

Trabaja con la API de Chat Completions

OpenAI entrenó modelos de finalización de chat para aceptar la entrada en un formato de conversación. El parámetro messages toma una matriz de objetos de mensaje con una conversación organizada por rol. Cuando se usa la API de Python, se usa una lista de diccionarios.

El formato de una finalización básica del chat es:

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

Una conversación con una respuesta de ejemplo seguida de una pregunta tendría el siguiente aspecto:

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."},
]

Rol del sistema

El rol del sistema, también conocido como mensaje del sistema, se incluye al principio de la matriz. Este mensaje proporciona las instrucciones iniciales para el modelo. Puede proporcionar varias informaciones en el rol del sistema, como:

  • Una breve descripción del asistente.
  • Rasgos de personalidad del asistente.
  • Instrucciones o reglas que quiere que siga el asistente.
  • Datos o información necesarios para el modelo, como preguntas relevantes de las Preguntas frecuentes (FAQ).

Personalice el rol del sistema para su caso de uso o incluya instrucciones básicas. El mensaje del sistema es opcional, pero incluye al menos uno básico para obtener los mejores resultados.

Mensajes

Después del rol del sistema, puede incluir una serie de mensajes entre el user y el assistant.

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

Para desencadenar una respuesta del modelo, finalice con un mensaje de usuario para indicar que es el turno del asistente para responder. También se puede incluir una serie de mensajes de ejemplo entre el usuario y el asistente como una forma de realizar un aprendizaje de pocas etapas.

Ejemplos de mensajes de aviso

En la sección siguiente se muestran ejemplos de diferentes estilos de avisos que puede usar con modelos de finalizaciones de chat. Estos ejemplos son solo un punto de partida. Puede experimentar con diferentes avisos para personalizar el comportamiento de sus propios casos de uso.

Ejemplo básico

Si desea que el modelo de finalizaciones de chat se comporte de forma similar a chatgpt.com, puede usar un mensaje básico del sistema, como Assistant is a large language model trained by OpenAI.

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

Ejemplo con instrucciones

En algunos escenarios, es posible que desee dar instrucciones adicionales al modelo para definir límites de protección para lo que el modelo es capaz de hacer.

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?"},
]

Uso de datos para la puesta en tierra

También puede incluir datos o información relevantes en el mensaje del sistema para proporcionar al modelo contexto adicional para la conversación. Si necesita incluir solo una pequeña cantidad de información, puede codificarla de forma rígida en el mensaje del sistema. Si tiene una gran cantidad de datos que el modelo debe tener en cuenta, puede usar embeddings o un producto como Búsqueda de Azure AI para recuperar la información más relevante en el momento de la consulta.

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?"},
]

Aprendizaje de pocas etapas con finalización del chat

También puede dar algunos ejemplos de etapas al modelo. El enfoque para el aprendizaje de pocas etapas ha cambiado ligeramente debido al nuevo formato de solicitud. Ahora puede incluir una serie de mensajes entre el usuario y el asistente en la solicitud como algunos ejemplos de pocas etapas. Al utilizar estos ejemplos, puede preparar respuestas para preguntas comunes a fin de iniciar el modelo o enseñar comportamientos específicos al modelo.

En este ejemplo se muestra cómo usar el aprendizaje de pocas capturas con modelos de finalización de chat actuales, como gpt-5-mini y gpt-5. Experimente con diferentes enfoques para encontrar lo que mejor funciona para su caso de uso.

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."},
]

Usar la finalización del chat para escenarios que no son de chat

La API Chat Completions está diseñada para funcionar con conversaciones de varios turnos, pero también funciona bien en escenarios sin chat.

Por ejemplo, para un escenario de extracción de entidades, puede usar la siguiente indicación:

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?"},
]

Creación de un bucle de conversación básico

Los ejemplos anteriores muestran la mecánica básica de interactuar con la API de finalizaciones de chat. En este ejemplo se muestra cómo crear un bucle de conversación que realice las siguientes acciones:

  • Recibe continuamente la entrada de la consola y le da formato de forma adecuada como parte de la lista de mensajes como contenido del rol de usuario.
  • Genera respuestas que se imprimen en la consola y se les da formato y se agregan a la lista de mensajes como contenido del rol de asistente.

Cada vez que haga una nueva pregunta, la solicitud envía la transcripción de conversación en ejecución junto con la pregunta más reciente. Dado que el modelo no tiene memoria, envíe una transcripción actualizada con cada pregunta o el modelo pierda el contexto de las preguntas y respuestas anteriores.

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")

Al ejecutar el código anterior, obtendrá una ventana de consola en blanco. Escriba la primera pregunta en la ventana y, a continuación, seleccione la Enter clave. Una vez que se devuelva la respuesta, puede repetir el proceso y realizar preguntas.

Administrar conversaciones

El ejemplo anterior se ejecuta hasta alcanzar el límite de tokens del modelo (ventana de contexto). Con cada pregunta y respuesta recibida, la messages lista crece de tamaño. El recuento combinado de tokens de tu messages, sumado a los tokens de salida solicitados, debe permanecer dentro del límite del modelo o la solicitud fallará. Consulte la página modelos para ver los límites de token actuales.

Es responsabilidad suya asegurarse de que el aviso y la finalización se encuentran dentro del límite de tokens. Para conversaciones más largas, debe realizar un seguimiento del recuento de tokens y enviar solo al modelo una solicitud que se encuentre dentro del límite. Como alternativa, con la API de respuestas puede hacer que la API controle el truncamiento o la administración del historial de conversaciones.

En el ejemplo de código siguiente se usa la biblioteca tiktoken de OpenAI para recortar una conversación en un umbral de demostración de 4096 tokens. Establezca token_limit en la ventana de contexto del modelo implementado para su uso en producción.

Es posible que tenga que actualizar tiktoken ejecutando pip install --upgrade tiktoken.

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")

En este ejemplo, una vez alcanzado el recuento de tokens, se quitan los mensajes más antiguos de la transcripción de conversación. Para mejorar la eficacia, del se usa en lugar de pop(). Empezamos en el índice 1 para conservar siempre el mensaje del sistema y quitar solo los mensajes de usuario o asistente. Con el tiempo, este método de administración de la conversación puede hacer que la calidad de la conversación se degrada a medida que el modelo pierde gradualmente el contexto de las partes anteriores de la conversación.

Un enfoque alternativo consiste en limitar la duración de la conversación a la longitud máxima del token o a un número específico de turnos. Una vez alcanzado el límite máximo de tokens, el modelo perdería el contexto si tuviera que permitir que la conversación continúe. Puede pedir al usuario que inicie una nueva conversación y borre la lista de mensajes para iniciar una nueva conversación con el límite de tokens completo disponible.

La parte de recuento de tokens del código que se mostró anteriormente es una versión simplificada de uno de los ejemplos del libro de recetas de OpenAI.

Solución de problemas

No se pudo crear la finalización porque el modelo generó una salida Unicode no válida

  • Código de error: 500
  • Mensaje de error:500 - InternalServerError: Error code: 500 - {"error": {"message": "Failed to create completion as the model generated invalid Unicode output"}}
  • Solución alternativa: Reduzca la temperatura del aviso a menos de 1 y use un cliente con lógica de reintento. Volver a intentar la solicitud suele funcionar.

Errores comunes

  • 401/403 (autenticación): compruebe la clave de API o confirme que tiene acceso Microsoft Entra ID al recurso de OpenAI de Azure.
  • 400/404 (no se encontró la implementación): confirme que model coincide con el nombre de la implementación.
  • Dirección URL no válida: confirme que base_url termina con /openai/v1/.

Configurar

  1. Cree una nueva aplicación de consola de .NET:

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

  2. Instale los paquetes NuGet necesarios:

    dotnet add package OpenAI
dotnet add package Azure.Identity

    El paquete openAI es estable. Los ejemplos de Microsoft Entra ID usan un constructor de autenticación personalizado experimental y suprimen la OPENAI001 advertencia.

  3. Para la autenticación sin claves con Microsoft Entra ID, inicie sesión en Azure:

    az login

Trabajar con modelos de finalización de chat

El siguiente fragmento de código muestra la manera más básica de interactuar con los modelos que usan la API de finalizaciones de chat.

Nota

La API de respuestas usa el mismo estilo de interacción de chat, pero admite las características más recientes que no se admiten con la API de finalizaciones de chat anteriores.

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);

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.

Cada respuesta incluye un FinishReason. Los valores posibles para FinishReason son:

  • Stop: la API devolvió la salida completa del modelo.
  • Longitud: salida incompleta del modelo debido al MaxOutputTokenCount parámetro o al límite del token.
  • ContentFilter: contenido omitido debido a una marca de filtro de contenido.
  • ToolCalls: el modelo denominado herramienta.
  • FunctionCall: modelo denominado función. Este valor está en desuso.

Establezca MaxOutputTokenCount lo suficientemente alto como para la respuesta esperada. Un valor mayor ayuda a evitar que el modelo se detenga antes de que llegue al final del mensaje.

Trabaja con la API de Chat Completions

OpenAI entrenó modelos de finalización de chat para aceptar la entrada en un formato de conversación. El parámetro messages toma una matriz de objetos de mensaje con una conversación organizada por rol. Cuando se usa el SDK de .NET, se usan clases de mensajes fuertemente tipadas para cada rol.

El formato de una finalización básica del chat es:

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

Una conversación con una respuesta de ejemplo seguida de una pregunta tendría el siguiente aspecto:

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.")

Rol del sistema

El rol del sistema, también conocido como mensaje del sistema, se incluye al principio de la matriz. Este mensaje proporciona las instrucciones iniciales para el modelo. Puede proporcionar varias informaciones en el rol del sistema, como:

  • Una breve descripción del asistente.
  • Rasgos de personalidad del asistente.
  • Instrucciones o reglas que quiere que siga el asistente.
  • Datos o información necesarios para el modelo, como preguntas relevantes de las Preguntas frecuentes (FAQ).

Personalice el rol del sistema para su caso de uso o incluya instrucciones básicas. El mensaje del sistema es opcional, pero incluye al menos uno básico para obtener los mejores resultados.

Mensajes

Después del rol del sistema, puede incluir una serie de mensajes entre el user y el assistant.

new UserChatMessage("What is thermodynamics?")

Para desencadenar una respuesta del modelo, finalice con un mensaje de usuario para indicar que es el turno del asistente para responder. También se puede incluir una serie de mensajes de ejemplo entre el usuario y el asistente como una forma de realizar un aprendizaje de pocas etapas.

Ejemplos de mensajes de aviso

En la sección siguiente se muestran ejemplos de diferentes estilos de avisos que puede usar con modelos de finalizaciones de chat. Estos ejemplos son solo un punto de partida. Puede experimentar con diferentes avisos para personalizar el comportamiento de sus propios casos de uso.

Ejemplo básico

Si desea que el modelo de finalizaciones de chat se comporte de forma similar a chatgpt.com, puede usar un mensaje básico del sistema, como Assistant is a large language model trained by OpenAI.

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

Ejemplo con instrucciones

En algunos escenarios, es posible que desee dar instrucciones adicionales al modelo para definir límites de protección para lo que el modelo es capaz de hacer.

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?")

Uso de datos para la puesta en tierra

También puede incluir datos o información relevantes en el mensaje del sistema para proporcionar al modelo contexto adicional para la conversación. Si necesita incluir solo una pequeña cantidad de información, puede codificarla de forma rígida en el mensaje del sistema. Si tiene una gran cantidad de datos que el modelo debe tener en cuenta, puede usar embeddings o un producto como Búsqueda de Azure AI para recuperar la información más relevante en el momento de la consulta.

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?")

Aprendizaje de pocas etapas con finalización del chat

También puede dar algunos ejemplos de etapas al modelo. Puede incluir una serie de mensajes entre el usuario y el asistente en la indicación como ejemplos. Al utilizar estos ejemplos, puede preparar respuestas para preguntas comunes a fin de iniciar el modelo o enseñar comportamientos específicos al modelo.

En este ejemplo se usan modelos de finalización de chat actuales, como gpt-5-mini y gpt-5.

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.")

Usar la finalización del chat para escenarios que no son de chat

La API Chat Completions está diseñada para funcionar con conversaciones de varios turnos, pero también funciona bien en escenarios sin chat.

Por ejemplo, para un escenario de extracción de entidades, puede usar la siguiente indicación:

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?")

Creación de un bucle de conversación básico

Los ejemplos anteriores muestran la mecánica básica de interactuar con la API de finalizaciones de chat. En este ejemplo se muestra cómo crear un bucle de conversación que realice las siguientes acciones:

  • Recibe continuamente la entrada de la consola y le da formato de forma adecuada como parte de la lista de mensajes como contenido del rol de usuario.
  • Genera respuestas que se imprimen en la consola y se les da formato y se agregan a la lista de mensajes como contenido del rol de asistente.

Cada vez que haga una nueva pregunta, la solicitud envía la transcripción de conversación en ejecución junto con la pregunta más reciente. Dado que el modelo no tiene memoria, envíe una transcripción actualizada con cada pregunta o el modelo pierda el contexto de las preguntas y respuestas anteriores.

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");
}

Al ejecutar el código anterior, obtendrá una ventana de consola en blanco. Escriba la primera pregunta en la ventana y, a continuación, seleccione la Enter clave. Una vez que se devuelva la respuesta, puede repetir el proceso y realizar preguntas.

Administrar conversaciones

El ejemplo anterior se ejecuta hasta que se alcanza el límite de tokens del modelo (ventana de contexto). Con cada pregunta y respuesta recibida, la conversation lista crece de tamaño. El recuento de tokens combinado de los mensajes más los tokens de salida solicitados deben permanecer dentro del límite del modelo o se produce un error en la solicitud. Consulte la página modelos para ver los límites de token actuales.

Es responsabilidad suya asegurarse de que el aviso y la finalización se encuentran dentro del límite de tokens. Para conversaciones más largas, debe realizar un seguimiento del recuento de tokens y enviar solo al modelo una solicitud que se encuentre dentro del límite. Como alternativa, con la API de respuestas puede hacer que la API controle el truncamiento y la administración del historial de conversaciones.

En el ejemplo de código siguiente se recorta la conversación en un umbral de demostración de 4096 tokens. Establezca TokenLimit en la ventana de contexto del modelo implementado para su uso en producción. El ejemplo elimina los mensajes no pertenecientes al sistema más antiguos para mantener la conversación dentro de unos límites.

Instale los paquetes Microsoft.ML.Tokenizers y Microsoft.ML.Tokenizers.Data.O200kBase para un recuento preciso de tokens:

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");
}

En este ejemplo, una vez alcanzado el recuento de tokens, se quitan los mensajes más antiguos de la transcripción de conversación. Siempre conservamos el mensaje del sistema y solo quitamos mensajes de usuario o asistente. Con el tiempo, este método de administración de la conversación puede hacer que la calidad de la conversación se degrada a medida que el modelo pierde gradualmente el contexto de las partes anteriores de la conversación.

Un enfoque alternativo consiste en limitar la duración de la conversación a la longitud máxima del token o a un número específico de turnos. Una vez alcanzado el límite máximo de tokens, el modelo perdería el contexto si tuviera que permitir que la conversación continúe. Puede pedir al usuario que inicie una nueva conversación y borre la lista de mensajes para iniciar una nueva conversación con el límite de tokens completo disponible.

Solución de problemas

No se pudo crear la finalización porque el modelo generó una salida Unicode no válida

  • Código de error: 500
  • Mensaje de error:500 - InternalServerError: Error code: 500 - {"error": {"message": "Failed to create completion as the model generated invalid Unicode output"}}
  • Solución alternativa: Establezca Temperature en ChatCompletionOptions menos de 1 y use un cliente con lógica de reintento. Volver a intentar la solicitud suele funcionar.

Errores comunes

  • 401/403 (autenticación): compruebe la clave de API o confirme que tiene acceso Microsoft Entra ID al recurso Azure OpenAI.
  • 400/404 (no se encontró la implementación): confirme que el nombre del modelo pasado al constructor coincide con el ChatClient nombre de implementación.
  • Punto de conexión no válido: confirme que el Endpoint URI de OpenAIClientOptions apunta a https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/.

Configurar

  1. Instale Node.js 22 o posterior.

  2. Cree un proyecto de TypeScript e instale los paquetes necesarios.

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

  3. Guarde cada ejemplo completo como chat.tsy, a continuación, ejecútelo.

    npx tsx chat.ts

Trabajar con modelos de finalización de chat

En los ejemplos siguientes se muestra la manera básica de interactuar con los modelos que usan la API de finalizaciones de chat.

Nota

La API de respuestas usa el mismo estilo de interacción de chat, pero admite las características más recientes que no están disponibles con la API de finalizaciones de chat anteriores.

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}`);

La siguiente salida es representativa. La redacción exacta puede variar:

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

Para ver el patrón completo del cliente Azure OpenAI v1, consulte el ejemplo de Azure Chat Completions de OpenAI Node.

Cada respuesta incluye finish_reason. Los valores posibles son:

  • stop: la API devolvió la salida completa del modelo.
  • length: El modelo se detuvo debido a max_completion_tokens o al límite de tokens.
  • content_filter: Un filtro de contenido ha omitido contenido.
  • tool_calls: el modelo denominado herramienta.
  • function_call: el modelo denominado función. Este valor está en desuso.

Para las respuestas de streaming, finish_reason es null hasta que el fragmento final completa la respuesta.

Establezca max_completion_tokens lo suficientemente alto como para la respuesta esperada. Un valor mayor ayuda a evitar que el modelo se detenga antes de que llegue al final del mensaje.

Trabaja con la API de Chat Completions

Los modelos de finalización de chat aceptan la entrada con formato de conversación. El messages parámetro toma una matriz de objetos de mensaje con una conversación organizada por rol. Escriba la matriz como OpenAI.Chat.ChatCompletionMessageParam[] cuando la defina fuera de la solicitud.

El formato de una finalización básica del chat es:

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

Una conversación con una respuesta de ejemplo seguida de una pregunta tiene este aspecto:

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." },
];

Rol del sistema

Incluya el rol del sistema, también conocido como mensaje del sistema, al principio de la matriz. Este mensaje proporciona las instrucciones iniciales para el modelo. Puede definir el propósito, el comportamiento, las reglas o los datos de base del asistente.

El mensaje del sistema es opcional, pero incluye al menos uno básico para obtener los mejores resultados.

Mensajes

Después del rol del sistema, incluye una serie de mensajes entre el user y el assistant:

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

Termine con un mensaje de usuario para indicar que es el turno del asistente para responder. También puede incluir mensajes de ejemplo entre el usuario y el asistente para el aprendizaje de pocas capturas.

Ejemplos de mensajes de aviso

Utilice estos ejemplos como puntos de partida para las indicaciones que puede adaptar a su aplicación.

Ejemplo básico

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

Ejemplo con instrucciones

Use el mensaje del sistema para definir límites para las respuestas del modelo:

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?" },
];

Uso de datos para la puesta en tierra

Incluya una pequeña cantidad de datos relevantes en el mensaje del sistema para fundamentar la respuesta del modelo:

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?" },
];

Para conjuntos de datos de entrenamiento más grandes, utiliza embeddings o Búsqueda de Azure AI para recuperar información relevante en el momento de la solicitud.

Uso del aprendizaje en pocas etapas

Incluya mensajes de usuario y asistente de ejemplo antes de la pregunta final:

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?" },
];

Usar la finalización del chat para escenarios que no son de chat

La API de finalizaciones de chat también admite tareas que no son de chat, como la extracción de entidades:

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.",
  },
];

Creación de un bucle de conversación básico

En el ejemplo siguiente se leen las preguntas de la consola, se envía la conversación completa al modelo y se agrega cada respuesta al historial de conversaciones. Dado que el modelo no tiene memoria, envíe el historial actualizado con cada solicitud.

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();

Cuando ejecutes el código, introduce una pregunta en el indicador Q:. Escriba una línea en blanco para cerrar la aplicación.

Administrar conversaciones

El bucle de conversación se ejecuta hasta que la conversación alcanza la ventana de contexto del modelo. El recuento de tokens combinado de messages y la salida solicitada deben permanecer dentro del límite del modelo. Para conocer los límites de token actuales, consulte la página modelos. El SDK de Node.js de OpenAI informa sobre el uso de tokens después de cada solicitud a través de response.usage, pero no incluye un tokenizador para estimar la próxima solicitud. Para calcular el uso de tokens antes de una solicitud, elija un tokenizador que admita el modelo y la codificación, y evalúelo antes de la adopción.

Para conversaciones más largas, use uno de estos enfoques:

  • Elimine los turnos completos más antiguos del usuario y del asistente, conservando el mensaje del sistema. Mantén un margen de seguridad conservador, ya que el recuento de caracteres o de turnos no corresponde exactamente al recuento de tokens.
  • Inicie una nueva conversación después de un número fijo de turnos.
  • Use la API de respuestas, que admite el estado y el truncamiento de las conversaciones administradas por el servidor.

Solución de problemas

No se pudo crear la finalización porque el modelo generó una salida Unicode no válida

  • Código de error: 500
  • Mensaje de error:Failed to create completion as the model generated invalid Unicode output
  • Solución alternativa: Para los modelos que lo admiten, establezca en temperature menor que 1. El SDK de Nodo openAI reintenta los errores de conexión y los errores HTTP seleccionados dos veces de forma predeterminada. Establezca maxRetries en el OpenAI cliente para cambiar este comportamiento.

Errores comunes

  • 401/403 (autenticación): compruebe la clave de API o confirme que la identidad con sesión iniciada puede acceder al recurso Azure OpenAI.
  • 400/404 (no se encontró la implementación): confirme que model coincide con el nombre de la implementación.
  • Dirección URL no válida: confirme que baseURL termina con /openai/v1/.

Contenido relacionado

  • Last updated on