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,sqlalchemyyredis
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/modelsdevuelve identificadores con su token de portador - [ ] El resumen supera las comprobaciones de
finish_reasony 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:
-
Error 401 repentino tras semanas de éxito
- Problema: Cada llamada devuelve
401aunque el código no haya cambiado. - Por qué ocurre: El TTL del token ha caducado.
- Solución: Verifique la afirmación
expdel JWT, genere un token nuevo, actualice el Secret y emita una alerta antes de la fecha de caducidad.
- Problema: Cada llamada devuelve
-
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.
- Problema: Una tarea de importación dispara cientos de solicitudes paralelas y la mayoría fallan con
-
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_reasoneslength), o el modelo no devolvió contenido. - Solución: Verifique
finish_reasony 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-Afteren429,503y529; 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, comomistralai/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
stopolength - 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,writeodestructive, 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: