API LLM para Desarrolladores: Guía de Integración Completa

Esta guía cubre todo lo que un desarrollador necesita para integrar APIs LLM en aplicaciones de producción: autenticación, streaming, uso de herramientas, embeddings, patrones RAG y gestión de costos. Todos los ejemplos usan el formato compatible con OpenAI y funcionan con APIMaster.ai.

Configuración

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_APIMASTER_KEY",
    base_url="https://apimaster.ai/v1",
)

Patrones Principales

1. Finalización de Chat Básica

def ask(prompt: str, model: str = "claude-sonnet-4-6") -> str:
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

2. Prompt de Sistema + Conversación

class Conversation:
    def __init__(self, system: str, model: str = "claude-sonnet-4-6"):
        self.model = model
        self.messages = [{"role": "system", "content": system}]
    
    def send(self, user_msg: str) -> str:
        self.messages.append({"role": "user", "content": user_msg})
        resp = client.chat.completions.create(
            model=self.model,
            messages=self.messages,
        )
        reply = resp.choices[0].message.content
        self.messages.append({"role": "assistant", "content": reply})
        return reply

bot = Conversation("Eres un desarrollador Python experto.")
print(bot.send("¿Qué es el GIL?"))
print(bot.send("¿Cómo puedo evitarlo?"))

3. Streaming

def stream(prompt: str, model: str = "gpt-5.4"):
    with client.chat.completions.stream(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    ) as s:
        for text in s.text_stream:
            yield text

for chunk in stream("Explica async/await en Python"):
    print(chunk, end="", flush=True)

4. Salida Estructurada

from pydantic import BaseModel
from typing import List

class ExtractedData(BaseModel):
    entities: List[str]
    sentiment: str
    summary: str

import json

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": f"Extrae datos y devuelve JSON que coincida con este esquema: {ExtractedData.schema()}"},
        {"role": "user", "content": "Apple reportó ingresos récord. El CEO Tim Cook lo calificó de excepcional."},
    ],
    response_format={"type": "json_object"},
)

data = ExtractedData(**json.loads(response.choices[0].message.content))
print(data.entities)    # ["Apple", "Tim Cook"]
print(data.sentiment)   # "positive"

5. Uso de Herramientas / Llamadas a Funciones

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "execute_sql",
            "description": "Ejecuta una consulta SQL de solo lectura",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "database": {"type": "string", "enum": ["users", "orders", "products"]},
                },
                "required": ["query", "database"],
            },
        },
    }
]

def handle_tool_call(tool_name: str, args: dict) -> str:
    # Tu implementación
    return json.dumps({"result": "datos simulados"})

def agent_loop(user_msg: str):
    messages = [{"role": "user", "content": user_msg}]
    
    while True:
        resp = client.chat.completions.create(
            model="gpt-5.4",
            messages=messages,
            tools=tools,
        )
        
        if resp.choices[0].finish_reason != "tool_calls":
            return resp.choices[0].message.content
        
        # Procesar llamadas a herramientas
        messages.append(resp.choices[0].message)
        for tc in resp.choices[0].message.tool_calls:
            result = handle_tool_call(tc.function.name, json.loads(tc.function.arguments))
            messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})

6. Embeddings

def embed(texts: list[str]) -> list[list[float]]:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts,
    )
    return [item.embedding for item in response.data]

# Similitud semántica
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

vecs = embed(["Python es genial", "Amo Python", "Java es verboso"])
print(cosine_similarity(vecs[0], vecs[1]))  # Alta: ~0.95
print(cosine_similarity(vecs[0], vecs[2]))  # Más baja: ~0.70

7. RAG (Generación Aumentada por Recuperación)

from typing import List

def rag_query(user_question: str, knowledge_base: List[str]) -> str:
    # Paso 1: Embedding de la pregunta
    q_embedding = embed([user_question])[0]
    doc_embeddings = embed(knowledge_base)
    
    # Paso 2: Encontrar los documentos más relevantes
    similarities = [cosine_similarity(q_embedding, d) for d in doc_embeddings]
    top_indices = sorted(range(len(similarities)), key=lambda i: similarities[i], reverse=True)[:3]
    context = "\n\n".join(knowledge_base[i] for i in top_indices)
    
    # Paso 3: Generar respuesta con contexto
    response = client.chat.completions.create(
        model="claude-sonnet-4-6",
        messages=[
            {"role": "system", "content": f"Responde usando solo este contexto:\n\n{context}"},
            {"role": "user", "content": user_question},
        ],
    )
    return response.choices[0].message.content

8. Async para Alto Rendimiento

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    api_key="YOUR_APIMASTER_KEY",
    base_url="https://apimaster.ai/v1",
)

async def process_batch(prompts: list[str]) -> list[str]:
    tasks = [
        async_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": p}],
            max_tokens=100,
        )
        for p in prompts
    ]
    responses = await asyncio.gather(*tasks)
    return [r.choices[0].message.content for r in responses]

# Procesar 50 prompts concurrentemente
results = asyncio.run(process_batch(my_prompts))

Lista de Verificación para Producción

• Claves API en variables de entorno, no en el código fuente
• Lógica de reintento con retroceso exponencial para errores 429/500
• max_tokens configurado para evitar costos descontrolados
• Streaming para respuestas visibles al usuario de más de 2 segundos
• Registro de solicitudes con conteo de tokens para seguimiento de costos
• Limitador de tasa para mantenerse dentro de los límites del proveedor

Elige el Modelo Correcto

Caso de Uso	Modelo	Nivel de Costo
Prototipado	deepseek-v4-flash o gpt-4o-mini	Muy bajo
Chatbot de producción	claude-haiku-4-5	Bajo
Asistente de código	deepseek-v4-flash o claude-sonnet-4-6	Bajo–medio
Análisis complejo	claude-sonnet-4-6	Medio
Investigación/razonamiento	claude-opus-4-8 o o3	Alto

Preguntas Frecuentes

¿Qué es una API LLM? Una API LLM es una interfaz HTTP que permite a tu código enviar prompts de texto y recibir respuestas generadas por IA. Envías un arreglo messages; la API devuelve una finalización. La mayoría usa el formato de Finalizaciones de Chat de OpenAI.

¿Cómo elijo entre proveedores de API LLM? Considera la capacidad del modelo (benchmarks), el costo por token, la latencia y la confiabilidad. Para la mayoría de los casos de uso, DeepSeek V4 Flash (codificación de bajo costo), Claude Sonnet (escritura/análisis) o GPT-4o (multimodal) cubren los caminos comunes. APIMaster te permite cambiar de proveedor con una sola línea.

¿Qué es una API compatible con OpenAI? Un endpoint que implementa el mismo formato /v1/chat/completions que OpenAI, permitiéndote usar la biblioteca openai de Python o cualquier herramienta compatible con OpenAI con modelos que no son de OpenAI.

¿Cómo manejo errores de API LLM en producción? Captura RateLimitError (reintenta con retroceso), APIConnectionError (reintenta) e InvalidRequestError (corrige el prompt). Usa timeouts y circuit breakers para la resiliencia en producción.

¿Puedo usar una sola clave API para múltiples proveedores LLM? Sí: APIMaster proporciona una única clave y endpoint para GPT, Claude, DeepSeek y Gemini. Cambia de modelo modificando el parámetro model. No se necesitan claves ni SDK específicos del proveedor.

Obtén acceso a la API LLM → · Compara modelos →