15 min de lectura

Objetivos de aprendizaje

Al final de este módulo, podrás:

  • Llamar a la API compatible con OpenAI de AI Model Hub desde Python mediante un token de portador y un modelo seleccionado desde `GET /v1/models`
  • Implementar completados de chat con streaming y sin streaming, con tiempos de espera y validación de respuestas
  • Manejar respuestas `429`, `503` y `529` con reintentos basados en `Retry-After` y límites de velocidad por modelo
  • Integrar la inferencia de forma síncrona y asíncrona a través de Kafka, con resultados almacenados en caché en In-Memory DB
  • Configurar el IONOS CLOUD MCP Server para el acceso de agentes a su cuenta, con solo lectura de forma predeterminada

Unidad 4.4: Integración de AI Model Hub

Introducción

Los usuarios de TaskBoard escriben descripciones de tareas extensas, y el equipo desea un resumen de una línea en cada tarjeta de tarea. Usted agrega un endpoint que envía la descripción a un modelo de lenguaje grande (LLM) en AI Model Hub y almacena el resumen en PostgreSQL. La inferencia se ejecuta en Alemania, y sus indicaciones no se utilizan para el entrenamiento, por lo que el contenido de las tareas permanece en la misma configuración soberana que el resto de TaskBoard.

En esta unidad, usted integra AI Model Hub en el código de la aplicación. Se autentica, selecciona un modelo, realiza llamadas a completado de chat con y sin streaming, y refuerza el cliente contra límites de tasa y sobrecarga. Luego, traslada la resumición masiva a la pipeline de Kafka de la Unidad 4.3 y almacena en caché los resultados en el clúster de In-Memory DB de la Unidad 4.1. Finalmente, conecta agentes de IA a su cuenta de IONOS CLOUD con IONOS CLOUD MCP Server. El Code Lab construye la función de resumen de extremo a extremo.

1. La API de AI Model Hub

AI Model Hub ofrece una API compatible con OpenAI. La invoca mediante la biblioteca oficial de Python openai cambiando la URL base:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["IONOS_API_TOKEN"],
    base_url="https://openai.inference.de-txl.ionos.com/v1",
    timeout=30.0,
    max_retries=3,
)
for m in client.models.list():
    print(m.id)

La URL base es https://openai.inference.de-txl.ionos.com/v1. La inferencia se ejecuta en Alemania (Berlín) y la API es accesible a nivel global.

1.1 Autenticación

La clave de API es un token de autenticación de IONOS CLOUD, enviado como Authorization: Bearer <token>. Los tokens son JSON Web Tokens (JWT) vinculados a un usuario de un contrato de IONOS Public Cloud; el uso se factura al propietario del contrato. Genera un token en el DCD bajo Management > Token Manager o mediante la API de autenticación de la Unidad 1.1:

curl -s -H "Authorization: Bearer $IONOS_API_TOKEN" \
  https://openai.inference.de-txl.ionos.com/v1/models | jq -r '.data[].id'

El tiempo de vida (TTL) de un token está comprendido entre 1 hora y 365 días en el Token Manager, y entre 60 segundos y 365 días con la API de autenticación. Su valor se muestra solo una vez. Cuando las llamadas que antes funcionaban devuelven 401, verifique primero la afirmación exp del token. Asigne a TaskBoard su propio token y guárdelo en el Secret de Kubernetes taskboard-ai.

1.2 Modelos y endpoints

Las rutas compatibles con OpenAI son POST /v1/chat/completions, POST /v1/responses, POST /v1/embeddings, POST /v1/images/generations, POST /v1/rerank y GET /v1/models. La siguiente tabla enumera los modelos de texto y sus capacidades:

Nombre del modelo Tipo Modalidad de entrada Modalidad de salida Streaming Llamada a herramientas Ventana de contexto Tamaño del modelo
Qwen3.5-9B Modelo de lenguaje Texto, imagen y video Texto ✅ ✅ 262k Pequeño
Mistral Small 24B Modelo de lenguaje Texto, imagen Texto ✅ ✅ 128k Mediano
Qwen3.8-27B Modelo de lenguaje Texto, imagen y video (beta) Texto ✅ ✅ 262k Mediano
Llama 3.3 70B Modelo de lenguaje Texto Texto ✅ ✅ 128k Mediano
GPT-OSS 120B Modelo de lenguaje Texto Texto ✅ ✅ 128k Mediano
Qwen3.5 397B A17B Modelo de lenguaje Texto e imagen Texto ✅ ✅ 262k Grande
Qwen3-Coder-Next 80B Modelo de codificación Texto Texto ✅ ✅ 256k Mediano

Como se muestra arriba, todos los modelos de texto admiten streaming y llamada a herramientas. En el código, utilice el identificador del modelo, como mistralai/Mistral-Small-24B-Instruct para Mistral Small 24B. Lea los identificadores desde /v1/models al inicio en lugar de codificar una lista de forma estática, porque el catálogo cambia.

2. Patrones de inferencia

2.1 Un resumen síncrono

MODEL = os.environ.get("SUMMARY_MODEL", "mistralai/Mistral-Small-24B-Instruct")

def summarize(description: str, model: str = MODEL) -> str:
    resp = client.chat.completions.create(
        model=model,
        messages=[
            {"role": "system", "content": "Summarize the task in one sentence of at most 20 words."},
            {"role": "user", "content": description},
        ],
        max_tokens=60,
        temperature=0.2,
    )
    choice = resp.choices[0]
    summary = (choice.message.content or "").strip()
    if choice.finish_reason != "stop" or not summary:
        raise ValueError(f"unusable summary, finish_reason={choice.finish_reason}")
    return summary[:200]

Valide cada respuesta antes de almacenarla: una respuesta truncada (finish_reason de length), una cadena vacía o un texto demasiado largo no deben llegar a la tarjeta de tarea. El campo usage informa prompt_tokens y completion_tokens, que debe registrar para el seguimiento de costos (sección 4).

2.2 Streaming

Para un panel interactivo de "explicar esta tarea", transmita los tokens al navegador a medida que llegan:

stream = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": f"Explain the next steps for: {description}"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        yield chunk.choices[0].delta.content
    if chunk.usage:
        log.info("tokens in=%s out=%s", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)

Con la transmisión en streaming, las estadísticas de uso no se incluyen de forma predeterminada. Establezca "stream_options": {"include_usage": true} para obtenerlas en el fragmento final. Utilice la transmisión en streaming cuando un usuario observe la salida y una solicitud simple cuando el código consuma el resultado.

3. Manejo de errores en producción

3.1 Límites de tasa y sobrecarga

El límite de tasa predeterminado es de 5 solicitudes por segundo por modelo, con ráfagas de hasta 10 solicitudes en una ventana de 2 segundos. Los límites se aplican por contrato y de forma independiente para cada modelo, y su contrato puede tener límites personalizados. Cada respuesta contada incluye encabezados sobre los que puede aplicar un control de flujo:

raw = client.chat.completions.with_raw_response.create(
    model=MODEL, messages=[{"role": "user", "content": "ping"}], max_tokens=1)
print(raw.headers.get("x-ratelimit-remaining-requests"),
      raw.headers.get("x-ratelimit-reset-requests"))
completion = raw.parse()
Estado Significado Reacción
429 RATE_LIMIT_EXCEEDED El límite de su contrato para este modelo se ha agotado Espere Retry-After segundos y luego reintente
503 SERVICE_OVERLOADED Demasiadas solicitudes grandes en curso: las solicitudes superiores a 4 MiB están limitadas a seis simultáneas Espere Retry-After segundos
529 user_overloaded Su tráfico contribuye a una sobrecarga de la plataforma Espere Retry-After y luego envíe a una tasa más baja
529 server_overloaded El modelo no tiene capacidad disponible, independientemente de su tráfico Espere Retry-After; considere otro modelo

La biblioteca openai respeta Retry-After automáticamente dentro de max_retries. Agregue su propio mecanismo de respaldo para 529 server_overloaded:

import openai

FALLBACK = "meta-llama/Llama-3.3-70B-Instruct"

def summarize_resilient(description: str) -> str:
    try:
        return summarize(description)
    except openai.APIStatusError as e:
        body = e.body if isinstance(e.body, dict) else {}
        code = body.get("code") or (body.get("error") or {}).get("code")
        if e.status_code == 529 and code == "server_overloaded":
            return summarize(description, model=FALLBACK)   # same prompt, other model
        raise

3.2 Errores del cliente

Otras respuestas de error incluyen un cuerpo JSON con httpStatus y una lista messages de entradas errorCode y message. Realice la bifurcación según errorCode, no según el texto del mensaje. Un 400 VALIDATION_ERROR identifica el campo incorrecto y siempre vuelve a fallar sin cambios; 404 MODEL_NOT_SUPPORTED significa que el modelo no existe o no puede servir este endpoint; 502 UPSTREAM_UNAVAILABLE justifica un nuevo intento tras una breve espera. No reintente errores 4xx distintos de 429.

4. Patrones de integración y costos

4.1 Caché de resultados en In-Memory DB

A los LLM se les cobra por millón de tokens de entrada y por millón de tokens de salida, por lo que la misma descripción nunca debe resumirse dos veces:

import hashlib

def cached_summary(description: str) -> str:
    key = "ai:summary:" + hashlib.sha256(f"{MODEL}\n{description}".encode()).hexdigest()
    hit = cache.get(key)                      # the redis client from Unit 4.1
    if hit:
        return hit
    summary = summarize_resilient(description)
    cache.set(key, summary, ex=7 * 24 * 3600)
    return summary

La clave incluye el modelo, por lo que un cambio de modelo genera nuevos resúmenes en lugar de mezclar salidas. Usted ve los costos de AI Model Hub por modelo y por unidad en la sección Cost & Usage del DCD.

4.2 Inferencia asíncrona mediante Kafka

Una importación masiva de 5.000 tareas excedería de inmediato el límite de velocidad por modelo. En su lugar, coloque el trabajo en una cola: la API produce eventos task.summarize en un tema task-summaries, creado de la misma forma que los temas de la Unidad 4.3, y un trabajador de resumen los consume a un ritmo constante.

import time

def run_summarizer():
    consumer.subscribe(["task-summaries"])
    while running:
        msg = consumer.poll(1.0)
        if msg is None or msg.error():
            continue
        event = json.loads(msg.value())
        summary = cached_summary(event["data"]["description"])
        with engine.begin() as c:
            c.execute(text("update tasks set summary = :s where id = :i"),
                      {"s": summary, "i": event["task_id"]})
        consumer.commit(message=msg, asynchronous=False)
        time.sleep(0.25)          # about 4 requests/s, below the base limit

La ruta síncrona atiende tareas individuales por las que el usuario está esperando; la ruta de Kafka atiende lotes. Ambas comparten la caché, y el manejo de reintentos y mensajes no procesables de la Unidad 4.3 captura las descripciones que el modelo sigue rechazando.

5. El IONOS CLOUD MCP Server

El IONOS CLOUD MCP Server es un binario local que implementa el Model Context Protocol (MCP). Proporciona a los asistentes y agentes de IA más de 100 herramientas en siete productos: Compute Engine, IONOS Cloud Object Storage, Cloud DNS, Certificate Manager, Billing, Activity Log y Managed Kubernetes. Es una alternativa a la escritura de llamadas a la API o al SDK cuando un agente debe inspeccionar o modificar su infraestructura.

5.1 Configuración

El cliente de IA inicia el binario y se comunica mediante JSON-RPC a través de stdio. Un .mcp.json con ámbito de proyecto para su equipo:

{
  "mcpServers": {
    "ionoscloud": {
      "command": "/usr/local/bin/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "${env:IONOS_TOKEN}"
      }
    }
  }
}

IONOS_TOKEN es obligatorio; las herramientas de Object Storage también requieren IONOS_S3_ACCESS_KEY y IONOS_S3_SECRET_KEY. Cree un token dedicado con el acceso mínimo necesario y no commitee nunca un token en el archivo.

5.2 Solo lectura por defecto, escritura mediante opt-in

El servidor es de solo lectura por defecto. IONOS_MCP_TOOL_SCOPE=write registra herramientas de creación y actualización, y destructive añade herramientas de eliminación y acciones disruptivas, como detener un servidor. Las herramientas de escritura cubren Compute Engine y Managed Kubernetes. Cada acción de creación, eliminación y disruptiva requiere una confirmación en dos pasos: una llamada de vista previa devuelve un confirmation_token, válido una sola vez durante cinco minutos, y una segunda llamada ejecuta la operación. No commitee IONOS_MCP_TOOL_SCOPE en un .mcp.json compartido, porque activa las herramientas de escritura para todas las personas que abran el repositorio.

Para una instancia compartida, ejecute el transporte Streamable HTTP:

export IONOS_TOKEN="$MCP_READONLY_TOKEN"
ionoscloud-mcp --transport http --http-addr 127.0.0.1:8080

El endpoint HTTP no cuenta con TLS ni con autenticación propia. Asócielo a 127.0.0.1, o colóquelo detrás de un proxy inverso que finalice TLS y autentique a los llamadores.

5.3 Una ruta de agente soberano

El servidor MCP llama directamente a la API de IONOS CLOUD. Sin embargo, el cliente de IA envía los prompts y la salida de las herramientas a su propio backend de modelos. Para mantener todo el recorrido de ida y vuelta dentro de IONOS CLOUD, utilice un cliente que admita tanto MCP como una URL base personalizada compatible con OpenAI, y dirija dicha URL base hacia AI Model Hub. La invocación de herramientas es un requisito previo para MCP, y los modelos de la sección 1.2 la admiten.

Tarjeta rápida de referencia de la API

Endpoints clave de AI Model Hub para esta unidad:

Método Endpoint Descripción
GET /v1/models Lista los identificadores de modelos disponibles
POST /v1/chat/completions Generación de texto, con stream: true para transmisión en streaming
POST /v1/responses API de respuestas con elementos de salida tipados
POST /v1/embeddings Vectores de incrustación para búsqueda semántica
POST /v1/rerank Reclasifica documentos para una consulta

URL base: https://openai.inference.de-txl.ionos.com/v1 Autenticación: Authorization: Bearer <token>

Laboratorio de código

Objetivo: Llamar a AI Model Hub desde TaskBoard para generar resúmenes de tareas, manejar errores, almacenar los resultados en caché en In-Memory DB y guardarlos en PostgreSQL.

Requisitos previos:

  • Un token de IONOS CLOUD en IONOS_API_TOKEN
  • Las conexiones de PostgreSQL y de caché de la Unidad 4.1 (engine, cache)
  • Python 3.12 con openai, sqlalchemy y redis

Paso 1: Listar los modelos

curl -s -H "Authorization: Bearer $IONOS_API_TOKEN" \
  https://openai.inference.de-txl.ionos.com/v1/models | jq -r '.data[].id' | head -5

Salida esperada:

<model identifiers, for example mistralai/Mistral-Small-24B-Instruct>

Paso 2: Agregar la columna de resumen

with engine.begin() as c:
    c.execute(text("alter table tasks add column if not exists summary text"))
print("ok")

Salida esperada:

ok

Paso 3: Resuma una descripción

d = "Migrate the attachment upload from API proxying to presigned PUT URLs, add CORS, and remove the old endpoint after one release."
print(summarize(d))

Salida esperada:

<one sentence of at most 20 words>

Paso 4: Lea las cabeceras de límite de velocidad

Ejecute el fragmento with_raw_response de la sección 3.1. Salida esperada:

4 200ms

Paso 5: Caché y almacenamiento

import time
for i in range(2):
    t = time.perf_counter(); s = cached_summary(d)
    print(i, f"{time.perf_counter() - t:.2f}s")
with engine.begin() as c:
    c.execute(text("update tasks set summary = :s where id = 1"), {"s": s})

Salida esperada:

0 <about a second>s
1 0.00s

Paso 6: Forzar un error de validación

try:
    client.chat.completions.create(model=MODEL, messages=[])
except openai.BadRequestError as e:
    print(e.status_code, e.body)

Salida esperada:

400 {... 'errorCode': 'VALIDATION_ERROR', ...}

Lista de verificación de validación:

  • [ ] /v1/models devuelve identificadores con su token de portador
  • [ ] El resumen supera las comprobaciones de finish_reason y de longitud
  • [ ] La segunda llamada se sirve desde la caché sin una solicitud al modelo
  • [ ] El resumen se almacena en la columna tasks.summary

Limpieza:

for k in cache.scan_iter("ai:summary:*"):
    cache.delete(k)

Errores comunes

Errores de desarrollo a evitar con el tema de esta unidad:

  1. Error 401 repentino tras semanas de éxito

    • Problema: Cada llamada devuelve 401 aunque el código no haya cambiado.
    • Por qué ocurre: El TTL del token ha caducado.
    • Solución: Verifique la afirmación exp del JWT, genere un token nuevo, actualice el Secret y emita una alerta antes de la fecha de caducidad.
  2. Tareas por lotes que superan el límite de tasa

    • Problema: Una tarea de importación dispara cientos de solicitudes paralelas y la mayoría fallan con 429.
    • Por qué ocurre: Cada modelo permite 5 solicitudes por segundo por contrato, con ráfagas breves.
    • Solución: Encole el trabajo a través de Kafka y regule el consumidor (sección 4.2); lea X-RateLimit-Remaining-Requests.
  3. Almacenar salida no validada

    • Problema: Las tarjetas de tareas muestran frases incompletas o resúmenes vacíos.
    • Por qué ocurre: La respuesta alcanzó max_tokens (finish_reason es length), o el modelo no devolvió contenido.
    • Solución: Verifique finish_reason y la longitud antes de almacenar, y conserve el resumen anterior en caso de fallo (sección 2.1).

Resumen

Ahora puede agregar funciones de IA a TaskBoard con AI Model Hub. La biblioteca openai funciona contra la URL base compatible con OpenAI con un token de portador de IONOS CLOUD. Valida las respuestas, transmite en tiempo real donde los usuarios observan y maneja 429, 503 y 529 con Retry-After. Las solicitudes individuales se ejecutan de forma síncrona, los lotes fluyen a través de Kafka a un ritmo inferior al límite de velocidad y la caché evita pagar dos veces por los mismos tokens. Para flujos de trabajo de agentes, el IONOS CLOUD MCP Server expone su cuenta como herramientas de solo lectura, con escrituras solo mediante una opción de inclusión explícita.

Puntos clave:

  • URL base https://openai.inference.de-txl.ionos.com/v1, token de portador, identificadores de modelo desde /v1/models
  • Límites predeterminados: 5 solicitudes por segundo por modelo, ráfagas de hasta 10, según el contrato
  • Espere el tiempo de Retry-After en 429, 503 y 529; bifurque según códigos de error, no según mensajes
  • Almacene en caché los resultados por modelo y entrada; encolé el trabajo masivo a través de Kafka
  • El MCP Server es de solo lectura de forma predeterminada; las escrituras requieren IONOS_MCP_TOOL_SCOPE, y las acciones de creación, eliminación y disruptivas requieren una confirmación en dos pasos

Terminología importante:

  • Identificador de modelo: La cadena que pasa como model, como mistralai/Mistral-Small-24B-Instruct
  • Límite de ráfaga: Las solicitudes adicionales permitidas dentro de una ventana de 2 segundos por encima de la velocidad base
  • finish_reason: El campo que le indica por qué se detuvo la generación, por ejemplo stop o length
  • MCP: Model Context Protocol, el protocolo JSON-RPC a través del cual los clientes de IA llaman a herramientas
  • Alcance de la herramienta: El nivel de IONOS_MCP_TOOL_SCOPE, read, write o destructive, que determina qué herramientas registra el servidor

Próximos pasos

Continuar aprendiendo: Unidad 4.5: Verificación de conocimientos - Integración de servicios

Temas relacionados: