Chat básico con Azure AI Foundry - Ejemplo de principio a fin

Este ejemplo es una aplicación simple de Spring Boot que se conecta a un modelo de Azure AI Foundry usando autenticación sin clave (Microsoft Entra ID) y prueba tu configuración. Usa el ChatClient de Spring AI.

Tabla de contenido

• Requisitos previos
• Inicio rápido
• Cómo funciona la autenticación
• Ejecutando la aplicación
  • Usando Maven
  • Usando VS Code
  • Salida esperada
• Referencia de configuración
  • Variables de entorno
  • Configuración de Spring
• Resolución de problemas
  • Problemas comunes
  • Modo de depuración
• Siguientes pasos
• Recursos

Requisitos previos

Antes de ejecutar este ejemplo, asegúrate de tener:

• Un recurso de Azure AI Foundry con un despliegue gpt-4o-mini — provisionado con azd up o manualmente mediante la guía de configuración de Azure AI Foundry
• El rol Cognitive Services OpenAI User en ese recurso (las plantillas Bicep asignan esto automáticamente)
• La CLI de Azure (az), con sesión iniciada usando az login
• Java 21+ y Maven 3.9+

No se requiere clave API — la autenticación es sin clave mediante Microsoft Entra ID.

Inicio rápido

# 1. Navega al proyecto
cd 02-SetupDevEnvironment/examples/basic-chat-azure

# 2. Inicia sesión para que la autenticación sin clave pueda obtener un token
az login

# 3. Configura el endpoint
#    - Si ejecutaste `azd up`, se escribió .env por ti (omite esto).
#    - De lo contrario, copia la plantilla y configura AZURE_OPENAI_ENDPOINT:
cp .env.example .env

# 4. Ejecuta la aplicación
mvn spring-boot:run

Cómo funciona la autenticación

Este ejemplo se autentica con Microsoft Entra ID — no hay clave API.

Cuando solo se configura spring.ai.azure.openai.endpoint (y no la api-key), Spring AI crea el cliente Azure OpenAI con DefaultAzureCredential. Esta credencial automáticamente obtiene un token de tu sesión local de az login, o de una identidad administrada cuando se ejecuta en Azure — por lo que el mismo código funciona en ambos entornos sin cambios.

Ejecutando la aplicación

Usando Maven

mvn spring-boot:run

Usando VS Code

1. Abre el proyecto en VS Code
2. Presiona F5 o usa el panel "Run and Debug"
3. Selecciona la configuración "Spring Boot-BasicChatApplication"

Nota: La configuración de VS Code carga automáticamente tu archivo .env

Salida esperada

Starting Basic Chat with Azure OpenAI...
Environment variables loaded successfully
Connecting to Azure OpenAI...
Sending prompt: What is AI in a short sentence? Max 100 words.

AI Response:
================
AI, or Artificial Intelligence, is the simulation of human intelligence in machines programmed to think and learn like humans.
================

Success! Azure OpenAI connection is working correctly.

Referencia de configuración

Variables de entorno

Variable	Descripción	Requerida	Ejemplo
AZURE_OPENAI_ENDPOINT	URL del endpoint de Foundry (Azure OpenAI)	Sí	https://my-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT	Nombre del despliegue del modelo de chat	No	gpt-4o-mini (por defecto)

No existe una variable para clave API — la autenticación es sin clave (Microsoft Entra ID vía az login).

Configuración de Spring

El archivo application.yml configura:

• Endpoint: ${AZURE_OPENAI_ENDPOINT} - Desde variable de entorno
• Despliegue: ${AZURE_OPENAI_DEPLOYMENT:gpt-4o-mini} - Desde variable de entorno con valor por defecto
• Autenticación: sin clave — no se establece api-key, por lo que Spring AI usa DefaultAzureCredential
• Temperatura: 0.7 - Controla creatividad (0.0 = determinista, 1.0 = creativo)
• Tokens máximos: 500 - Longitud máxima de respuesta

Resolución de problemas

Problemas comunes

Error: 401 / "PermissionDenied" / errores de token

• Ejecuta az login — la autenticación sin clave necesita una sesión activa para obtener token
• Verifica que tu cuenta tenga el rol Cognitive Services OpenAI User en el recurso
• Si acabas de asignar el rol, espera un minuto para que se propague
• Confirma que estás en el tenant/suscripción correctos (az account show)

Error: "El endpoint no es válido" / errores de conexión

• Asegúrate que AZURE_OPENAI_ENDPOINT es la URL base completa (e.g., https://your-resource.openai.azure.com/)
• Verifica la consistencia con la barra diagonal al final
• Confirma que el endpoint coincide con tu recurso provisionado (azd env get-values)

Error: "No se encontró el despliegue"

• Verifica que AZURE_OPENAI_DEPLOYMENT coincide con un nombre de despliegue en Azure
• Asegúrate que el modelo está desplegado y activo
• El nombre por defecto del despliegue es gpt-4o-mini

VS Code: Variables de entorno no cargan

• Asegúrate que el archivo .env esté en el directorio raíz del proyecto (al mismo nivel que pom.xml)
• Intenta ejecutar mvn spring-boot:run en la terminal integrada de VS Code
• Verifica que la extensión de Java para VS Code esté correctamente instalada

Modo de depuración

Para habilitar registro detallado, descomenta estas líneas en application.yml:

logging:
  level:
    org.springframework.ai: DEBUG
    com.azure: DEBUG

Siguientes pasos

¡Configuración completa! Continúa tu aprendizaje:

Capítulo 3: Técnicas centrales de IA generativa

Recursos

• Documentación Spring AI Azure OpenAI
• Autenticación sin clave con Microsoft Entra ID
• Portal Azure AI Foundry
• Documentación Azure AI Foundry

---

Descargo de responsabilidad: Este documento ha sido traducido utilizando el servicio de traducción automática Co-op Translator. Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción.