Integración de Lumi o1 Mini con Python

Esta guía te mostrará cómo integrar y utilizar la API del modelo Lumi o1 Mini de LunaVerseX en tus aplicaciones Python. Cubriremos desde la configuración inicial hasta ejemplos prácticos de solicitudes, manejo de streaming y errores.

Configuración del Entorno (Recomendado)

Antes de comenzar, es una buena práctica crear un entorno virtual para tu proyecto Python. Esto ayuda a manejar las dependencias de forma aislada.


# Crear un entorno virtual (por ejemplo, llamado 'lumi_env')
python -m venv lumi_env

# Activar el entorno virtual
# En Windows:
# lumi_env\Scripts\activate
# En macOS/Linux:
source lumi_env/bin/activate

Una vez activado, cualquier librería que instales con pip se instalará dentro de este entorno.

Instalación de la Librería requests

Para interactuar con la API, utilizaremos la librería requests, una herramienta estándar y muy popular para realizar solicitudes HTTP en Python. Si no la tienes instalada en tu entorno, ejecútala:

pip install requests

Obtención y Uso de tu API Key

Para autenticar tus solicitudes a la API de LunaVerseX, necesitarás una API Key. Puedes generar y administrar tus claves desde tu panel de desarrollador en el sitio de LunaVerseX. (Si aún no tienes una, visita la guía de autenticación).

¡Importante! Trata tu API Key como una contraseña. Nunca la incluyas directamente en tu código fuente si este va a ser público o compartido. Para proyectos en producción, utiliza variables de entorno o un sistema de gestión de secretos.

Ejemplo 1: Solicitud POST Básica (Respuesta Completa)

Este ejemplo muestra cómo enviar una pregunta al modelo Lumi o1 Mini y recibir la respuesta completa en formato JSON.


import requests
import json
import os # Para usar variables de entorno (recomendado)

# Intenta obtener la API Key desde una variable de entorno
API_KEY = os.getenv("LUNAVERSEX_API_KEY", "TU_API_KEY_AQUI_SI_NO_USAS_ENV") 
API_URL = "https://api.lunaversex.com/v1/chat"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "lumi-o1-mini",
    "messages": [
        {"role": "system", "content": "Eres un asistente de IA conciso y directo al grano."},
        {"role": "user", "content": "Explica brevemente qué es la computación cuántica."}
    ],
    "stream": False,
    "max_tokens": 150,
    "temperature": 0.7
}

print(f"--- Enviando solicitud a Lumi o1 Mini ---")
try:
    response = requests.post(API_URL, headers=headers, json=payload, timeout=30)
    response.raise_for_status() 

    result = response.json()
    print("\n--- Respuesta Completa (JSON) ---")
    print(json.dumps(result, indent=2, ensure_ascii=False))
    
    if result.get("choices") and len(result["choices"]) > 0:
        assistant_message = result["choices"][0].get("message", {}).get("content", "")
        print(f"\n--- Respuesta del Asistente ---")
        print(assistant_message)

except requests.exceptions.HTTPError as http_err:
    print(f"\nError HTTP: {http_err}")
    print(f"Status Code: {response.status_code}")
    try:
        print(f"Error Body: {response.json()}")
    except json.JSONDecodeError:
        print(f"Error Body (raw): {response.text}")
except requests.exceptions.Timeout:
    print("\nError: Timeout. La solicitud tardó demasiado.")
except requests.exceptions.RequestException as req_err:
    print(f"\nError de Solicitud: {req_err}")
except Exception as e:
    print(f"\nError Inesperado: {e}")

Comando cURL equivalente:


curl -X POST https://api.lunaversex.com/v1/chat \
-H "Authorization: Bearer TU_API_KEY_AQUI" \
-H "Content-Type: application/json" \
-d '{
  "model": "lumi-o1-mini",
  "messages": [
    {"role": "system", "content": "Eres un asistente de IA conciso y directo al grano."},
    {"role": "user", "content": "Explica brevemente qué es la computación cuántica."}
  ],
  "stream": false,
  "max_tokens": 150,
  "temperature": 0.7
}'

Ejemplo 2: Solicitud con Streaming

Si necesitas recibir la respuesta a medida que se genera (ideal para interfaces de chat en tiempo real), puedes habilitar el streaming.


import requests
import json
import os

API_KEY = os.getenv("LUNAVERSEX_API_KEY", "TU_API_KEY_AQUI_SI_NO_USAS_ENV")
API_URL = "https://api.lunaversex.com/v1/chat"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Accept": "text/event-stream" # Importante para streaming
}

payload = {
    "model": "lumi-o1-mini",
    "messages": [
        {"role": "user", "content": "Escribe un poema corto sobre la luna."}
    ],
    "stream": True
}

print(f"--- Enviando solicitud con Streaming a Lumi o1 Mini ---")
try:
    with requests.post(API_URL, headers=headers, json=payload, stream=True, timeout=30) as response:
        response.raise_for_status()
        print("\n--- Respuesta en Streaming ---")
        full_response_content = ""
        for line in response.iter_lines():
            if line:
                decoded_line = line.decode('utf-8')
                if decoded_line.startswith('data: '):
                    try:
                        json_data_str = decoded_line[len('data: '):]
                        if json_data_str.strip() == "[DONE]": 
                            print("\n--- Fin del Stream ---")
                            break
                        
                        event_data = json.loads(json_data_str)
                        
                        content_chunk = event_data.get("choices", [{}])[0].get("delta", {}).get("content", "")
                        if content_chunk:
                            print(content_chunk, end="", flush=True)
                            full_response_content += content_chunk
                    except json.JSONDecodeError:
                        print(f"\nError decodificando JSON en stream: {json_data_str}")
                    except Exception as e_stream:
                        print(f"\nError procesando chunk de stream: {e_stream}")
        # print(f"\n\n--- Contenido completo recibido --- \n{full_response_content}")

except requests.exceptions.HTTPError as http_err:
    print(f"\nError HTTP: {http_err}")
    print(f"Status Code: {response.status_code}")
    try:
        print(f"Error Body: {response.json()}")
    except json.JSONDecodeError:
        print(f"Error Body (raw): {response.text}")
except requests.exceptions.Timeout:
    print("\nError: Timeout. La solicitud tardó demasiado.")
except requests.exceptions.RequestException as req_err:
    print(f"\nError de Solicitud: {req_err}")
except Exception as e:
    print(f"\nError Inesperado: {e}")

Comando cURL equivalente para streaming (SSE):


curl -N -X POST https://api.lunaversex.com/v1/chat \
-H "Authorization: Bearer TU_API_KEY_AQUI" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
  "model": "lumi-o1-mini",
  "messages": [
    {"role": "user", "content": "Escribe un poema corto sobre la luna."}
  ],
  "stream": true
}'

Nota: El procesamiento exacto de los eventos de stream (data: ...) puede variar ligeramente según la implementación específica de tu API para Server-Sent Events (SSE).

Explicación Detallada

En los ejemplos anteriores:

  1. Importaciones y Configuración: Importamos requests y json. Es crucial configurar tu API_KEY de forma segura (preferiblemente mediante variables de entorno con os.getenv).
  2. Encabezados (headers):
    • Authorization: Bearer TU_API_KEY_AQUI: Autentica tu solicitud.
    • Content-Type: application/json: Indica que el cuerpo de la solicitud es JSON.
    • Accept: text/event-stream (para streaming): Informa al servidor que esperas una respuesta en formato Server-Sent Events.
  3. Cuerpo de la Solicitud (payload):
    • model: Siempre "lumi-o1-mini" para esta guía.
    • messages: Una lista que define el historial de la conversación. El rol system puede usarse para dar instrucciones generales al modelo, mientras que user representa la entrada del usuario.
    • stream: True o False para habilitar/deshabilitar el streaming.
    • max_tokens, temperature: Parámetros opcionales para controlar la longitud y creatividad de la respuesta.
  4. Solicitud y Respuesta:
    • Usamos requests.post(). Para streaming, es importante usar stream=True en la llamada y luego iterar sobre response.iter_lines().
    • response.raise_for_status() es útil para detectar errores HTTP automáticamente.
  5. Procesamiento de Stream: Cada línea del stream (si decoded_line.startswith('data: ')) contiene un fragmento JSON. Debes parsearlo y extraer el contenido relevante (generalmente dentro de choices[0].delta.content). El stream finaliza con un evento especial como data: [DONE].
  6. Manejo de Errores: Un bloque try...except robusto es esencial para manejar problemas de red, errores HTTP devueltos por la API, y timeouts.

Mejores Prácticas

  • Seguridad de la API Key: ¡Nunca publiques tu API Key! Usa variables de entorno (os.getenv) o servicios de gestión de secretos.
  • Manejo de Errores Completo: Implementa una lógica sólida para todos los posibles códigos de error HTTP y errores de red.
  • Timeouts: Siempre incluye un timeout en tus solicitudes para evitar que tu aplicación se bloquee indefinidamente.
  • Reintentos (Retries): Considera implementar una estrategia de reintentos con backoff exponencial para errores transitorios (como errores 5xx o timeouts).
  • Validación de Entradas: Valida y sanitiza cualquier entrada del usuario antes de enviarla a la API.
  • Logging: Registra las solicitudes y respuestas (sin datos sensibles) para facilitar la depuración.

Próximos Pasos