Desenvolver aplicativos com modelos e LangChain no Microsoft Foundry (clássico)

LangChain é um ecossistema de desenvolvedores que facilita a criação de aplicativos de raciocínio. Ele(a) inclui vários componentes, e a maioria deles pode ser usada de forma independente, de forma que você possa selecionar as peças necessárias.

Você pode usar modelos implantados para Microsoft Foundry com LangChain de duas maneiras:

Este tutorial mostra como usar o pacote langchain-azure-ai[v1] com LangChain usando Azure API de Inferência de Modelo de IA. Alguns modelos, como OpenAI, Cohere ou Mistral, oferecem suas próprias APIs e extensões LangChain. Essas extensões podem incluir funcionalidades específicas do modelo e são adequadas se você precisar usá-las. Instale a extensão para o modelo escolhido, como langchain-openai ou langchain-cohere.

Pré-requisitos

Para executar este tutorial, você precisa:

• Uma conta Azure com uma assinatura ativa. Se você não tiver uma, crie uma conta de Azure free, que inclui uma assinatura de avaliação gratuita.

• Função necessária:
  • Proprietário ou Colaborador no recurso foundry ou hub de IA para implantar modelos
  • Usuário do Azure AI para usar o modelo em um projeto Foundry
  • Desenvolvedor de IA do Azure para usar o modelo em um projeto centralizado em hub.

• Uma implantação de modelo que dá suporte à API de Inferência de Modelo. Este artigo usa Mistral-Large-3.

• Python 3.9 ou posterior instalado, incluindo pip.

• LangChain instalado. Você pode instalá-lo usando o seguinte comando:

  pip install langchain
  

• Instale a integração do Foundry:

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

Configurar o ambiente

Para usar LLMs implementadas no portal do Microsoft Foundry, você precisa do endpoint e das credenciais para se conectar a ele. Siga estas etapas para obter as informações necessárias no modelo que você deseja usar:

1. Entre no Microsoft Foundry. Verifique se o interruptor da Nova Fundição está ativado. Essas etapas referem-se ao Foundry (versão nova).

   

2. Abra o projeto em que o modelo é implantado, se ele ainda não estiver aberto.

3. Copie a URL do ponto de extremidade e a chave.

Nesse cenário, defina a URL do endpoint e a chave como variáveis de ambiente. (Se o ponto de extremidade que você copiou incluir texto adicional depois /models, remova-o para que a URL termine conforme /models mostrado no exemplo 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 conectar 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 trecho de código faz: Cria uma instância de um AzureAIChatCompletionsModel cliente configurado para se conectar ao modelo implantado usando uma chave de API para autenticação. Esse cliente atua como uma interface para a API de Inferência de Modelo.

Referências:

• Integração de IA do LangChain com Azure
• Visão geral da API de Inferência do Modelo

Se o endpoint for compatível com 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 você planeja usar chamadas assíncronas, use 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 ponto de extremidade atender a um único modelo (por exemplo, implantações de API sem servidor), 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"],
)

Verificar sua configuração

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

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

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

Referências:

• Interface Runnable do LangChain

Usar modelos de conclusão de chat

Use o modelo diretamente. ChatModels são instâncias da interface LangChain Runnable , que fornece uma maneira padrão de interagir com elas. Para chamar o modelo, passe uma lista de mensagens para o 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 snippet de código faz: Demonstra como passar uma lista de objetos HumanMessage e SystemMessage para o método invoke() do modelo para gerar uma resposta.

Referências:

• Mensagens LangChain
• Interface do 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}")]
)

Essa cadeia recebe language e text como entradas. Agora, crie um analisador de saída:

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

O que este snippet de código faz: Cria um StrOutputParser que converte a saída do modelo em um formato de cadeia de caracteres, retirando os metadados extras.

Referências:

• Analisadores de saída do LangChain

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

chain = prompt_template | model | parser

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

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

Encadear várias LLMs juntas

Como os modelos no Foundry expõem uma API de Inferência de Modelo comum, você pode encadear várias operações de LLM e escolher o modelo mais adequado para cada etapa.

No exemplo a seguir, você cria dois clientes de modelo: um produtor e um verificador. Para deixar a distinção clara, use um ponto de extremidade de vários modelos, como a API de Inferência de Modelo , e passe o model parâmetro para um modelo grande para geração e um modelo pequeno para verificação. A produção de conteúdo geralmente requer um modelo maior, enquanto a verificação pode usar um menor.

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 snippet de código faz: Cria uma instância de dois clientes separados AzureAIChatCompletionsModel : um usando Mistral-Large-3 para geração de conteúdo e outro usando Mistral-Small para verificação, demonstrando como escolher modelos diferentes para tarefas diferentes.

Referências:

• Integração de IA do LangChain com Azure

O exemplo a seguir 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 snippet de código faz: Cria um modelo de prompt e o encadeia com o producer cliente modelo para gerar conteúdo criativo (um poema nesse caso).

Encadear as peças:

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

O que este snippet de código faz: Encadeia o poema gerado por meio do verifier modelo para validar ou revisar o conteúdo gerado, demonstrando um fluxo de trabalho produtor-verificador.

A cadeia anterior retorna apenas a saída da verifier etapa. Para acessar o resultado intermediário gerado pelo producer, use um RunnablePassthrough para gerar essa etapa intermediária.

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 a cadeia usando o invoke método:

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

O que este snippet de código faz: Chama a cadeia completa de produção e verificação com uma entrada de tópico, retornando tanto o conteúdo produzido quanto o resultado da verificação. Saída esperada: um objeto JSON contendo as chaves poem e verification com o poema gerado e a resposta de verificação.

Referências:

• LangChain Runnables

Usar modelos de incorporação

Crie um cliente de inserções de maneira semelhante. Defina as variáveis de ambiente para apontar para um modelo de inserções:

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 snippet de código faz: Cria uma instância de um cliente de inserções usando AzureAIEmbeddingsModel para converter texto em inserções de vetor, que podem ser usadas para pesquisas semânticas e comparações de similaridade.

Referências:

• LangChain Embeddings

Use um repositório de vetores na memória:

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

O que este snippet de código faz: Cria um repositório de vetores na memória (InMemoryVectorStore) que armazena inserções para operações de pesquisa de similaridade rápida.

Referências:

• Repositórios de Vetores 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 snippet de código faz: Converte documentos em inserções usando o cliente de inserções e os adiciona ao repositório de vetores para recuperação posterior.

Referências:

• Repositórios de Vetores LangChain

Pesquise por similaridade:

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

O que este snippet de código faz: Executa uma pesquisa semântica no repositório de vetores, retornando documentos mais semelhantes à consulta com base na similaridade de inserção. Saída esperada: lista de documentos relevantes classificados por pontuação de similaridade.

Usar os modelos da Azure OpenAI

Ao usar 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 snippet faz: instancia um cliente configurado especificamente para modelos do Azure OpenAI usando o formato de endpoint Azure OpenAI. O parâmetro endpoint aponta para o recurso Azure OpenAI e o credential usa a chave de API armazenada na variável de ambiente.

Referências:

• Integração de IA do LangChain com Azure

Depuração e solução de problemas

Se você precisar depurar seu aplicativo e entender as solicitações enviadas aos modelos no Foundry, use os recursos de depuração da integração:

Primeiro, configure o log para o 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 snippet faz: Configura o registro de logs no Python no nível DEBUG para capturar informações detalhadas sobre solicitações HTTP e respostas entre o LangChain e a API de Inferência da Modelo.

Referências:

• Módulo de registro em log do Python

Para ver as cargas de solicitação, passe logging_enable=True para dentro 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 snippet de código faz: Cria um cliente com logging habilitado para capturar e exibir conteúdos detalhados de solicitação/resposta, útil para auxiliar na depuração de interações de API.

Use o cliente como de costume em seu código.

Rastreamento

Use o rastreamento na Foundry criando um rastreador. Os logs são armazenados no Aplicativo Azure Insights e podem ser consultados a qualquer momento usando Azure Monitor ou o portal do Foundry. Cada hub de IA tem uma instância associada do Aplicativo Azure Insights.

Obtenha sua cadeia de conexão de instrumentação

Você pode configurar seu aplicativo para enviar telemetria ao Aplicativo Azure Insights usando um dos seguintes métodos:

1. Use a cadeia de conexão para o Aplicativo Azure Insights diretamente.

   1. Vá para o portal do Foundry e selecione Rastreamento.

   2. Selecione Gerenciar fonte de dados. Nesta tela, você pode ver a instância associada ao projeto.

   3. Copie o valor na cadeia de conexão e defina-o para a seguinte variável:

      import os
      
      application_insights_connection_string = "instrumentation...."
      

2. Use o Microsoft Foundry SDK e o ponto de extremidade do projeto Foundry.

   1. Verifique se você tem o pacote azure-ai-projects instalado em seu ambiente.

   2. Vá para o portal do Foundry.

   3. Copie a URL do ponto de extremidade do projeto do 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 gerenciar rastreamentos.

Próximas etapas

• Desenvolver aplicativos com LlamaIndex
• Visualizar e gerenciar rastreamentos na Foundry
• Usar modelos de fundições
• Referência: API de Inferência de Modelo