Compartilhar via

Usar LangChain com modelos no Microsoft Foundry

Utilize langchain-azure-ai para criar aplicativos LangChain que chamam modelos implantados no Microsoft Foundry. Modelos com APIs compatíveis com OpenAI podem ser usados diretamente. Neste artigo, você criará clientes de chat e de embeddings, executará sequências de prompts e combinará a geração com os fluxos de trabalho de verificação.

Pré-requisitos

  • Uma assinatura do Azure. Criar um gratuitamente.
  • Um projeto do Foundry.
  • A função de usuário de IA do Azure no projeto Foundry.
  • Um modelo de chat implantado que dá suporte a APIs compatíveis com OpenAI, como gpt-4.1 ou Mistral-Large-3.
  • Um modelo de incorporações implementado, como text-embedding-3-large.
  • Python 3.9 ou posterior.

Instale os pacotes necessários:

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

Importante

langchain-azure-ai usa o novo SDK do Microsoft Foundry (v2). Se você estiver usando o Foundry clássico, utilize langchain-azure-ai[v1], que ultiliza o SDK de Inferência de IA do Azure (herdado). Saiba mais.

Configurar o ambiente

Defina um dos seguintes padrões de conexão:

  • Ponto de extremidade do projeto com o Microsoft Entra ID (recomendado).
  • Ponto de extremidade direto com uma chave 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>"

O que este trecho de código faz: Define variáveis de ambiente usadas pelas langchain-azure-ai classes de modelo para acesso de ponto de extremidade direto ou relacionado a projeto.

Usar modelos de chat

Você pode facilmente instanciar um modelo usando init_chat_model:

from langchain.chat_models import init_chat_model

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

Importante

Usar init_chat_model requer langchain>=1.2.13. Se você não puder atualizar sua versão, configure os clientes diretamente.

Todos os modelos do Foundry que dão suporte a APIs compatíveis com OpenAI podem ser usados com o cliente, mas eles precisam ser implantados em seu recurso do Foundry primeiro. Usar project_endpoint (variável de ambiente AZURE_AI_PROJECT_ENDPOINT) requer o ID do Microsoft Entra para autenticação e a função Usuário de IA do Azure.

O que este snippet de código faz: cria um cliente de modelo de chat usando o método de conveniência init_chat_model. O cliente roteia para o modelo especificado por meio do ponto de extremidade do projeto Foundry ou do ponto de extremidade direto configurado no ambiente.

Referências:

Verificar sua configuração

Execute uma invocação de modelo simples:

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

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

O que este trecho de código faz: Envia um prompt básico para verificar o endpoint, a autenticação e o roteamento do modelo.

Referências:

Modelos configuráveis

Você também pode criar um modelo configurável em runtime especificando configurable_fields. Quando você omite o model parâmetro, ele se torna um campo configurável por padrão.

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?

O que este snippet de código faz: Cria uma instância de modelo configurável que permite alternar modelos facilmente no momento da invocação. Como o parâmetro model está ausente em init_chat_model, por padrão, é um campo configurável e pode ser passado com invoke(). Você pode adicionar outros campos para serem configuráveis configurando configurable_fields.

Configurar clientes diretamente

Você também pode criar um cliente de modelo de chat usando AzureAIOpenAIApiChatModel a classe.

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

Por padrão, AzureAIOpenAIApiChatModel usa a API de Respostas OpenAI. Você pode alterar esse comportamento passando 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
)

Executar chamadas assíncronas

Use credenciais assíncronas se seu aplicativo chamar modelos com ainvoke. Ao usar o Microsoft Entra ID para autenticação, utilize a implementação assíncrona correspondente para credenciais:

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

Dica

Se você executar esse código em um jupyter notebook, poderá usar await main() diretamente em vez de asyncio.run(main()).

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

O que este snippet de código faz: Cria um cliente assíncrono e executa uma solicitação sem bloqueio com ainvoke.

Referências:

Raciocínio

Muitos modelos podem executar o raciocínio em várias etapas para chegar a uma conclusão. Isso envolve dividir problemas complexos em etapas menores e mais gerenciáveis.

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

Referências:

Ferramentas do lado do servidor

Os modelos OpenAI implantados no Foundry dão suporte a loops de chamada de ferramentas do lado do servidor: os modelos podem interagir com pesquisa na Web, interpretadores de código e outras ferramentas e, em seguida, analisar os resultados em uma única vez de conversa. Se um modelo invocar uma ferramenta no lado do servidor, a mensagem de resposta incluirá informações que representam a invocação e o resultado da ferramenta.

Importante

As ferramentas no namespace langchain_azure_ai.tools.builtin só têm suporte em modelos OpenAI.

Essas são ferramentas fornecidas pelo OpenAI que estendem os recursos do modelo. Para ver a lista completa de ferramentas com suporte, consulte as ferramentas internas.

O exemplo a seguir mostra como usar a pesquisa na 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))

Algumas ferramentas podem exigir a configuração de outros recursos em seu projeto. Use azure-ai-projects para configurar esses recursos e, em seguida, referenciá-los de LangChain/LangGraph.

O exemplo a seguir mostra como configurar um repositório de arquivos antes de usá-lo em uma ferramenta:

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

O que este snippet faz: Configura um repositório de vetores com um arquivo no Microsoft Foundry para que um modelo possa consultar posteriormente o conteúdo desse arquivo (usado com o FileSearchTool bloco de código próximo).

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}]

Usar modelos do Foundry em agentes

Use create_agent com modelos conectados ao Foundry para criar loops de agente no 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.

As ferramentas do lado do servidor também podem ser usadas, mas exigem chamadas 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.", 
)

Dica

A ferramenta de geração de imagem no Foundry requer a passagem do nome de implantação do modelo para geração de imagem como parte de um cabeçalho, x-ms-oai-image-generation-deployment Ao usar langchain-azure-ai, isso é tratado automaticamente. No entanto, se você planeja usar essa ferramenta com langchain-openai, deverá passar o cabeçalho manualmente.

Usar modelos de incorporação

Você pode facilmente instanciar um modelo usando init_embeddings:

from langchain.embeddings import init_embeddings

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

O que este snippet de código faz: cria um cliente de modelo de incorporação usando o método de conveniência init_embeddings.

Todos os modelos do Foundry que dão suporte a APIs compatíveis com OpenAI podem ser usados com o cliente, mas eles precisam ser implantados em seu recurso do Foundry primeiro. Usar project_endpoint (variável de ambiente AZURE_AI_PROJECT_ENDPOINT) requer o ID do Microsoft Entra para autenticação e a função Usuário de IA do Azure.

Ou crie o cliente de inserções com 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 autenticação direta com ponto de extremidade e chave 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",
)

O que este snippet de código faz: Configura a geração de inserções para fluxos de trabalho de pesquisa, recuperação e classificação de vetores.

Referências:

Exemplo: executar a pesquisa de similaridade com um repositório de vetores

Use um repositório de vetores na memória para experimentação 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'}]

O que este snippet de código faz: Adiciona documentos de exemplo a um repositório de vetores e retorna o documento mais semelhante para uma consulta.

Referências:

Depurar solicitações com registros

Habilite o langchain_azure_ai registro de depuração para inspecionar o fluxo de solicitação.

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)

O que este snippet de código faz: configura o log do Python para emitir logs detalhados do SDK que ajudam a solucionar problemas de ponto de extremidade ou problemas de conteúdo.

Referências:

Referência de variáveis de ambiente

Você pode configurar as variáveis de ambiente a seguir. Esses valores também podem ser configurados ao construir os objetos:

Variable Função Exemplo Parâmetro no construtor
AZURE_AI_PROJECT_ENDPOINT Endpoint do projeto Foundry. O uso do endpoint do projeto requer autenticação com o Microsoft Entra ID (recomendado). https://contoso.services.ai.azure.com/api/projects/my-project project_endpoint
AZURE_OPENAI_ENDPOINT Ponto de acesso para recursos do OpenAI. https://contoso.openai.azure.com Nenhum.
OPENAI_BASE_URL Ponto de extremidade diretamente compatível com OpenAI utilizado para chamadas de modelo. https://contoso.services.ai.azure.com/openai/v1 endpoint
OPENAI_API_KEY ou AZURE_OPENAI_API_KEY Chave de API usada com OPENAI_BASE_URL ou AZURE_OPENAI_ENDPOINT para autenticação baseada em chave. <your-api-key> credential
AZURE_OPENAI_DEPLOYMENT_NAME Nome de implantação do modelo no recurso Foundry ou OpenAI. Verifique o nome no portal do Foundry, pois os nomes de implantação podem ser diferentes do modelo subjacente usado. Qualquer modelo que dê suporte a APIs compatíveis com OpenAI pode ser usado, no entanto, nem todos os parâmetros podem ter suporte. Mistral-Large-3 model
AZURE_OPENAI_API_VERSION A versão da API a ser usada. Quando um api_version estiver disponível, construiremos os clientes OpenAI e injetaremos o api-version parâmetro de consulta por meio de default_query. v1 ou preview api_version

Importante

Variáveis de ambiente AZURE_AI_INFERENCE_ENDPOINT e AZURE_AI_CREDENTIALS usadas para AzureAIChatCompletionsModel ou AzureAIEmbeddingsModel (herdadas) não são mais utilizadas.

Próxima etapa

Usar o Foundry Content Safety com o LangGraph

Conteúdo relacionado

  • Last updated on