Image for post Integración de Anthropic Claude con FastAPI: Construyendo una API de IA Conversacional

Integración de Anthropic Claude con FastAPI: Construyendo una API de IA Conversacional

Escrito por Sergio Márquez

En el vertiginoso mundo de la Inteligencia Artificial, los Modelos de Lenguaje Grandes (LLMs) se han convertido en herramientas indispensables para crear aplicaciones innovadoras. Si bien OpenAI ha liderado gran parte de la conversación, explorar alternativas como Anthropic Claude no solo diversifica tus opciones, sino que también te permite aprovechar diferentes fortalezas y filosofías de modelos. En este artículo, te guiaré paso a paso para integrar la potente API de Anthropic Claude en una aplicación web robusta y escalable utilizando FastAPI, el framework web asíncrono de Python.

Contexto del Problema: La Necesidad de APIs de LLMs Flexibles

Como desarrolladores, a menudo necesitamos dotar a nuestras aplicaciones de capacidades conversacionales, de generación de texto o de análisis de lenguaje natural. Integrar un LLM directamente en el backend de nuestra aplicación a través de una API es la forma más común y eficiente de hacerlo. Sin embargo, la elección del LLM y la forma de integrarlo pueden impactar significativamente el rendimiento, el costo y la mantenibilidad de nuestra solución.

El desafío radica en construir una API que sea:

  • Eficiente: Capaz de manejar múltiples solicitudes concurrentes sin bloquearse.
  • Robusta: Con manejo de errores y validación de datos.
  • Segura: Protegiendo las claves de API y otros datos sensibles.
  • Escalable: Lista para crecer con la demanda de usuarios.

FastAPI, con su rendimiento asíncrono y su excelente soporte para validación de datos con Pydantic, es la elección perfecta para este tipo de tarea. Al combinarlo con Anthropic Claude, abrimos la puerta a una nueva gama de posibilidades para nuestras aplicaciones de IA.

Conceptos Clave

Antes de sumergirnos en el código, repasemos los pilares de nuestra implementación:

Anthropic Claude API

Anthropic es una empresa de investigación y seguridad de IA que ha desarrollado la familia de modelos Claude. Estos modelos son conocidos por su capacidad de razonamiento, su seguridad y su enfoque en la "IA constitucional". La API de Claude, similar a otras APIs de LLMs, permite interactuar con sus modelos enviando mensajes y recibiendo respuestas. Utilizaremos la API de "Messages", que es la forma recomendada de interactuar con los modelos más recientes de Claude. [29, 30]

La estructura básica de una interacción con la API de Messages implica enviar una lista de mensajes (historial de conversación) y el modelo responde con el siguiente mensaje en la secuencia. Esto facilita la gestión del contexto conversacional. [30]

FastAPI

FastAPI es un framework web moderno y de alto rendimiento para construir APIs con Python 3.7+. [6, 37] Sus características clave incluyen:

  • Velocidad: Basado en Starlette para la parte web y Pydantic para la validación de datos, es uno de los frameworks más rápidos disponibles. [6]
  • Asíncrono: Soporte nativo para async y await, lo que permite manejar miles de solicitudes concurrentes. [6, 20, 28]
  • Validación de Datos: Integración profunda con Pydantic para definir modelos de datos claros y obtener validación automática. [13, 19, 20]
  • Documentación Automática: Genera automáticamente documentación interactiva (Swagger UI y ReDoc) para tu API.

Pydantic para Validación de Datos

Pydantic es una biblioteca de validación de datos que utiliza type hints de Python. FastAPI la integra de forma nativa para validar automáticamente los datos de entrada y salida de tus endpoints, lo que reduce drásticamente los errores y mejora la claridad del código. [13, 19, 20]

Programación Asíncrona (async/await)

Python, a través de asyncio, permite escribir código concurrente que no bloquea el hilo principal. Esto es crucial para APIs que interactúan con servicios externos (como la API de Claude), ya que permite que el servidor maneje otras solicitudes mientras espera la respuesta del LLM. [6, 28, 35]

Implementación Paso a Paso

Paso 1: Configuración del Entorno y Dependencias

Primero, crea un nuevo directorio para tu proyecto y configura un entorno virtual. Recomiendo usar Poetry para una gestión de dependencias más robusta, pero venv y pip también funcionan.


mkdir claude-fastapi-api
cd claude-fastapi-api

# Usando Poetry (recomendado)
poetry init --no-interaction
poetry add fastapi uvicorn python-dotenv anthropic

# O usando venv y pip
python -m venv venv
source venv/bin/activate # En Windows: venv\Scripts\activate
pip install fastapi uvicorn python-dotenv anthropic

Necesitarás una clave de API de Anthropic. Puedes obtenerla registrándote en su plataforma. [3, 11] Una vez que la tengas, guárdala de forma segura en un archivo .env en la raíz de tu proyecto:


# .env
ANTHROPIC_API_KEY="tu_clave_secreta_de_anthropic"

¡Importante! Nunca expongas tus claves de API directamente en el código fuente ni las subas a repositorios públicos como GitHub. [1, 2, 3, 10, 11] Utiliza variables de entorno o soluciones de gestión de secretos para manejar tu clave de forma segura. [1, 3, 10, 25]

Paso 2: Estructura Básica de FastAPI

Crea un archivo main.py. Aquí definiremos nuestra aplicación FastAPI.


# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from dotenv import load_dotenv
import os
from anthropic import Anthropic, APIStatusError, APIConnectionError

# Cargar variables de entorno
load_dotenv()

# Inicializar la aplicación FastAPI
app = FastAPI(
    title="API Conversacional con Anthropic Claude",
    description="Una API sencilla para interactuar con el modelo Claude de Anthropic."
)

# Obtener la clave de API de Anthropic de las variables de entorno
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")

if not ANTHROPIC_API_KEY:
    raise ValueError("La variable de entorno ANTHROPIC_API_KEY no está configurada.")

# Inicializar el cliente de Anthropic
# Se recomienda inicializar el cliente una vez y reutilizarlo.
anthropic_client = Anthropic(api_key=ANTHROPIC_API_KEY)

# Definir modelos Pydantic para la solicitud y la respuesta
class MessageRequest(BaseModel):
    message: str
    model: str = "claude-3-opus-20240229" # Modelo por defecto, puedes cambiarlo

class MessageResponse(BaseModel):
    response: str
    model_used: str

@app.get("/")
async def read_root():
    return {"message": "Bienvenido a la API de Claude. Usa /chat para interactuar."}

@app.post("/chat", response_model=MessageResponse)
async def chat_with_claude(request: MessageRequest):
    """
    Endpoint para enviar un mensaje a Claude y obtener una respuesta.
    """
    try:
        # Llamar a la API de Anthropic
        response = await anthropic_client.messages.create(
            model=request.model,
            max_tokens=1024, # Límite de tokens para la respuesta
            messages=[
                {"role": "user", "content": request.message}
            ]
        )
        
        # Extraer el contenido de la respuesta
        ai_response_content = ""
        for content_block in response.content:
            if content_block.type == "text":
                ai_response_content += content_block.text

        return MessageResponse(response=ai_response_content, model_used=response.model)

    except APIStatusError as e:
        # Errores de la API de Anthropic (ej. clave inválida, límite de tokens)
        raise HTTPException(status_code=e.status_code, detail=f"Error de la API de Anthropic: {e.response}")
    except APIConnectionError as e:
        # Errores de conexión de red
        raise HTTPException(status_code=503, detail=f"Error de conexión con la API de Anthropic: {e}")
    except Exception as e:
        # Otros errores inesperados
        raise HTTPException(status_code=500, detail=f"Error interno del servidor: {e}")

Paso 3: Ejecutar la Aplicación

Para ejecutar tu API, usa Uvicorn:


# Si usas Poetry
poetry run uvicorn main:app --reload

# Si usas venv/pip
uvicorn main:app --reload

Abre tu navegador y ve a http://127.0.0.1:8000/docs. Verás la documentación interactiva de Swagger UI, donde puedes probar tu endpoint /chat.

Mini Proyecto / Aplicación Sencilla: Un Chatbot Básico

El código que acabamos de escribir ya es un mini-proyecto funcional: un chatbot básico que toma un mensaje de usuario y devuelve una respuesta de Claude. Puedes interactuar con él directamente desde la interfaz de Swagger UI.

Cómo probarlo:

  1. Ve a http://127.0.0.1:8000/docs.
  2. Expande el endpoint /chat (POST).
  3. Haz clic en "Try it out".
  4. En el campo "Request body", introduce un JSON como este: 
    
{
  "message": "¿Cuál es la capital de Francia?",
  "model": "claude-3-haiku-20240307"
}
  5. Haz clic en "Execute".

Deberías recibir una respuesta de Claude con la capital de Francia. ¡Felicidades, has construido tu primera API conversacional con Anthropic Claude y FastAPI!

Errores Comunes y Depuración

Al trabajar con APIs externas y frameworks web, es común encontrarse con algunos problemas. Aquí te presento los más frecuentes y cómo abordarlos:

  1. ValueError: ANTHROPIC_API_KEY no está configurada.

    Causa: No has creado el archivo .env, la clave no está correctamente definida, o load_dotenv() no se ejecutó o no encontró el archivo.

    Solución: Asegúrate de que tienes un archivo .env en la raíz de tu proyecto con ANTHROPIC_API_KEY="tu_clave" y que load_dotenv() está al principio de tu main.py.

  2. HTTPException con status_code 401/403 (Unauthorized/Forbidden)

    Causa: Tu clave de API de Anthropic es inválida o no tiene los permisos necesarios. [2]

    Solución: Verifica tu clave de API en el panel de Anthropic. Asegúrate de que no haya espacios extra o caracteres incorrectos. Podría ser que la clave haya expirado o haya sido revocada. [2]

  3. HTTPException con status_code 400 (Bad Request)

    Causa: El formato de tu solicitud a la API de Claude es incorrecto, o el modelo especificado no existe o no está disponible para tu cuenta. [30]

    Solución: Revisa la documentación de la API de Anthropic para el endpoint messages. Asegúrate de que el model que estás usando sea válido y que el formato de los messages sea correcto. Pydantic también te dará errores claros si tu MessageRequest no cumple con el esquema. [13, 19]

  4. HTTPException con status_code 429 (Too Many Requests)

    Causa: Has excedido el límite de solicitudes (rate limit) de la API de Anthropic. [10]

    Solución: Espera un tiempo antes de hacer más solicitudes. En una aplicación de producción, implementarías una lógica de reintentos con retroceso exponencial (exponential backoff) o una cola de mensajes. [10]

  5. HTTPException con status_code 503 (Service Unavailable)

    Causa: Problemas de conexión de red entre tu servidor y la API de Anthropic. [24]

    Solución: Verifica tu conexión a internet. Si estás en un entorno de producción, podría ser un problema temporal de la red o de los servidores de Anthropic. El manejo de excepciones APIConnectionError ya está implementado. [24]

  6. Errores de Pydantic en la Consola

    Causa: Tu JSON de entrada no coincide con el modelo MessageRequest definido.

    Solución: FastAPI y Pydantic te darán mensajes de error muy descriptivos. Asegúrate de que el JSON que envías tenga la clave "message" y opcionalmente "model", y que sus tipos de datos sean correctos (cadenas de texto). [13, 19]

Aprendizaje Futuro

Este mini-proyecto es solo el punto de partida. Aquí hay algunas ideas para expandir y mejorar tu API:

  • Añadir Memoria Conversacional: Actualmente, cada solicitud es independiente. Para un chatbot real, necesitarás almacenar el historial de la conversación. Esto se puede lograr pasando la lista completa de mensajes (usuario y asistente) en cada solicitud a Claude, o implementando una base de datos (como Redis o PostgreSQL) para persistir el historial. [30]

    
# Ejemplo conceptual de cómo se vería la llamada con historial
# (requeriría lógica para almacenar y recuperar 'conversation_history')
# messages = conversation_history + [{"role": "user", "content": request.message}]
# response = await anthropic_client.messages.create(model=request.model, messages=messages, ...)

  • Streaming de Respuestas: Para una mejor experiencia de usuario, especialmente con respuestas largas, puedes configurar la API de Claude para que envíe la respuesta en fragmentos (streaming) y luego transmitir esos fragmentos a tu cliente. FastAPI soporta streaming de respuestas. [5, 6, 7, 8, 15]

    
# Ejemplo conceptual de streaming con Anthropic y FastAPI
# from fastapi.responses import StreamingResponse
# async def generate_stream():
#     async with anthropic_client.messages.stream(model=request.model, messages=[...]) as stream:
#         async for text in stream.text_stream:
#             yield text.encode("utf-8")
# return StreamingResponse(generate_stream(), media_type="text/event-stream")

  • Autenticación y Rate Limiting: Para proteger tu API, implementa mecanismos de autenticación (ej. OAuth2 con JWT) y limita el número de solicitudes que un usuario puede hacer en un período de tiempo determinado. [18, 39, 44, 48, 49]

  • Explorar Otros Modelos y Funcionalidades de Claude: Anthropic ofrece diferentes modelos (Haiku, Sonnet, Opus) con distintas capacidades y costos. [4, 9, 14, 16, 17] También puedes explorar funcionalidades avanzadas como el uso de herramientas (tool use) para permitir que Claude interactúe con funciones externas. [21, 29, 36, 43, 47]

  • Despliegue en Producción: Una vez que tu API esté lista, considera desplegarla usando Docker y servicios en la nube como Railway, Render, AWS, Azure o Google Cloud. [27] Esto implica crear un Dockerfile y configurar tu entorno de producción. [19]

La integración de LLMs en tus aplicaciones es una habilidad fundamental en el desarrollo de IA moderno. Con FastAPI y Anthropic Claude, tienes una combinación poderosa para construir soluciones conversacionales inteligentes y eficientes. ¡Experimenta, construye y sigue aprendiendo!

Volver al blog