Desarrollo de aplicaciones con LlamaIndex y Microsoft Foundry

En este artículo, aprenderá a usar LlamaIndex con modelos implementados desde el catálogo de modelos en Microsoft Foundry.

Puede usar modelos implementados en Microsoft Foundry con LlamaIndex de dos maneras:

• Usar la API específica del proveedor del modelo: algunos modelos, como OpenAI, Cohere o Mistral, ofrecen su propio conjunto de API y extensiones para LlamaIndex. Estas extensiones pueden incluir funcionalidades específicas que admiten el modelo y, por tanto, son adecuadas si desea aprovecharlas. Al trabajar con llama-index, instale la extensión específica para el modelo que quiere usar, como llama-index-llms-openai o llama-index-llms-cohere.

• Uso de la API de inferencia de modelos de Azure AI: Todos los modelos implementados en Foundry admiten la API de inferencia de modelos, que ofrece un conjunto común de funcionalidades que puede ser utilizada por la mayoría de los modelos del catálogo. La ventaja de esta API es que, puesto que es la misma para todos los modelos, cambiar de uno a otro es tan sencillo como cambiar la implementación de modelo que se está usando. No se requieren más cambios en el código. Al trabajar con LlamaIndex, instale las extensiones llama-index-llms-azure-inference y llama-index-embeddings-azure-inference.

En este ejemplo, trabajará con la API de inferencia de modelos.

Prerrequisitos

Para ejecutar este tutorial, necesitará:

• Una cuenta de Azure con una suscripción activa. Si no tiene una, cree una cuenta gratuita de Azure, que incluye una suscripción de evaluación gratuita.
• Un proyecto Foundry.

• Rol obligatorio:
  • Propietario o Colaborador en el recurso Foundry o el Centro de IA para la implementación de modelos
  • Usuario de Azure AI para usar el modelo en un proyecto Foundry
  • Desarrollador de Azure AI para usar el modelo en un proyecto basado en hub

• Implementación de un modelo que permite la API de Inferencia de Modelos . En este artículo se usan Mistral-Large-3 en ejemplos de código; puede sustituir su propio nombre de modelo implementado.

• Para usar las funcionalidades de inserción en LlamaIndex, necesita un modelo de inserción como cohere-embed-v3-multilingual.

  • Puede seguir las instrucciones de Implementación de modelos como implementaciones de API sin servidor.

• Python 3.8 o posterior instalado, incluido pip.

• LlamaIndex instalado. Puede instalarlo mediante el comando siguiente:

  pip install llama-index
  

• En este ejemplo, va a trabajar con la API de inferencia de modelos, por lo que instalará los siguientes paquetes:

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

  Importante

  El uso del servicio Foundry Models requiere una versión 0.2.4 para llama-index-llms-azure-inference o llama-index-embeddings-azure-inference.

Configuración del entorno

Para usar los LLM implementados en el portal de Microsoft Foundry, necesita el punto de conexión y las credenciales para conectarse a él. Siga estos pasos para obtener la información que necesita del modelo que desea usar:

1. Inicie sesión en Microsoft Foundry. Asegúrese de que el botón de alternancia Foundry nuevo esté desactivado. Estos pasos hacen referencia a Foundry (clásico).

   

2. Abra el proyecto donde está implementado el modelo, si aún no está abierto.

3. Vaya a Modelos y puntos de conexión y seleccione el modelo implementado como se indica en los requisitos previos.

4. Copie la dirección URL del punto de conexión y la clave.

   

   Sugerencia

   Si el modelo se implementó con compatibilidad con Microsoft Entra ID, no necesita una clave.

En este escenario, establezca la dirección URL del punto de conexión y la clave como variables de entorno. (Si el punto de conexión que copió incluye texto adicional después de /models, quítelo para que la dirección URL finalice en /models como se muestra a continuación).

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

Después de configurar el entorno, cree un cliente para conectarse al punto de conexión.

import os
from llama_index.llms.azure_inference import AzureAICompletionsModel

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

Si el punto de conexión atiende más de un modelo, como con el servicio Foundry Models o Los modelos de GitHub, debe especificar el model_name parámetro :

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

Qué hace esto: Crea un cliente LLM con especificación explícita del nombre del modelo para los puntos de conexión de varios modelos. El model_name parámetro indica al servicio qué modelo se va a usar para las finalizaciones de chat.

Referencias:

• Integración de inferencia de LlamaIndex de Azure
• Parámetros de AzureAICompletionsModel

Como alternativa, si el punto de conexión admite el identificador de Entra de Microsoft, puede usar el código siguiente para crear el 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(),
)

Qué hace esto: Crea un cliente LLM mediante la autenticación de Microsoft Entra ID (Azure AD), que es más segura para entornos de producción que las claves de API.

Comprobación de la configuración

Pruebe la conexión de cliente con una invocación sencilla:

from llama_index.core.llms import ChatMessage

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

Qué hace esto: Llama al modelo con un mensaje sencillo para comprobar la autenticación y la conectividad. Salida esperada: un objeto de respuesta que contiene el mensaje de saludo del modelo.

Referencias:

• LlamaIndex ChatMessage
• Método de Chat LLM de LlamaIndex

Si tiene previsto usar llamadas asincrónicas, use la versión asincrónica para las credenciales:

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

Modelos de Azure OpenAI y servicio de Modelos Foundry

Si usa el servicio Azure OpenAI o Foundry Models, asegúrese de que tiene al menos una versión 0.2.4 de la integración de LlamaIndex. Use el api_version parámetro si necesita seleccionar un elemento específico api_version.

Para el servicio Foundry Models, debe pasar el 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 en modelos de 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 inferencia

Puede configurar cómo se realiza la inferencia para todas las operaciones que usan este cliente estableciendo parámetros adicionales. Este enfoque le ayuda a evitar especificarlos en cada llamada que realice al modelo.

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

Qué hace esto: Establece los parámetros de inferencia predeterminados (temperature y top_p) que se aplican a todas las llamadas de chat y finalización realizadas con este cliente. La temperatura más baja (0,0) produce salidas más deterministas; top_p controla la diversidad en el muestreo.

Referencias:

• Parámetros de la API de inferencia de modelos

Para los parámetros no admitidos en la API de inferencia de modelos (referencia), pero disponible en el modelo subyacente, use el model_extras argumento . En el ejemplo siguiente, se pasa el parámetro safe_prompt, que solo está disponible para los modelos Mistral.

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

Uso de modelos LLM

Puede usar el cliente directamente o configurar los modelos que su código utilizará en LlamaIndex. Para usar el modelo directamente, utilice el método chat para modelos de instrucción por 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)

También puede transmitir las salidas:

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

El complete método sigue estando disponible para los modelos de tipo chat-completions. En esos casos, el texto de entrada se convierte en un mensaje mediante role="user".

Uso de modelos de inserción

Al igual que crea un cliente LLM, puede conectarse a un modelo de inserción. En el ejemplo siguiente, establezca la variable de entorno para que apunte a un modelo de inserción:

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

A continuación, cree el 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>",
)

Qué hace esto: Crea una instancia de un cliente de incrustaciones para convertir texto en incrustaciones vectoriales. Las incrustaciones son representaciones numéricas del texto que se usan para búsquedas de similitud semántica y generación aumentada de recuperación (RAG).

Referencias:

• Integración de inserciones de LlamaIndex
• AzureAIEmbeddingsModel

En el ejemplo siguiente se muestra una prueba sencilla para comprobar que 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)

Qué hace esto: Convierte un nodo de texto en incrustaciones e imprime la representación vectorial numérica. Salida esperada: una lista de números de punto flotante que representa el significado semántico del texto (longitud típica: dimensiones de 384 a 1024 en función del modelo).

Referencias:

• TextNode

Configuración de los modelos que usa el código

En el código, puede usar el cliente de modelo LLM o el modelo de inserción de forma individual al trabajar con LlamaIndex, o puede configurar toda la sesión mediante opciones de Settings. Al configurar la sesión, todo el código usa los mismos modelos para todas las operaciones.

from llama_index.core import Settings

Settings.llm = llm
Settings.embed_model = embed_model

Qué hace esto: Registra globalmente los clientes LLM y embeddings para que todas las operaciones de LlamaIndex usen automáticamente estos modelos sin necesidad de pasarlos como parámetros a cada función.

Referencias:

• Configuración de LlamaIndex

Sin embargo, algunos escenarios requieren un modelo general para la mayoría de las operaciones y un modelo específico para una tarea determinada. En estos casos, configure el modelo LLM o el modelo de inserción para cada construcción de LlamaIndex. En el ejemplo siguiente se muestra cómo establecer un modelo específico:

from llama_index.core.evaluation import RelevancyEvaluator

relevancy_evaluator = RelevancyEvaluator(llm=llm)

Qué hace esto: Crea un evaluador de relevancia que usa el cliente LLM personalizado para evaluar los resultados de recuperación. Esto le permite usar diferentes modelos para diferentes tareas (por ejemplo, un modelo específico para la evaluación frente al chat general).

Referencias:

• Evaluadores de LlamaIndex

Por lo general, use una combinación de ambas estrategias.

Contenido relacionado

• Introducción a los SDK de Azure AI
• Referencia de la integración de inserciones de LlamaIndex
• Referencia para la integración de LLM de LlamaIndex