Uso de LangChain con modelos en Microsoft Foundry

Use langchain-azure-ai para compilar aplicaciones LangChain que llaman a modelos implementados en Microsoft Foundry. Los modelos con API compatibles con OpenAI se pueden usar directamente. En este artículo, creará clientes de chat e incrustaciones, ejecutará cadenas de mensajes y combinará la generación con flujos de trabajo de verificación.

Requisitos previos

• Una suscripción Azure. Cree uno gratis.
• Un proyecto de fundición.
• El rol de Azure AI User en el proyecto Foundry.
• Modelo de chat implementado que admite API compatibles con OpenAI, como gpt-4.1 o Mistral-Large-3.
• Un modelo de inserción implementado, como text-embedding-3-large.
• Python 3.9 o posterior.

Instale los paquetes necesarios:

pip install -U langchain langchain-azure-ai azure-identity

Configuración del entorno

Establezca uno de los siguientes patrones de conexión:

• Punto de conexión del proyecto con Microsoft Entra ID (recomendado).
• Punto de conexión directo con una clave de API.

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"

Qué hace este fragmento de código: Define las variables de entorno usadas por las clases de modelo para el langchain-azure-ai acceso directo o a puntos finales basados en proyectos.

Uso de modelos de chat

Puede crear fácilmente una instancia de un modelo mediante init_chat_model:

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:gpt-4.1")

Todos los modelos de Foundry compatibles con OpenAI se pueden usar con el cliente, pero primero deben implementarse en el recurso foundry. Usar project_endpoint (variable de entorno AZURE_AI_PROJECT_ENDPOINT) requiere Microsoft Entra ID para la autenticación y el rol Usuario de Azure AI.

Qué hace este fragmento de código: Crea un cliente de modelo de chat mediante el init_chat_model método de conveniencia. El cliente se enruta al modelo especificado a través del punto de conexión del proyecto Foundry o del punto de conexión directo configurado en el entorno.

Referencias:

• AzureAIOpenAIApiChatModel

Comprobación de la configuración

Ejecute una invocación de modelo simple:

response = model.invoke("Say hello")
response.pretty_print()

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

Qué hace este fragmento de código: Envía un mensaje básico para comprobar el punto de conexión, la autenticación y el enrutamiento del modelo.

Referencias:

• Interfaz ejecutable de LangChain

Modelos configurables

También puede crear un modelo configurable en tiempo de ejecución especificando configurable_fields. Cuando se omite el model parámetro, se convierte en un campo configurable de forma predeterminada.

from langchain.chat_models import init_chat_model
from azure.identity import DefaultAzureCredential

configurable_model = init_chat_model(
    model_provider="azure_ai", 
    temperature=0,
	credential=DefaultAzureCredential()
)


configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "gpt-5-nano"}},  # Run with GPT-5-nano
).pretty_print()

configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "Mistral-Large-3"}}, # Run with Mistral Large
).pretty_print()

================================== Ai Message ==================================

Hi! I'm ChatGPT, an AI assistant built by OpenAI. You can call me ChatGPT or just Assistant. How can I help you today?
================================== Ai Message ==================================

I don't have a name, but you can call me **Assistant** or anything you like! 😊 What can I help you with today?

Qué hace este fragmento de código: Crea una instancia de modelo configurable que permite cambiar los modelos fácilmente en el momento de la invocación. Dado que falta el model parámetro en init_chat_model, es de forma predeterminada un campo configurable y se puede pasar con invoke(). Puede agregar otros campos para que se puedan configurar mediante la configuración de configurable_fields.

Configurar clientes directamente

También puede crear un cliente de modelo de chat mediante AzureAIOpenAIApiChatModel la clase .

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="Mistral-Large-3",
)

De forma predeterminada, AzureAIOpenAIApiChatModel usa la API de respuestas de OpenAI. Para cambiar este comportamiento, pase use_responses_api=False:

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
    use_responses_api=False
)

Ejecución de llamadas asincrónicas

Use credenciales asincrónicas si la aplicación llama a modelos con ainvoke. Al usar Microsoft Entra ID para la autenticación, use la implementación asincrónica correspondiente para las credenciales:

import os

from azure.identity.aio import DefaultAzureCredential as DefaultAzureCredentialAsync
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredentialAsync(),
	model="gpt-4.1",
)


async def main():
	response = await model.ainvoke("Say hello asynchronously")
	response.pretty_print()


import asyncio
asyncio.run(main())

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

Qué hace este fragmento de código: Crea un cliente asincrónico y ejecuta una solicitud sin bloqueo con ainvoke.

Referencias:

• credenciales Async en Azure Identity
• Interfaz ejecutable de LangChain

Razonamiento

Muchos modelos pueden realizar el razonamiento de varios pasos para llegar a una conclusión. Esto implica dividir problemas complejos en pasos más pequeños y manejables.

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:DeepSeek-R1-0528")

for chunk in model.stream("Why do parrots have colorful feathers?"):
    reasoning_steps = [r for r in chunk.content_blocks if r["type"] == "reasoning"]
    print(reasoning_steps if reasoning_steps else chunk.text, end="")

print("\n")

Parrots have colorful feathers primarily due to a combination of evolutionary ...

Referencias:

• Streaming de LangChain

Herramientas del lado servidor

Los modelos openAI implementados en Foundry admiten bucles de llamada a herramientas del lado servidor: los modelos pueden interactuar con la búsqueda web, los intérpretes de código y otras herramientas y, a continuación, analizar los resultados en un solo turno conversacional. Si un modelo invoca un servidor de herramientas, el contenido del mensaje de respuesta incluirá contenido que representa la invocación y el resultado de la herramienta.

Estas son herramientas proporcionadas por OpenAI que amplían las funcionalidades del modelo. Para ver la lista completa de herramientas admitidas, consulte Herramientas integradas.

En el ejemplo siguiente se muestra cómo usar la búsqueda web:

from langchain.chat_models import init_chat_model
from langchain_azure_ai.tools.builtin import WebSearchTool
from azure.identity import DefaultAzureCredential

model = init_chat_model("azure_ai:gpt-4.1", credential=DefaultAzureCredential())
model_with_web_search = model.bind_tools([WebSearchTool()])

result = model_with_web_search.invoke("What is the current price of gold? Give me the answer in one sentence.")
result.content[-1]["text"]

As of today, March 24, 2026, the spot price of gold is approximately $4,397.80 per ounce. ([tradingeconomics.com](https://tradingeconomics.com/commodity/gold))

Es posible que algunas herramientas requieran la configuración de otros recursos del proyecto. Use azure-ai-projects para configurar esos recursos y, a continuación, haga referencia a ellos desde LangChain/LangGraph.

En el ejemplo siguiente se muestra cómo configurar un almacén de archivos antes de usarlo en una herramienta:

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create vector store and upload file
vector_store = openai.vector_stores.create(name="ProductInfoStore")
vector_store_id = vector_store.id

with open("product_info.md", "rb") as file_handle:
    vector_store_file = openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id,
        file=file_handle,
    )

¿Qué hace este fragmento de código: Configura un almacén de vectores con un archivo en Microsoft Foundry para que un modelo pueda buscar más adelante en el contenido de ese archivo (usado con el FileSearchTool en el siguiente bloque de código).

from langchain_azure_ai.tools.builtin import FileSearchTool

model_with_tools = model.bind_tools([FileSearchTool(vector_store_ids=[vector_store.id])])

results = model_with_tools.invoke("Tell me about Contoso products")
print("Answer:", results.content[-1]["text"])
print("Annotations:", results.content[-1]["annotations"])

Answer: Contoso offers the following products:

1. **The widget**
   - Description: A high-quality widget that is perfect for all your widget needs.
   - Price: $19.99

2. **The gadget**
   - Description: An advanced gadget that offers exceptional performance and reliability.
   - Price: $49.99

These products are part of Contoso's main offerings as detailed in their product information documentation.
Annotations: [{'file_id': 'assistant-MvU5SEqUcUBumoLUV5BXxn', 'filename': 'product_info.md', 'type': 'file_citation', 'file_index': 395}]

Uso de modelos Foundry en agentes

Utilice create_agent con modelos conectados a Foundry para crear bucles de agente de estilo ReAct:

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()

================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

También se pueden usar herramientas del lado servidor, pero requieren llamar a bind_tools.

from langchain.chat_models import init_chat_model
from langchain.agents import create_agent
from langchain_azure_ai.tools.builtin import ImageGenerationTool

model = init_chat_model("azure_ai:gpt-5.2")
tools = [ImageGenerationTool(model="gpt-image-1.5", size="1024x1024")]
model_with_tools = model.bind_tools(tools)

agent = create_agent(
    model=model_with_tools,
    tools=tools,
    system_prompt="You're an informational agent. Answer questions with graphics.", 
)

Utilice modelos de incrustación

Puede crear fácilmente una instancia de un modelo mediante init_embeddings:

from langchain.embeddings import init_embeddings

embed_model = init_embeddings("azure_ai:text-embedding-3-small")

Qué hace este fragmento de código: Crea un cliente de modelo de incrustaciones mediante el init_embeddings método de conveniencia.

Todos los modelos de Foundry compatibles con OpenAI se pueden usar con el cliente, pero primero deben implementarse en el recurso foundry. Usar project_endpoint (variable de entorno AZURE_AI_PROJECT_ENDPOINT) requiere Microsoft Entra ID para la autenticación y el rol Usuario de Azure AI.

O bien, cree el cliente de incrustaciones con AzureAIOpenAIApiEmbeddingsModel.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="text-embedding-3-large",
)

Para la autenticación directa de punto de conexión y clave de API:

import os

from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	endpoint=os.environ["OPENAI_BASE_URL"],
	credential=os.environ["OPENAI_API_KEY"],
	model="text-embedding-3-large",
)

Qué hace este fragmento de código: Configura la generación de incrustaciones para flujos de trabajo de búsqueda, recuperación y clasificación de vectores.

Referencias:

• AzureAIOpenAIApiEmbeddingsModel

Ejemplo: Ejecución de la búsqueda de similitud con un almacén de vectores

Use un almacén de vectores en memoria para la experimentación local.

from langchain_core.documents import Document
from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

documents = [
	Document(id="1", page_content="foo", metadata={"baz": "bar"}),
	Document(id="2", page_content="thud", metadata={"bar": "baz"}),
]

vector_store.add_documents(documents=documents)

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

* thud [{'bar': 'baz'}]

Qué hace este fragmento de código: Agrega documentos de ejemplo a un almacén de vectores y devuelve el documento más similar para una consulta.

Referencias:

• Almacenes de vectores LangChain

Depuración de solicitudes con registro

Habilite langchain_azure_ai el registro de depuración para inspeccionar el flujo de solicitudes.

import logging
import sys

logger = logging.getLogger("langchain_azure_ai")
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(stream=sys.stdout)
formatter = logging.Formatter(
	"%(asctime)s:%(levelname)s:%(name)s:%(message)s"
)
handler.setFormatter(formatter)
logger.addHandler(handler)

¿Qué hace este fragmento de código: Configura el registro de Python para emitir registros detallados del SDK que facilitan la resolución de problemas de carga útil o terminal.

Referencias:

• logs de Python

Referencia de variables de entorno

Puede configurar las siguientes variables de entorno. Estos valores también se pueden configurar al construir los objetos:

Paso siguiente

Contenido relacionado

• Introducción a los modelos de foundry
• Microsoft Visión General del SDK de Foundry
• Uso de LangChain con memoria en Foundry
• Usar LangChain con Foundry Agent Service