Desenvolver aplicações com LlamaIndex e Microsoft Foundry (clássico)

Aplica-se apenas a:Portal Foundry (clássico). Este artigo não está disponível para o novo portal da Foundry. Saiba mais sobre o novo portal.

Neste artigo, aprende a usar LlamaIndex com modelos implementados a partir do catálogo de modelos no Microsoft Foundry.

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

• Usando a API específica para o fornecedor do modelo: Alguns modelos, como OpenAI, Cohere ou Mistral, oferecem o seu próprio conjunto de APIs e extensões para o LlamaIndex. Essas extensões podem incluir funcionalidades específicas que o modelo suporta e, por isso, são adequadas se quiseres explorá-las. Ao trabalhar com llama-index, instale a extensão específica para o modelo que pretende usar, como llama-index-llms-openai ou llama-index-llms-cohere.

• Usando a API de Inferência de Modelos Azure IA: Todos os modelos implementados no Foundry suportam a API de Inferência de Modelos Modelo, que oferece um conjunto comum de funcionalidades que a maioria dos modelos do catálogo pode utilizar. A vantagem desta API é que, como é igual para todos os modelos, mudar de um para outro é tão simples como alterar o modelo de implementação em uso. Não são necessárias mais alterações no código. Ao trabalhar com o LlamaIndex, instale as extensões llama-index-llms-azure-inference e llama-index-embeddings-azure-inference.

Neste exemplo, trabalha com a API de Inferência de Modelos.

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.
• Um projeto da Foundry.

• 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 em exemplos de código; pode substituir pelo nome do seu próprio modelo implementado.

• Para usar funcionalidades de embeddings no LlamaIndex, precisa de um modelo de embedding como cohere-embed-v3-multilingual.

  • Pode seguir as instruções em Implementar modelos como implementações de APIs serverless.

• Python 3.8 ou posterior instalado, incluindo pip.

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

  pip install llama-index
  

• Neste exemplo, está a trabalhar com a API de Inferência de Modelos, por isso instala os seguintes pacotes:

  pip install -U llama-index-llms-azure-inference
  pip install -U llama-index-embeddings-azure-inference
  

  Importante

  Usar o serviço Foundry Models requer a versão 0.2.4 para llama-index-llms-azure-inference ou llama-index-embeddings-azure-inference.

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

Depois de configurares o ambiente, cria um cliente para se ligar ao endpoint.

import os
from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
)

Se o seu endpoint servir mais do que um modelo, como com o serviço Foundry Models ou GitHub Models, precisa de especificar o parâmetro model_name:

import os
from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model_name="Mistral-Large-3",
)

O que isto faz: Cria um cliente LLM com o nome do modelo especificado explicitamente para endpoints multimodelo. O model_name parâmetro indica ao serviço qual o modelo a usar para completar o chat.

Referências:

• Integração de Inferência do LlamaIndex com Azure
• AzureAICompletionsModel Parameters

Alternativamente, se o seu endpoint suportar o Microsoft Entra ID, pode usar o seguinte código para criar o cliente:

import os
from azure.identity import DefaultAzureCredential
from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

O que isto faz: Cria um cliente LLM usando autenticação Microsoft Entra ID (Azure AD), que é mais segura para ambientes de produção do que as chaves API.

Verifica a tua configuração

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

from llama_index.core.llms import ChatMessage

messages = [ChatMessage(role="user", content="Hello")]
response = llm.chat(messages)
print(response)

O que isto faz: Chama o modelo com uma mensagem simples para verificar autenticação e conectividade. Saída esperada: Um objeto de resposta contendo a mensagem de saudação do modelo.

Referências:

• LlamaIndex ChatMessage
• Método de Chat LLM LlamaIndex

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

from azure.identity.aio import (
    DefaultAzureCredential as DefaultAzureCredentialAsync,
)
from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredentialAsync(),
)

Azure OpenAI Models e serviço Foundry Models

Se estiveres a usar Azure serviço OpenAI ou Foundry Models, certifica-te de que tens pelo menos a versão 0.2.4 da integração com o LlamaIndex. Use o parâmetro api_version se precisar de selecionar um api_version específico.

Para o serviço Foundry Models, é necessário passar o model_name parâmetro:

from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model_name="Mistral-Large-3",
)

Para Azure OpenAI em modelos Foundry:

from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint="https://<resource>.openai.azure.com/openai/deployments/<deployment-name>",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    api_version="2024-05-01-preview",
)

Parâmetros de inferência

Pode configurar como a inferência é realizada para todas as operações que utilizam este cliente, definindo parâmetros extra. Esta abordagem ajuda-o a evitar especificá-los em cada chamada que realiza ao modelo.

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    temperature=0.0,
    model_kwargs={"top_p": 1.0},
)

O que isto faz: Define parâmetros de inferência padrão (temperature e top_p) que se aplicam a todas as chamadas de chat e conclusão feitas com este cliente. Temperaturas mais baixas (0,0) produzem resultados mais determinísticos; top_p Controla a diversidade na amostragem.

Referências:

• Parâmetros da API de Inferência de Modelos

Para parâmetros não suportados na API de Inferência de Modelos (referência) mas disponíveis no modelo subjacente, use o model_extras argumento. No exemplo seguinte, o parâmetro safe_prompt, que só está disponível para modelos de Mistral, é ultrapassado.

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    temperature=0.0,
    model_kwargs={"model_extras": {"safe_prompt": True}},
)

Utilização de modelos LLM

Pode usar o cliente diretamente ou configurar os modelos usados pelo seu código no LlamaIndex. Para usar o modelo diretamente, use o chat método para modelos de instruções de chat:

from llama_index.core.llms import ChatMessage

messages = [
    ChatMessage(
        role="system", content="You are a pirate with colorful personality."
    ),
    ChatMessage(role="user", content="Hello"),
]

response = llm.chat(messages)
print(response)

Também pode transmitir as saídas:

response = llm.stream_chat(messages)
for r in response:
    print(r.delta, end="")

O complete método ainda está disponível para modelos do tipo chat-completions. Nesses casos, o seu texto de entrada é convertido numa mensagem usando role="user".

Utilizar modelos de embeddings

Tal como crias um cliente LLM, podes ligar-te a um modelo de embeddings. No exemplo seguinte, defina a variável ambiente para apontar para um modelo de embeddings:

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

Depois cria o cliente:

from llama_index.embeddings.azure_inference import AzureAIEmbeddingsModel

embed_model = AzureAIEmbeddingsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ['AZURE_INFERENCE_CREDENTIAL'],
    model="<your-model-name>",
)

O que isto faz: Instancia um cliente de embeddings para converter texto em embeddings vetoriais. Os embeddings são representações numéricas de texto usadas para pesquisas de similaridade semântica e geração aumentada por recuperação (RAG).

Referências:

• Integração de Incorporações do LlamaIndex
• AzureAIEmbeddingsModel

O exemplo seguinte mostra um teste simples para verificar se funciona:

from llama_index.core.schema import TextNode

nodes = [
    TextNode(
        text="Before college the two main things I worked on, "
        "outside of school, were writing and programming."
    )
]
response = embed_model(nodes=nodes)
print(response[0].embedding)

O que isto faz: Converte um nó de texto em embeddings e imprime a representação vetorial numérica. Saída esperada: Uma lista de números em ponto flutuante que representa o significado semântico do texto (comprimento típico: 384–1024 dimensões dependendo do modelo).

Referências:

• TextNode

Configure os modelos que o seu código usa

No seu código, pode usar o cliente individual do modelo LLM ou do modelo de embeddings ao trabalhar com o LlamaIndex, ou pode configurar toda a sessão usando as opções Settings. Quando configuras a sessão, todo o teu código usa os mesmos modelos para todas as operações.

from llama_index.core import Settings

Settings.llm = llm
Settings.embed_model = embed_model

O que isto faz: Regista globalmente os clientes LLM e de embeddings, de modo que todas as operações do LlamaIndex usam automaticamente estes modelos sem necessidade de os passar como parâmetros para cada função.

Referências:

• Definições do LlamaIndex

No entanto, alguns cenários requerem um modelo geral para a maioria das operações e um modelo específico para uma dada tarefa. Nestes casos, configure o modelo LLM ou modelo de incorporação para cada construto LlamaIndex. O exemplo seguinte mostra como definir um modelo específico:

from llama_index.core.evaluation import RelevancyEvaluator

relevancy_evaluator = RelevancyEvaluator(llm=llm)

O que isto faz: Cria um avaliador de relevância que utiliza o seu cliente LLM personalizado para avaliar os resultados de recuperação. Isto permite usar diferentes modelos para diferentes tarefas (por exemplo, um modelo específico para avaliação vs. chat geral).

Referências:

• Avaliadores LlamaIndex

De um modo geral, usa uma combinação de ambas as estratégias.

Conteúdo relacionado

• Como começar com Azure SDKs de IA
• Referência para Integração de Embeddings do LlamaIndex
• Referência para a integração de LLMs com "LlamaIndex"