3. Proyecto base
Haz tu primera llamada al modelo
Configura Groq y completa una prueba pequeña con generateText y async/await.
Qué aprenderás
- Separar credenciales, selección del modelo y prompt.
- Leer text y usage de una respuesta.
- Ejecutar la práctica y reconocer el alcance de una prueba de conexión.
Índice de esta lección
Paso 1
Prepara tu acceso a Groq
Abre la consola oficial de Groq y entra en API Keys. Si no tienes cuenta, crea una siguiendo el proceso del proveedor. Para esta práctica basta un proveedor; no necesitas configurar todos los adaptadores.
Crea una clave con un nombre que identifique esta práctica y una expiración adecuada. Guarda el valor únicamente en tu .env local. Consulta las cuotas, condiciones y modelos disponibles en tu cuenta: los ejemplos del curso no garantizan acceso o gratuidad permanente.
Proveedor: GroqConsola: https://console.groq.com/keysVariable local: GROQ_API_KEYPrueba inicial: OK, todo listo!Qué deberías observar
Puedes identificar dónde crear tu clave y dónde guardarla sin compartir su valor.
Paso 2
Configura la credencial fuera del código
En la raíz de tu práctica, crea .env y añade tu propia credencial de Groq. Si clonaste el proyecto publicado, copia .env.example a .env. Completa GROQ_API_KEY solo en .env; deja vacía la plantilla pública. El adaptador lee esta variable del entorno.
Revisa que el valor esté completo y sin espacios accidentales. Mantén .env y sus variantes fuera de Git, junto con node_modules/ y dist/. No incluyas credenciales en capturas, apuntes o ejercicios.
GROQ_API_KEY=REEMPLAZA_CON_TU_CREDENCIALQué deberías observar
El archivo .env existe en tu práctica y contiene tu credencial. Los scripts lo cargan mediante --env-file=.env.
Paso 3
Centraliza el proveedor elegido
Crea src/helpers/selected-model.ts. Este es el adaptador y el identificador seleccionados en el material actual.
Cambiar el identificador cambia el modelo que solicita tu aplicación. Si el proveedor lo retira o tu cuenta no tiene acceso, verifica su catálogo; el nombre que figura en un ejemplo no garantiza disponibilidad permanente.
import { groq } from '@ai-sdk/groq'; export const model = groq('openai/gpt-oss-20b');Qué deberías observar
La acción podrá importar model sin conocer el identificador concreto en cada llamada.
Paso 4
Envía una instrucción pequeña
Crea src/actions/get-message-model.ts. generateText recibe model y prompt; await espera a que la promesa se resuelva antes de usar text.
usage permite observar el consumo comunicado por el proveedor. Cuando totalTokens no está disponible, mostramos ese estado en lugar de inventar un cero. Mantén el prompt pequeño para establecer una primera referencia.
import { generateText } from 'ai';import { model } from '../helpers/selected-model.js'; export async function getMessageFromModel() { const { text, usage } = await generateText({ model, prompt: 'Responde solamente con: "OK, todo listo!"', }); console.log('Respuesta del modelo:', text.trim()); console.log('Tokens:', usage.totalTokens ?? 'No disponible');}Qué deberías observar
Con credenciales, red y modelo disponibles, la consola muestra la respuesta y los tokens reportados. Comprueba si el texto cumple la instrucción; no lo asumas.
Paso 5
Conecta la entrada y ejecuta
Crea src/main.ts con esta llamada. Después, desde la raíz de la práctica, ejecuta npm run build y npm run dev.
El build valida y compila. dev ejecuta TypeScript y hace la petición real. Una respuesta correcta demuestra que la conexión funciona para este caso; todavía no hemos añadido herramientas ni un ciclo agéntico.
import { getMessageFromModel } from './actions/get-message-model.js'; await getMessageFromModel();Qué deberías observar
El build termina sin errores. dev imprime la respuesta si la llamada tiene éxito; si falla, la lección de errores te ayuda a ubicar el problema.
Paso 6
Comprueba la conexión y diagnostica un fallo
Ejecuta npm run dev y comprueba la respuesta real. El prompt pide “OK, todo listo!”; el color del texto depende de la variante que ejecutes y no demuestra por sí mismo que la configuración sea correcta.
Si falla, revisa primero que los scripts carguen .env, que exista GROQ_API_KEY y que selected-model.ts use groq con un modelo disponible. La variante getMessageFromModelFailSafe del proyecto base ayuda a distinguir credenciales, permisos, cuotas y fallos de red. La lección Maneja los errores muestra cómo implementarla en tu práctica mínima.
No provoques un fallo publicando ni mostrando una clave. Ante un problema de permisos revisa la credencial y la cuenta; ante límites de uso consulta las cuotas antes de repetir. Capturar un error no corrige su causa.
import { getMessageFromModelFailSafe } from './actions/get-message-model.js'; await getMessageFromModelFailSafe();Qué deberías observar
Puedes explicar qué revisar si la llamada falla y volver a la función normal cuando la conexión esté verificada.
Ahora te toca
Prueba la idea por tu cuenta
Cambia la instrucción por “Responde solamente con: conexión verificada”. Ejecuta de nuevo y compara el texto recibido con lo solicitado. Antes, verifica que .env esté excluido de Git y que .env.example permanezca sin claves.
Necesito una pista
Cambia únicamente prompt en la acción y conserva el modelo y el punto de entrada.
Comparar con una solución
Tras cambiar prompt, ejecuta npm run dev. Registra la respuesta real y verifica el cumplimiento; el texto del modelo puede variar y una sola prueba no evalúa su calidad en otras tareas.
Antes de seguir
Comprueba lo que aprendiste
No es una nota. Es una pausa para comprobar que la idea quedó clara.
¿Terminaste la práctica?
Haz el ejercicio y comprueba tus respuestas antes de marcar la lección como completada.