Desplegando Tu Modelo de IA a Producción: Una Guía Práctica

Has conectado tus datos, entrenado tu modelo y lo has probado en el chat playground. Ahora es hora de desplegarlo a producción e integrarlo en tu aplicación.

Esta guía te lleva a través del despliegue de tu modelo de IA usando la API lista para producción de Cuadra AI, desde obtener tus claves de API hasta manejar escenarios del mundo real.

Prerrequisitos

Antes de desplegar, asegúrate de haber completado:

✅ Fase Conectar - Tus datasets están creados y los archivos procesados
✅ Fase Entrenar - Tu modelo está configurado con instrucciones y datasets adjuntos
✅ Pruebas - Has probado tu modelo en el chat playground y verificado que funciona correctamente

Obteniendo Tus Credenciales de API

El primer paso es obtener tu endpoint de API y clave de autenticación.

Paso 1: Navega a la Sección Desplegar

Ve a tu modelo en el dashboard
Haz clic en la pestaña Desplegar
Verás tu endpoint de API y clave de autenticación

Paso 2: Copia Tus Credenciales

Verás:

Endpoint de API - La URL única de API de tu modelo
Clave de API - Tu token de autenticación (¡mantén esto seguro!)

Importante: Trata tu clave de API como una contraseña. Nunca la comprometas en control de versiones ni la expongas en código del lado del cliente.

Paso 3: Regenera si es Necesario

Si necesitas regenerar tu clave de API:

Haz clic en "Regenerar Clave de API"
Confirma la acción
Actualiza tu aplicación con la nueva clave
La clave antigua ya no funcionará

Entendiendo la API

Cuadra AI proporciona una API REST estándar que es fácil de integrar en cualquier aplicación.

Conceptos Básicos de la API

Protocolo: HTTPS
Formato: Solicitud/respuesta JSON
Autenticación: Clave de API en el header Authorization
Método: POST para solicitudes de chat

Estructura de Solicitud

json

{
  "message": "El mensaje de tu usuario aquí",
  "stream": false,
  "responseFormat": {
    "type": "json_schema",
    "json_schema": {
      // Opcional: Esquema JSON para salidas estructuradas
    }
  }
}

Estructura de Respuesta

json

{
  "response": "El texto de respuesta de la IA",
  "usage": {
    "input_tokens": 150,
    "output_tokens": 200,
    "total_tokens": 350
  }
}

Ejemplos de Integración

JavaScript/Node.js

javascript

async function callCuadraAPI(userMessage) {
  const response = await fetch('TU_ENDPOINT_API', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CUADRA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: userMessage,
      stream: false
    })
  });

  if (!response.ok) {
    throw new Error(`Error de API: ${response.status}`);
  }

  const data = await response.json();
  return data.response;
}

// Uso
const answer = await callCuadraAPI("¿Cuáles son sus políticas de devolución?");
console.log(answer);

Python

python

import requests
import os

def call_cuadra_api(user_message):
    url = os.getenv('CUADRA_API_ENDPOINT')
    headers = {
        'Authorization': f"Bearer {os.getenv('CUADRA_API_KEY')}",
        'Content-Type': 'application/json'
    }
    data = {
        'message': user_message,
        'stream': False
    }
    
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    
    return response.json()['response']

# Uso
answer = call_cuadra_api("¿Cuáles son sus políticas de devolución?")
print(answer)

Respuestas en Streaming

Para mejor experiencia de usuario, usa streaming:

javascript

async function streamCuadraAPI(userMessage, onToken) {
  const response = await fetch('TU_ENDPOINT_API', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CUADRA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: userMessage,
      stream: true  // Habilita streaming
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n').filter(line => line.trim());

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        if (data.token) {
          onToken(data.token);  // Callback para cada token
        }
      }
    }
  }
}

// Uso
let fullResponse = '';
streamCuadraAPI("Cuéntame sobre tus productos", (token) => {
  fullResponse += token;
  // Actualiza UI con cada token para visualización en tiempo real
  updateChatUI(fullResponse);
});

Mejores Prácticas para Producción

1. Variables de Entorno

Nunca codifiques claves de API. Usa variables de entorno:

bash

# Archivo .env
CUADRA_API_ENDPOINT=https://api.cuadra.ai/v1/models/tu-modelo-id
CUADRA_API_KEY=tu-clave-api-aqui

2. Manejo de Errores

Implementa manejo robusto de errores:

javascript

async function callCuadraAPIWithRetry(userMessage, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('TU_ENDPOINT_API', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.CUADRA_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ message: userMessage })
      });

      if (response.status === 429) {
        // Límite de tasa - espera y reintenta
        const waitTime = Math.pow(2, attempt) * 1000; // Retroceso exponencial
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      if (!response.ok) {
        throw new Error(`Error de API: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      // Espera antes de reintentar
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

3. Límites de Tasa

Respeta los límites de tasa e implementa throttling del lado del cliente:

Verifica los límites de tasa de tu plan
Implementa cola de solicitudes si es necesario
Usa retroceso exponencial para respuestas 429
Monitorea tu uso en el dashboard

4. Manejo de Timeouts

Establece timeouts apropiados:

javascript

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // Timeout de 30 segundos

try {
  const response = await fetch('TU_ENDPOINT_API', {
    signal: controller.signal,
    // ... otras opciones
  });
  clearTimeout(timeoutId);
} catch (error) {
  if (error.name === 'AbortError') {
    // Maneja timeout
  }
}

5. Registro y Monitoreo

Rastrea tu uso de API:

javascript

async function callCuadraAPI(userMessage) {
  const startTime = Date.now();
  
  try {
    const response = await callCuadraAPI(userMessage);
    const duration = Date.now() - startTime;
    
    // Registra solicitud exitosa
    logMetrics({
      success: true,
      duration,
      tokens: response.usage.total_tokens
    });
    
    return response;
  } catch (error) {
    // Registra error
    logMetrics({
      success: false,
      duration: Date.now() - startTime,
      error: error.message
    });
    throw error;
  }
}

Salidas Estructuradas

Para respuestas consistentes y parseables, usa esquema JSON:

javascript

const response = await fetch('TU_ENDPOINT_API', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CUADRA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: "¿Cuáles son sus políticas de devolución?",
    responseFormat: {
      type: "json_schema",
      json_schema: {
        name: "return_policy_response",
        schema: {
          type: "object",
          properties: {
            policy: { type: "string" },
            timeframe: { type: "string" },
            conditions: { type: "array", items: { type: "string" } }
          },
          required: ["policy", "timeframe"]
        }
      }
    }
  })
});

Consideraciones de Seguridad

Seguridad de Claves de API

Solo del Lado del Servidor - Nunca expongas claves de API en código del lado del cliente
Variables de Entorno - Almacena claves en variables de entorno
Rotación - Rota claves periódicamente
Control de Acceso - Limita quién puede acceder a las claves de API

Privacidad de Datos

Cifrado - Usa HTTPS para todas las llamadas a la API
Minimización de Datos - Solo envía datos necesarios
Cumplimiento - Asegura cumplimiento con GDPR, CCPA, etc.
Registros de Auditoría - Registra el uso de API para auditorías de seguridad

Monitoreo y Análisis

Dashboard de Uso

Monitorea tu despliegue en el dashboard de Cuadra AI:

Llamadas a la API - Rastrea el volumen de solicitudes
Uso de Tokens - Monitorea el consumo de tokens
Costos - Ve costos por modelo
Rendimiento - Rastrea tiempos de respuesta

Análisis Personalizados

Implementa tus propios análisis:

Rastrea satisfacción del usuario
Monitorea calidad de respuestas
Mide métricas de negocio (tasa de resolución, etc.)
Identifica preguntas comunes

Solución de Problemas

Problemas Comunes

Problema: 401 No Autorizado

Verifica que tu clave de API sea correcta
Verifica que la clave no haya sido regenerada
Asegúrate de que el formato del header Authorization sea correcto

Problema: 429 Límite de Tasa

Verifica los límites de tasa de tu plan
Implementa throttling de solicitudes
Usa retroceso exponencial

Problema: Respuestas Lentas

Verifica la configuración de tu modelo
Revisa el tamaño de la base de conocimiento
Considera usar streaming para mejor UX
Monitorea el rendimiento de la API en el dashboard

Problema: Respuestas Inesperadas

Revisa las instrucciones del sistema de tu modelo
Verifica que los datasets adjuntos sean correctos
Prueba en el chat playground primero
Verifica que la base de conocimiento esté actualizada

Escalando Tu Despliegue

A medida que tu uso crece:

Monitorea el Uso - Rastrea llamadas a la API y costos
Optimiza la Configuración - Refina ajustes del modelo para eficiencia
Actualiza el Plan - Considera planes de nivel superior para más recursos
Almacena en Caché Respuestas - Almacena en caché consultas comunes cuando sea apropiado
Balanceo de Carga - Distribuye solicitudes en múltiples endpoints si es necesario

Próximos Pasos

¡Ahora estás listo para desplegar tu modelo de IA a producción! Recuerda:

Protege Tus Claves - Mantén las claves de API seguras y nunca las expongas
Maneja Errores - Implementa manejo robusto de errores
Monitorea el Uso - Rastrea rendimiento y costos
Itera - Mejora continuamente basado en uso del mundo real

Comienza a desplegar tu modelo y ve qué tan fácil es integrar IA en tu aplicación.

¿Necesitas ayuda con el despliegue? Consulta nuestra documentación de API o contacta soporte.

Desplegando Tu Modelo

de IA a Producción:

Una Guía Práctica

Desplegando Tu Modelo de IA a Producción: Una Guía Práctica

Prerrequisitos

Obteniendo Tus Credenciales de API

Paso 1: Navega a la Sección Desplegar

Paso 2: Copia Tus Credenciales

Paso 3: Regenera si es Necesario

Entendiendo la API

Conceptos Básicos de la API

Estructura de Solicitud

Estructura de Respuesta

Ejemplos de Integración

JavaScript/Node.js

Python

Respuestas en Streaming

Mejores Prácticas para Producción

1. Variables de Entorno

2. Manejo de Errores

3. Límites de Tasa

4. Manejo de Timeouts

5. Registro y Monitoreo

Salidas Estructuradas

Consideraciones de Seguridad

Seguridad de Claves de API

Privacidad de Datos

Monitoreo y Análisis

Dashboard de Uso

Análisis Personalizados

Solución de Problemas

Problemas Comunes

Escalando Tu Despliegue

Próximos Pasos

Helpful Resources