Elección de un punto de conexión y un SDK

Completado

Microsoft Foundry proporciona flexibilidad para desarrollar aplicaciones de chat de IA generativas. Antes de comenzar el desarrollo, es importante comprender las opciones disponibles y cómo decidir cuáles de ellos usar. Algunas consideraciones para desarrollar una aplicación incluyen:

• Puntos de conexión: los proyectos de Microsoft Foundry proporcionan dos puntos de conexión que puede usar para conectarse y consumir recursos de proyecto, como implementaciones de modelos, desde aplicaciones cliente. Cada proyecto tiene un punto de conexión de Project y un punto de conexión de Azure OpenAI.
• SDK de cliente: en función del punto de conexión que seleccione, puede elegir usar el SDK de Microsoft Foundry o el SDK de OpenAI para desarrollar una aplicación de chat de IA generativa. Ambos SDK admiten un objeto de cliente compatible con openAI API que puede enviar mensajes a modelos, pero hay algunas diferencias en la funcionalidad específica disponible en cada SDK.
• Autenticación: según el punto de conexión y el SDK que elija usar, hay varias formas en que Foundry puede autenticar una aplicación cliente para conceder acceso a los recursos. En general, las aplicaciones de producción deben usar la autenticación de Id. de Entra de Microsoft , que requiere que la aplicación se ejecute en el contexto de una identidad específica; pero en algunos escenarios también puede usar la autenticación basada en claves o basada en tokens .
• Api de chat: la API de cliente de OpenAI admite dos API de chat: ChatCompletions y Respuestas. Aunque se recomienda la API de respuestas para la mayoría de los nuevos proyectos de desarrollo, la API chatCompletions es bien establecida y compatible en muchos modelos y plataformas de IA generativos.

Comencemos teniendo en cuenta los puntos de conexión, los SDK de cliente y los métodos de autenticación disponibles: exploraremos las API De respuestas y ChatCompletions más adelante.

Uso del SDK de Foundry con el punto de conexión del proyecto

El SDK Foundry de Microsoft proporciona acceso mediante programación a los recursos en tus proyectos a través de una API REST y bibliotecas cliente específicas del lenguaje; incluyendo:

• proyectos de IA de Azure para Python
• proyectos de IA de Azure para Microsoft .NET
• Proyectos de Azure AI para JavaScript

Nota:

En este módulo se usan ejemplos de código de Python para tareas comunes. Puede consultar la documentación del SDK específico del lenguaje para obtener código equivalente en su idioma preferido. Cada SDK se desarrolla y mantiene de forma independiente, por lo que algunas funcionalidades pueden estar en distintas fases de implementación.

Instalar el SDK

Para usar la biblioteca de proyectos de IA de Azure en Python, instale el paquete azure-ai-projects de PyPI junto con paquetes auxiliares:

pip install azure-ai-projects azure-identity openai

Nota:

Al usar el SDK de Foundry para desarrollar una aplicación de chat, también debe importar el paquete del SDK de OpenAI: la funcionalidad del cliente de chat en el SDK de Foundry se deriva del SDK de OpenAI.

Conectarse al punto final del proyecto

Cada proyecto Foundry tiene un punto de conexión único que puede encontrar en la página de Overview del proyecto en el portal de Foundry en https://ai.azure.com.

El punto final del proyecto sigue este formato:

https://{resource-name}.services.ai.azure.com/api/projects/<project-name>

Use este punto de conexión para crear un objeto AIProjectClient :

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project_endpoint = "https://{resource-name}.services.ai.azure.com/api/projects/<project-name>"
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=project_endpoint
)

Nota:

El código usa las credenciales de Azure predeterminadas para autenticarse. Para habilitar esta autenticación, debe instalar el paquete azure-identity (que se muestra anteriormente en el comando de instalación).

Sugerencia

Para acceder al proyecto correctamente, el código debe ejecutarse en una sesión de Azure autenticada. Por ejemplo, puede usar el comando Azure CLI az login para iniciar sesión antes de ejecutar el código.

El cliente del proyecto (AIProjectClient) proporciona acceso a las operaciones nativas de Foundry que no tienen equivalentes de OpenAI. Use el cliente de project para:

• Recuperar conexiones de recursos
• Acceso a la configuración del proyecto
• Habilitar seguimiento
• Administración de conjuntos de datos e índices

Creación de un cliente de chat

Para chatear con un modelo en el proyecto Foundry, necesita un objeto de cliente compatible con OpenAI. Puede usar el método get_openai_client() del cliente del proyecto para obtener uno, de la siguiente manera:

openai_client = project_client.get_openai_client(api_version="2024-10-21")

A continuación, puede usar este objeto de cliente de chat para enviar mensajes a modelos y devolver respuestas.

Uso del SDK de OpenAI con el punto de conexión de Azure OpenAI

El SDK de OpenAI es la biblioteca cliente oficial para llamar a la API de OpenAI. Controla las solicitudes HTTP, la autenticación, los reintentos y el análisis de respuestas. El SDK funciona con modelos hospedados en OpenAI, implementaciones de Azure OpenAI y modelos Foundry con los mismos patrones.

Instalar el SDK

Para usar la biblioteca de OpenAI en Python, instale el paquete openai desde PyPI junto con los paquetes auxiliares:

pip install openai azure-identity

Nota:

El paquete azure-identity es necesario si tiene previsto usar la autenticación basada en tokens para conectarse al punto de conexión mediante credenciales de Id. de Microsoft Entra.

Conexión al punto de conexión de Azure OpenAI

Cada proyecto foundry incluye un punto de conexión de Azure OpenAI que puede encontrar en la página Información general del proyecto en el portal de Foundry en https://ai.azure.com.

El punto de conexión de Azure OpenAI sigue este formato:

https://{resource-name}.openai.azure.com/openai/v1

Cree un cliente de OpenAI con el punto de conexión y las credenciales de Azure:

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

openai_client = OpenAI(  
  base_url = "https://{resource-name}.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

Además del identificador de Entra de Microsoft (recomendado), puede autenticarse mediante una clave de API o variables de entorno.

Autenticación de clave de API:

import os
from openai import OpenAI

openai_client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://{resource-name}.openai.azure.com/openai/v1/"
)

Importante

Use las claves de API con precaución. Almacénelos de forma segura en Azure Key Vault y nunca los incluya directamente en el código.

Variables de entorno:

Si establece las variables de entorno OPENAI_BASE_URL y OPENAI_API_KEY, el cliente las usa automáticamente.

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

Independientemente de cómo decida autenticarse, el cliente de OpenAI controla las operaciones de inferencia del modelo. Úselo para:

• Generación de respuestas con la API de respuestas
• Finalizaciones de chat e generación de imágenes
• Acceso a los modelos directos de Foundry (modelos que no son de Azure OpenAI)

Uso de un objeto de cliente AzureOpenAI

Por lo general, debe usar el objeto de cliente de OpenAI para chatear con modelos a través del punto de conexión de Azure OpenAI v1. Sin embargo, también tiene la opción de crear un objeto de cliente AzureOpenAI si necesita usar la funcionalidad de una versión específica de la API de Azure OpenAI. Para crear un objeto de cliente AzureOpenAI , debe especificar la versión de la API y el punto de conexión de Azure, de la siguiente manera:

import os
from openai import AzureOpenAI
    
openai_client = AzureOpenAI(
    azure_endpoint = "https://{resource-name}.openai.azure.com"
    api_key=os.getenv("AZURE_OPENAI_KEY"),  
    api_version="2024-10-21",
)

Elección entre el SDK de Foundry y el SDK de OpenAI

Microsoft Foundry admite dos enfoques para compilar aplicaciones de inteligencia artificial. Cada uno sirve para diferentes propósitos y comprender cuándo usar cada uno de ellos le ayuda a crear la solución adecuada.

Cuándo usar el SDK de Foundry

Use el SDK de Foundry cuando la aplicación necesite funcionalidades específicas de Foundry:

• Servicio de agente de Foundry para desarrollar y administrar agentes de inteligencia artificial
• Flujos de trabajo de invocación y aprobación de herramientas
• Evaluaciones en la nube para probar y validar respuestas de IA
• Seguimiento y observabilidad para supervisar el comportamiento de la aplicación
• Modelos directos de Foundry (modelos que no son de Azure OpenAI disponibles a través del catálogo de modelos)
• Características de gobernanza, conexiones y metadatos del proyecto

Microsoft recomienda el SDK de Foundry al compilar aplicaciones con agentes, evaluaciones o características específicas de Foundry.

Cuándo usar el SDK de OpenAI

Use el SDK de OpenAI cuando necesite la compatibilidad máxima con la API de OpenAI:

• Compatibilidad completa de la API de OpenAI para el código y las herramientas existentes
• Portabilidad entre implementaciones de OpenAI y Azure OpenAI
• Finalizaciones de chat, respuestas e imágenes API
• Dependencia mínima en conceptos específicos de Foundry

El SDK de OpenAI es ideal para cargas de trabajo de inferencia de modelos en las que desea que el código openAI existente funcione con cambios mínimos. Sin embargo, este enfoque no proporciona características específicas de Foundry, como agentes o evaluaciones.

Microsoft Foundry le ofrece flexibilidad en la forma en que crea aplicaciones de inteligencia artificial. Use el SDK de Foundry con AIProjectClient cuando necesite características de nivel de proyecto como agentes, evaluaciones, seguimiento y conexiones. Use el SDK de OpenAI cuando necesite una inferencia de modelo sencilla con la compatibilidad máxima de OpenAI. Ambos SDK funcionan con el punto de conexión del proyecto Foundry, por lo que puede combinarlos según sea necesario en las aplicaciones. También puede usar ambos SDK juntos en la misma aplicación: el SDK de Foundry para las características del proyecto y el SDK de OpenAI para la inferencia de modelos.