Desenvolver aplicações com modelos e LangChain no Microsoft Foundry (clássico)

LangChain é um ecossistema de programadores que facilita a construção de aplicações de raciocínio. Inclui vários componentes, e a maioria pode ser usada de forma independente, por isso podes escolher as peças que precisas.

Pode usar modelos implementados em Microsoft Foundry com LangChain de duas formas:

Este tutorial mostra como usar o pacote langchain-azure-ai[v1] com o LangChain usando Azure API de Inferência de Modelos de IA. Alguns modelos, como OpenAI, Cohere ou Mistral, oferecem as suas próprias APIs e extensões LangChain. Estas extensões podem incluir capacidades específicas para o modelo e são adequadas caso precise de as utilizar. Instale a extensão para o modelo escolhido, como langchain-openai ou langchain-cohere.

Pré-requisitos

Para executar este tutorial, precisas de:

• Uma conta no Azure com uma subscrição ativa. Se não tiveres uma, cria uma conta Azure free, que inclui uma subscrição de teste gratuita.

• Função obrigatória:
  • Proprietário ou Colaborador no recurso Foundry ou no Hub de IA para implementar modelos
  • Azure AI User para usar o modelo num projeto Foundry
  • Azure AI Developer para usar o modelo num projeto baseado em hub

• Uma implementação de modelo que suporta a Model Inference API. Este artigo utiliza Mistral-Large-3.

• Python 3.9 ou posterior instalado, incluindo pip.

• LangChain instalado. Pode instalá-lo usando o seguinte comando:

  pip install langchain
  

• Instale a integração com o Foundry:

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

Configurar o ambiente

Para usar LLMs implementados no portal Microsoft Foundry, precisa do endpoint e das credenciais para se ligar a ele. Siga estes passos para obter a informação de que precisa do modelo que pretende usar:

1. Iniciar sessão no Microsoft Foundry. Certifica-te de que a opção New Foundry está ativada. Estes passos referem-se à Foundry (nova).

   

2. Abre o projeto onde o modelo é implementado, se ainda não estiver aberto.

3. Copie a URL do endpoint e a chave.

Neste cenário, defina a URL e a chave do endpoint como variáveis de ambiente. (Se o endpoint que você copiou incluir texto adicional após /models, remova-o para que a URL termine em /models, conforme mostrado abaixo.)

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

Crie um cliente para se ligar ao modelo de chat usando a AzureAIChatCompletionsModel classe.

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

O que este excerto faz: Instancia um AzureAIChatCompletionsModel cliente configurado para se ligar ao seu modelo implementado usando uma chave API para autenticação. Este cliente funciona como uma interface para a API de Inferência de Modelos.

Referências:

• LangChain Azure integração de IA
• Visão geral da API de Inferência de Modelos

Se o seu endpoint suporta o Microsoft Entra ID, use o seguinte código para criar o 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",
)

Se planeia usar chamadas assíncronas, utilize a versão assíncrona das credenciais:

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

Se o seu endpoint serve um único modelo (por exemplo, implementações de APIs serverless), não inclua o 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"],
)

Verifica a tua configuração

Teste a ligação do seu cliente com uma invocação simples:

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

O que isto faz: Chama o modelo com um simples prompt para verificar autenticação e conectividade. Saída esperada: Uma mensagem de saudação do modelo (por exemplo, "Olá! Como posso ajudar hoje?").

Referências:

• Interface LangChain Runnable

Utilizar modelos de conclusão de chat

Usa o modelo diretamente. ChatModels são instâncias da interface LangChain Runnable , que fornece uma forma padrão de interagir com elas. Para chamar o modelo, passe uma lista de mensagens ao 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)

O que este excerto faz: Demonstra como passar uma lista de HumanMessage objetos e SystemMessage ao método do invoke() modelo para gerar uma resposta.

Referências:

• Mensagens LangChain
• Interface LangChain Runnable

Compor operações conforme necessário em cadeias. Use um modelo de prompt para traduzir frases:

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 cadeia de processos recebe language e text como entradas. Agora, crie um parser de saída:

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

O que este excerto faz: Cria um StrOutputParser que converte a saída do modelo para um formato de string, removendo quaisquer metadados extra.

Referências:

• Analisadores de Saída LangChain

Combine o template, modelo e parser de saída usando o operador pipe (|):

chain = prompt_template | model | parser

Invoque a cadeia fornecendo os valores de language e text usando o método invoke:

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

Encadear múltiplos LLMs

Como os modelos no Foundry expõem uma API comum de Inferência de Modelos, pode encadear múltiplas operações de LLM e escolher o modelo mais adequado a cada etapa.

No exemplo seguinte, cria-se dois clientes modelo: um produtor e um verificador. Para esclarecer a distinção, utilize um endpoint multi-modelo como a Model Inference API e passe o parâmetro para um modelo grande para geração e um modelo pequeno para verificação. Produzir conteúdo geralmente requer um modelo maior, enquanto a verificação pode usar um modelo mais pequeno.

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

O que este excerto faz: Instancia dois clientes distintos AzureAIChatCompletionsModel : um usado Mistral-Large-3 para geração de conteúdo e outro Mistral-Small para verificação, demonstrando como escolher diferentes modelos para diferentes tarefas.

Referências:

• LangChain Azure integração de IA

O exemplo seguinte gera um poema escrito por um 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"],
)

O que este excerto faz: Cria um modelo de prompt e encadeia-o com o producer cliente modelo para gerar conteúdo criativo (um poema neste caso).

Encadear as peças:

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

O que este excerto faz: Encadeia o poema gerado através do verifier modelo para validar ou rever o conteúdo gerado, demonstrando um fluxo de trabalho produtor-verificador.

A cadeia anterior devolve apenas a saída do verifier passo. Para aceder ao resultado intermédio gerado pelo producer, use a RunnablePassthrough para obter esse passo intermédio.

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)

Invoce a cadeia usando o método invoke :

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

O que este excerto faz: Chama a cadeia completa produtor-verificador com uma entrada de tópico, retornando tanto o conteúdo gerado como o resultado da verificação. Saída esperada: Um objeto JSON contendo poem e verification com as chaves do poema gerado e a resposta de verificação.

Referências:

• LangChain Runnables

Utilização de modelos de embedding

Crie um cliente de embeddings de forma semelhante. Defina as variáveis de ambiente para apontarem para um modelo de embeddings:

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

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

O que este excerto faz: Instancia um cliente de embeddings usando AzureAIEmbeddingsModel para converter texto em embeddings vetoriais, que podem ser usados para pesquisa semântica e comparações de similaridade.

Referências:

• LangChain Embeddings

Use um armazenamento vetorial em memória:

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

O que este excerto faz: Cria um armazenamento vetorial em memória (InMemoryVectorStore) que armazena embeddings para operações rápidas de pesquisa por similaridade.

Referências:

• Armazenamento Vetorial LangChain

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

O que este excerto faz: Converte documentos em embeddings usando o cliente de embeddings e adiciona-os à loja vetorial para recuperação posterior.

Referências:

• Armazenamentos de Vetores LangChain

Pesquise por semelhança:

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

O que este excerto faz: Realiza uma pesquisa semântica contra o armazém vectorial, retornando documentos mais semelhantes à consulta com base na similaridade de embeddings. Resultado esperado: Lista de documentos relevantes classificados por pontuação de similaridade.

Utilizar modelos OpenAI do Azure

Quando utilizar os modelos OpenAI do Azure com o pacote langchain-azure-ai, use o seguinte formato de endpoint:

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

O que este excerto faz: Instancia um cliente configurado especificamente para modelos OpenAI do Azure usando o formato de endpoint do Azure OpenAI. O parâmetro endpoint aponta para o seu recurso Azure OpenAI, e o credential usa a chave API armazenada na variável de ambiente.

Referências:

• Integração de IA do LangChain Azure

Depuração e resolução de problemas

Se precisar de depurar a sua aplicação e compreender os pedidos enviados aos modelos no Foundry, utilize as capacidades de depuração da integração:

Primeiro, configure o registo ao nível desejado:

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)

O que este excerto faz: Configura o registo em Python ao nível DEBUG para captar informações detalhadas sobre pedidos HTTP e respostas entre o LangChain e a API de Inferência do Modelo.

Referências:

• Módulo de registo Python

Para ver as cargas úteis de pedido, passe logging_enable=True em client_kwargs ao instanciar o 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},
)

O que este excerto faz: Cria um cliente com o logging ativado para capturar e mostrar payloads detalhados de pedido/resposta, útil para depurar interações da API.

Utilize o cliente normalmente no seu código.

Rastreamento

Use o traçado no Foundry criando um traçador. Os registos são armazenados no Aplicação Azure Insights e podem ser consultados a qualquer momento usando o Azure Monitor ou o portal Foundry. Cada hub de IA tem uma instância associada do Aplicação Azure Insights.

Obtenha a sua instrumentation cadeia de ligação

Pode configurar a sua aplicação para enviar telemetria para o Aplicação Azure Insights usando qualquer um dos seguintes métodos:

1. Utilize diretamente a string de conexão para o Aplicação Azure Insights.

   1. Vai ao portal da Foundry e seleciona Traçar.

   2. Selecione Gerir a fonte dos dados. Neste ecrã, pode ver a instância associada ao projeto.

   3. Copie o valor em string de Conexão e defina-o para a seguinte variável:

      import os
      
      application_insights_connection_string = "instrumentation...."
      

2. Utilize o SDK do Microsoft Foundry e o endpoint do Foundry Project:

   1. Certifique-se de que tem o pacote azure-ai-projects instalado no seu ambiente.

   2. Vai ao portal da Foundry.

   3. Copie a URL do endpoint do seu projeto Foundry e defina-a no seguinte código:

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

Saiba mais sobre como visualizar e gerir traços.

Próximos passos

• Desenvolver aplicações com o LlamaIndex
• Visualizar e gerir rastros no Foundry
• Utilizar Modelos de Fundição
• Referência: API de Inferência de Modelos