Desarrollo de aplicaciones con modelos y LangChain en Microsoft Foundry (clásico)

LangChain es un ecosistema de desarrolladores que facilita la creación de aplicaciones de razonamiento. Incluye varios componentes, y la mayoría de ellos se pueden usar de forma independiente, por lo que puede elegir y elegir las piezas que necesita.

Puede usar modelos implementados para Microsoft Foundry con LangChain de dos maneras:

En este tutorial se muestra cómo usar el paquete de langchain-azure-ai[v1] con LangChain mediante Azure API de inferencia de modelos de IA. Algunos modelos, como OpenAI, Cohere o Mistral, ofrecen sus propias API y extensiones LangChain. Estas extensiones pueden incluir funcionalidades específicas del modelo y son adecuadas si necesita usarlas. Instale la extensión para el modelo elegido, como langchain-openai o langchain-cohere.

Requisitos previos

Para ejecutar este tutorial, necesita:

• Una cuenta de Azure con una suscripción activa. Si no tiene una, cree una cuenta de free Azure, que incluye una suscripción de evaluación gratuita.

• Rol obligatorio:
  • Propietario o Colaborador en el recurso Foundry o el AI Hub para implementar modelos
  • Azure ai User para usar el modelo en un proyecto Foundry
  • Azure AI Developer para usar el modelo en un proyecto basado en hub

• Una implementación de modelo que admite la API de Inferencia del Modelo. En este artículo se usa Mistral-Large-3.

• Python 3.9 o posterior instalado, incluido pip.

• LangChain instalado. Puede instalarlo mediante el comando siguiente:

  pip install langchain
  

• Instale la integración de Foundry:

  pip install -U langchain-azure-ai[v1]
  

Configuración del entorno

Para usar los modelos de lenguaje implementados en el portal Microsoft Foundry, necesita el punto de conexión y las credenciales para conectarse a él. Siga estos pasos para obtener la información que necesita del modelo que desea usar:

1. Inicie sesión en Microsoft Foundry. Asegúrese de que el interruptor New Foundry esté activado. Estos pasos hacen referencia a Foundry (new).

   

2. Abra el proyecto donde se implementa el modelo, si aún no está abierto.

3. Copie la dirección URL del punto de conexión y la clave.

En este escenario, establezca la dirección URL del punto de conexión y la clave como variables de entorno. (Si el punto de conexión que copió incluye texto adicional después de /models, quítelo para que la dirección URL finalice en /models como se muestra a continuación).

export AZURE_INFERENCE_ENDPOINT="https://<resource>.services.ai.azure.com/models"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

Cree un cliente para conectarse al modelo de chat mediante la AzureAIChatCompletionsModel clase .

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
)

Qué hace este fragmento de código: Crea una instancia de un AzureAIChatCompletionsModel cliente configurado para conectarse al modelo implementado mediante una clave de API para la autenticación. Este cliente actúa como una interfaz para la API de inferencia de modelos.

Referencias:

• integración de Azure AI con LangChain
• Introducción a la API de inferencia de modelos

Si el punto de conexión admite Microsoft Entra ID, use el código siguiente para crear el cliente:

import os
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
)

Si tiene previsto usar llamadas asincrónicas, use la versión asincrónica de las credenciales:

from azure.identity.aio import (
    DefaultAzureCredential as DefaultAzureCredentialAsync,
)
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredentialAsync(),
    model="Mistral-Large-3",
)

Si el punto de conexión sirve un único modelo (por ejemplo, implementaciones de API sin servidor), no incluya el model parámetro :

import os
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_AI_CREDENTIAL"],
)

Comprobación de la configuración

Pruebe la conexión de cliente con una invocación sencilla:

response = model.invoke("Say hello")
print(response.content)

Qué hace esto: Llama al modelo con un mensaje sencillo para comprobar la autenticación y la conectividad. Salida esperada: un mensaje de saludo del modelo (por ejemplo, "Hola! ¿Cómo puedo ayudarte hoy?".

Referencias:

• Interfaz De ejecución de LangChain

Uso de modelos de finalización de chat

Utilice el modelo directamente. ChatModels son instancias de la interfaz LangChain Runnable , que proporciona una manera estándar de interactuar con ellos. Para llamar al modelo, pase una lista de mensajes al invoke método .

from langchain_core.messages import HumanMessage, SystemMessage

messages = [
    SystemMessage(content="Translate the following from English into Italian"),
    HumanMessage(content="hi!"),
]

model.invoke(messages)

Qué hace este fragmento de código: Muestra cómo pasar una lista de HumanMessage objetos y SystemMessage al método del invoke() modelo para generar una respuesta.

Referencias:

• Mensajes LangChain
• Interfaz De ejecución de LangChain

Componga las operaciones como sea necesario en secuencias. Use una plantilla de prompt para traducir oraciones.

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

system_template = "Translate the following into {language}:"
prompt_template = ChatPromptTemplate.from_messages(
    [("system", system_template), ("user", "{text}")]
)

Esta cadena toma language y text entradas. Ahora, cree un analizador de salida:

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

Qué hace este fragmento de código: Crea un StrOutputParser objeto que convierte la salida del modelo en un formato de cadena, quitando los metadatos adicionales.

Referencias:

• Analizadores de salida de LangChain

Combine la plantilla, el modelo y el analizador de salida mediante el operador de canalización (|):

chain = prompt_template | model | parser

Invoque la cadena proporcionando los valores de language y text usando el método invoke.

chain.invoke({"language": "italian", "text": "hi"})

Encadenar varios LLM

Dado que los modelos de Foundry exponen una API de inferencia de modelos común, puede encadenar varias operaciones LLM y elegir el modelo más adecuado para cada paso.

En el ejemplo siguiente, se crean dos clientes de modelo: un productor y un comprobador. Para que la distinción sea clara, use un punto de conexión de varios modelos, como la API de inferencia de modelos y pase el model parámetro a un modelo grande para la generación y un modelo pequeño para la comprobación. La producción de contenido normalmente requiere un modelo más grande, mientras que la comprobación puede usar una más pequeña.

from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

producer = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
)

verifier = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="mistral-small",
)

Qué hace este fragmento de código: Crea una instancia de dos clientes independientes AzureAIChatCompletionsModel : uno que usa Mistral-Large-3 para la generación de contenido y otro mediante Mistral-Small para la comprobación, lo que muestra cómo elegir modelos diferentes para diferentes tareas.

Referencias:

• integración de Azure AI de LangChain

En el ejemplo siguiente se genera un poema escrito por un poeta urbano:

from langchain_core.prompts import PromptTemplate

producer_template = PromptTemplate(
    template="You are an urban poet, your job is to come up \
             verses based on a given topic.\n\
             Here is the topic you have been asked to generate a verse on:\n\
             {topic}",
    input_variables=["topic"],
)

verifier_template = PromptTemplate(
    template="You are a verifier of poems, you are tasked\
              to inspect the verses of poem. If they consist of violence and abusive language\
              report it. Your response should be only one word either True or False.\n \
              Here is the lyrics submitted to you:\n\
              {input}",
    input_variables=["input"],
)

Qué hace este fragmento de código: Crea una plantilla de aviso y la encadena con el producer cliente de modelo para generar contenido creativo (un poema en este caso).

Encadene las piezas:

chain = producer_template | producer | parser | verifier_template | verifier | parser

Qué hace este fragmento: Encadena el poema generado a través del modelo verifier para validar o revisar el contenido generado, mostrando un flujo de trabajo de productor-verificador.

La cadena anterior devuelve solo la salida del verifier paso. Para acceder al resultado intermedio generado por producer, utilice un RunnablePassthrough para mostrar ese paso intermedio.

from langchain_core.runnables import RunnablePassthrough, RunnableParallel

generate_poem = producer_template | producer | parser
verify_poem = verifier_template | verifier | parser

chain = generate_poem | RunnableParallel(poem=RunnablePassthrough(), verification=RunnablePassthrough() | verify_poem)

Invoque la cadena mediante el invoke método :

chain.invoke({"topic": "living in a foreign country"})

Qué hace este fragmento de código: Llama a la cadena completa productor-verificador con una entrada de tópico, devolviendo tanto el contenido generado como el resultado de la verificación. Salida esperada: un objeto JSON que contiene poem y verification claves con el poema generado y la respuesta de comprobación.

Referencias:

• LangChain Runnables

Utilice modelos de incrustación

Cree un cliente de embeddings de manera similar. Establezca las variables de entorno para que apunten a un modelo de inserción:

export AZURE_INFERENCE_ENDPOINT="<your-model-endpoint-goes-here>"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

Cree el cliente:

import os
from langchain_azure_ai.embeddings import AzureAIEmbeddingsModel

embed_model = AzureAIEmbeddingsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="text-embedding-3-large",
)

Qué hace este fragmento de código: Crea una instancia de un cliente de inserción mediante AzureAIEmbeddingsModel para convertir texto en incrustaciones vectoriales, que se pueden usar para comparaciones de búsqueda semántica y similitud.

Referencias:

• Incrustaciones de LangChain

Use un almacén de vectores en memoria:

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

Qué hace este fragmento de código: Crea un almacén de vectores en memoria (InMemoryVectorStore) que almacena incrustaciones para operaciones de búsqueda de similitud rápidas.

Referencias:

• LangChain Almacenes de Vectores

Agregar documentos:

from langchain_core.documents import Document

document_1 = Document(id="1", page_content="foo", metadata={"baz": "bar"})
document_2 = Document(id="2", page_content="thud", metadata={"bar": "baz"})

documents = [document_1, document_2]
vector_store.add_documents(documents=documents)

Qué hace este fragmento de código: Convierte documentos en incrustaciones mediante el cliente de incrustaciones y los agrega al almacén de vectores para su posterior recuperación.

Referencias:

• LangChain Almacenes de Vectores

Buscar por similitud:

results = vector_store.similarity_search(query="thud", k=1)
for doc in results:
    print(f"* {doc.page_content} [{doc.metadata}]")

Qué hace este fragmento de código: Realiza una búsqueda semántica en el almacén de vectores, devolviendo documentos más similares a la consulta en función de la similitud de inserción. Salida esperada: lista de documentos relevantes clasificados por puntuación de similitud.

Uso de modelos de OpenAI de Azure

Al usar Azure modelos de OpenAI con el paquete langchain-azure-ai, use el siguiente formato de punto de conexión:

import os
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

llm = AzureAIChatCompletionsModel(
    endpoint="https://<resource>.openai.azure.com/openai/v1",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="gpt-4o"
)

Qué hace este fragmento de código: Crea una instancia de un cliente configurado específicamente para los modelos de OpenAI de Azure mediante el formato de punto de conexión de Azure OpenAI. El parámetro endpoint apunta al recurso Azure OpenAI y el credential usa la clave de API almacenada en la variable de entorno.

Referencias:

• integración de LangChain Azure AI

Depuración y solución de problemas

Si necesita depurar la aplicación y comprender las solicitudes enviadas a modelos en Foundry, use las funcionalidades de depuración de la integración:

En primer lugar, configure el registro en el nivel deseado:

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.inference' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout:
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename="sample.log")
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

¿Qué hace este fragmento de código: Configura Python registro en el nivel DEBUG para capturar información detallada sobre las solicitudes HTTP y las respuestas entre LangChain y la API de inferencia de modelos.

Referencias:

• módulo de registro Python

Para ver las cargas de solicitud, pase logging_enable=Trueclient_kwargs al instanciar el cliente:

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
    client_kwargs={"logging_enable": True},
)

Qué hace este fragmento de código: Crea un cliente con el registro habilitado para capturar y mostrar cargas de solicitud y respuesta detalladas, útiles para depurar las interacciones de la API.

Utilice el cliente como de costumbre en su código.

Seguimiento

Usa el seguimiento en Foundry mediante la creación de un trazador. Los registros se almacenan en Aplicación de Azure Insights y se pueden consultar en cualquier momento mediante Azure Monitor o el portal de Foundry. Cada centro de INTELIGENCIA ARTIFICIAL tiene una instancia de Aplicación de Azure Insights asociada.

Obtén tu cadena de conexión de instrumentación

Puede configurar la aplicación para enviar datos de telemetría a Aplicación de Azure Insights mediante cualquiera de los métodos siguientes:

1. Use la cadena de conexión para Aplicación de Azure Insights directamente.

   1. Vaya al portal de Foundry y seleccione Seguimiento.

   2. Seleccione Administrar origen de datos. En esta pantalla, puede ver la instancia asociada al proyecto.

   3. Copie el valor en Cadena de conexión y establézcalo en la siguiente variable:

      import os
      
      application_insights_connection_string = "instrumentation...."
      

2. Use el SDK de Microsoft Foundry y el punto de conexión de Foundry Project:

   1. Asegúrese de que tiene instalado el paquete azure-ai-projects en su entorno.

   2. Vaya al portal de Foundry.

   3. Copie la dirección URL del punto de conexión del proyecto foundry y establézcala en el código siguiente:

      from azure.ai.projects import AIProjectClient
      from azure.identity import DefaultAzureCredential
      
      project_client = AIProjectClient(
          credential=DefaultAzureCredential(),
          endpoint="<your-foundry-project-endpoint-url>",
      )
      
      application_insights_connection_string = project_client.telemetry.get_application_insights_connection_string()
      

Obtenga más información sobre cómo visualizar y administrar seguimientos.

Pasos siguientes

• Desarrollo de aplicaciones con LlamaIndex
• Visualización y administración de seguimientos en Foundry
• Usar modelos de Foundry
• Referencia: API de inferencia de modelos