Cómo los desarrolladores crean y alojan bots de servidor basados en API en Poe para implementar modelos personalizados

Los Poe Server Bots permiten a los desarrolladores conectar infraestructura computacional externa, modelos de aprendizaje automático personalizados y lógica propietaria directamente a la plataforma Poe de Quora mediante un protocolo HTTP estandarizado basado en Server-Sent Events (SSE). A diferencia de los bots de prompts estándar que dependen de los modelos comerciales alojados de Poe con prompts de sistema personalizados, los bots de servidor brindan a los equipos de ingeniería control total sobre los motores de inferencia de backend, pesos privados, pipelines de generación aumentada por recuperación (RAG) e integraciones de API externas. Al envolver modelos personalizados en la ligera biblioteca de Python fastapi_poe y desplegar el servicio en un endpoint de acceso público, los desarrolladores pueden distribuir instantáneamente herramientas de IA propietarias a la base global de usuarios de Poe a través de las aplicaciones web, iOS, Android y de escritorio.

Arquitectura y el Protocolo de Poe Server Bot

La comunicación entre Poe y su backend personalizado sigue un modelo cliente-servidor asíncrono sobre HTTPS. Cuando un usuario envía un mensaje a su bot de servidor en Poe, la infraestructura de Poe reenvía el contexto del mensaje como una solicitud HTTP POST a su endpoint de servidor designado. Su servidor procesa el payload entrante y transmite la respuesta generada de vuelta a Poe utilizando Server-Sent Events (SSE). Esta arquitectura asegura baja latencia y proporciona transmisión de tokens en tiempo real al usuario final.

La especificación del protocolo estandariza varios tipos de eventos y solicitudes:

• QueryRequest: Contiene el contexto conversacional completo, incluidos los mensajes pasados en el hilo (query), el identificador único de la conversación (conversation_id), el identificador del usuario (user_id), metadatos del mensaje y capacidades del cliente.
• PartialResponse: El bloque de transmisión atómico emitido por su servidor. Cada respuesta parcial proporciona texto incremental, payloads de datos o actualizaciones de estado al cliente.
• SettingsRequest / SettingsResponse: Permite a su servidor negociar configuraciones a nivel de bot con Poe, como mensajes de introducción, permisos de archivos adjuntos, respuestas sugeridas y declaraciones de dependencias para consultas bot a bot.
• ReportFeedbackRequest y ReportErrorRequest: Proporcionan callbacks de telemetría y retroalimentación de Poe a su servidor cuando los usuarios califican mensajes o cuando ocurren errores de transmisión en el lado del cliente.

Para autenticar las solicitudes y proteger su backend de tráfico no autorizado, Poe emite una Clave de Acceso (Access Key). Su servidor verifica esta clave contra el encabezado Authorization: Bearer <access_key> enviado con cada solicitud entrante.

Configuración del Entorno de Desarrollo

La biblioteca oficial fastapi_poe proporciona la ruta más rápida para implementar un bot de servidor compatible. Abstrae el análisis de HTTP, la serialización de eventos y la autenticación en una interfaz asíncrona extensible.

Comience instalando fastapi-poe junto con un servidor ASGI como Uvicorn:

pip install fastapi-poe uvicorn

Un bot de servidor mínimo hereda de PoeBot e implementa el generador get_response:

import fastapi_poe as fp
from typing import AsyncIterable

class EchoBot(fp.PoeBot):
    async def get_response(
        self, request: fp.QueryRequest
    ) -> AsyncIterable[fp.PartialResponse]:
        last_message = request.query[-1].content
        yield fp.PartialResponse(text=f"Received: {last_message}")

    async def get_settings(
        self, setting: fp.SettingsRequest
    ) -> fp.SettingsResponse:
        return fp.SettingsResponse(
            introduction_message="Welcome! This bot is running on a custom backend.",
            allow_attachments=False
        )

bot = EchoBot()
app = fp.make_app(bot, access_key="YOUR_SECRET_ACCESS_KEY")

if __name__ == "__main__":
    fp.run(bot, access_key="YOUR_SECRET_ACCESS_KEY", port=8080)

Durante la creación de prototipos locales, puede exponer su puerto local (por ejemplo, 8080) al internet público utilizando una herramienta de túnel como ngrok o Cloudflare Tunnels:

ngrok http 8080

Esto genera una URL HTTPS pública temporal (por ejemplo, https://abcdef123.ngrok-free.app) que puede ingresar en la interfaz de registro de bots de Poe para realizar pruebas de inmediato.

Despliegue de Modelos Personalizados y Pipelines de Inferencia

Conectar un bot de servidor a un modelo personalizado implica vincular los mensajes entrantes de QueryRequest a un motor de inferencia y transmitir los tokens generados como objetos PartialResponse.

Integración con un Backend de Inferencia vLLM o Hugging Face

Al ejecutar modelos de pesos abiertos (como Llama 3, Mistral o Qwen) en hardware de GPU dedicado, servirlos a través de un motor optimizado como vLLM o Hugging Face Text Generation Inference (TGI) ofrece un alto rendimiento y agrupamiento continuo (continuous batching).

El siguiente ejemplo ilustra un bot de servidor de Poe reenviando solicitudes a un servidor de inferencia vLLM compatible con OpenAI:

import os
import fastapi_poe as fp
from openai import AsyncOpenAI
from typing import AsyncIterable

# Connect to local or remote vLLM endpoint
client = AsyncOpenAI(
    base_url=os.environ.get("VLLM_BASE_URL", "http://localhost:8000/v1"),
    api_key=os.environ.get("VLLM_API_KEY", "EMPTY"),
)

class CustomModelBot(fp.PoeBot):
    async def get_response(
        self, request: fp.QueryRequest
    ) -> AsyncIterable[fp.PartialResponse]:
        # Convert Poe conversation history to chat messages
        messages = []
        for message in request.query:
            role = "user" if message.role == "user" else "assistant"
            messages.append({"role": role, "content": message.content})

        try:
            stream = await client.chat.completions.create(
                model="meta-llama/Meta-Llama-3-8B-Instruct",
                messages=messages,
                stream=True,
                temperature=0.7,
                max_tokens=1024,
            )

            async for chunk in stream:
                token = chunk.choices[0].delta.content
                if token:
                    yield fp.PartialResponse(text=token)

        except Exception as e:
            yield fp.ErrorResponse(
                text=f"An error occurred during inference: {str(e)}",
                allow_retry=True
            )

    async def get_settings(
        self, setting: fp.SettingsRequest
    ) -> fp.SettingsResponse:
        return fp.SettingsResponse(
            introduction_message="Powered by a custom open-source model running on dedicated infrastructure.",
            enable_image_comprehension=False,
            allow_attachments=False
        )

bot = CustomModelBot()
app = fp.make_app(bot, access_key=os.environ.get("POE_ACCESS_KEY"))

Manejo de Contexto Multiturno y Archivos Adjuntos

Poe envía el historial completo del diálogo en el arreglo request.query, ordenado cronológicamente. Si su modelo personalizado tiene una ventana de contexto limitada, la lógica de su bot de servidor debe recortar o resumir los turnos anteriores antes de la tokenización.

Cuando su bot habilita allow_attachments=True en get_settings, las subidas de archivos (imágenes, PDFs, documentos de texto) aparecen en request.query[-1].attachments. Cada objeto adjunto contiene una URL de descarga y un tipo MIME, lo que permite que su backend descargue el activo, realice OCR, ejecute codificación de visión o incorpore el documento en un almacén vectorial antes de generar una respuesta.

Opciones de Alojamiento para Bots de Servidor

Dado que Poe requiere un endpoint HTTPS ininterrumpido capaz de transmitir respuestas SSE, seleccionar la plataforma de alojamiento adecuada depende del tamaño de su modelo, sus requerimientos de cálculo y su presupuesto.

Despliegue de GPU Serverless con Modal

Modal proporciona soporte de primera clase para los bots de servidor de Poe, permitiendo a los desarrolladores definir la infraestructura de GPU como código y pagar solo por el tiempo real de ejecución. Modal escala automáticamente las instancias de contenedores desde cero y proporciona una URL HTTPS.

Un script de despliegue en Modal listo para producción:

import os
import modal
import fastapi_poe as fp

app = modal.App("poe-custom-model-bot")

# Define container environment with dependencies
image = (
    modal.Image.debian_slim()
    .pip_install("fastapi-poe", "openai")
)

@app.function(
    image=image,
    secrets=[modal.Secret.from_name("poe-custom-model-secrets")],
    keep_warm=1,  # Keeps one instance ready to prevent cold starts
)
@modal.asgi_app()
def fastapi_app():
    from bot_implementation import CustomModelBot
    bot = CustomModelBot()
    return fp.make_app(bot, access_key=os.environ["POE_ACCESS_KEY"])

Desplegar este servicio con modal deploy app.py genera una URL permanente como: https://<organization>--poe-custom-model-bot-fastapi-app.modal.run.

Alojamiento en Contenedores en Proveedores Cloud (AWS, GCP, Render, Fly.io)

Para equipos que ejecutan clústeres de inferencia propietarios o aprovechan plataformas de contenedores gestionadas:

1. Dockerizar la Aplicación: Cree un Dockerfile ligero ejecutando uvicorn app:app --host 0.0.0.0 --port 8080 --workers 4.
2. Proxy Inverso y SSL: Despliegue detrás de un controlador de ingress (como AWS ALB, Cloudflare o Nginx) que soporte conexiones HTTP de larga duración y transmisión de respuestas fragmentadas (chunked). Asegúrese de que los tiempos de espera del proxy (por ej., proxy_read_timeout) estén configurados en al menos 300 segundos para evitar desconexiones a mitad de la transmisión.
3. Secretos de Entorno: Inyecte POE_ACCESS_KEY y las credenciales de inferencia de forma segura a través de variables de entorno del contenedor.

Registro y Configuración del Bot en Poe

Una vez que su servidor esté desplegado y accesible a través de HTTPS público, complete el registro en la plataforma de Poe:

1. Vaya a poe.com/create_bot?server=1.
2. Handle del Bot: Elija un identificador alfanumérico único (por ej., @MyCustomModel). Este forma el enlace público para su bot.
3. Tipo de Bot: Asegúrese de que "Server bot" esté seleccionado.
4. URL del Servidor: Ingrese su endpoint público completo (por ej., https://your-domain.com/ o su URL de despliegue de Modal).
5. Clave de Acceso (Access Key): Pegue el token secreto configurado en la llamada fp.make_app() de su servidor. Poe validará este token con cada solicitud de prueba.
6. Detalles del Perfil: Configure su nombre para mostrar, descripción, avatar e instrucciones del sistema visibles para los usuarios.
7. Visibilidad: Seleccione si el bot debe permanecer privado (accesible solo para usted o los miembros designados del equipo) o público (buscable en el directorio Explore de Poe).

Haga clic en Create Bot. Poe verifica inmediatamente la conectividad emitiendo un SettingsRequest a su endpoint. Si el servidor devuelve una respuesta válida, el bot se activa.

Monetización y Economía de Puntos de Cálculo

Poe ofrece monetización nativa para creadores de bots de servidor, permitiendo a los desarrolladores ganar ingresos a medida que los usuarios interactúan con sus herramientas.

Precio por Mensaje y la API de Monetización de Bots

Los creadores pueden establecer un costo fijo de puntos de cálculo por mensaje en la configuración del bot, o utilizar la API de Monetización de Bots para facturación dinámica basada en el uso:

• Reparto de Ingresos por Suscripción: Cuando nuevos usuarios se suscriben a Poe después de interactuar con su bot, usted recibe un pago de afiliado.
• Consumo de Puntos de Cálculo: Cuando los suscriptores existentes de Poe o los usuarios gratuitos gastan puntos de cálculo en su bot, usted gana ingresos proporcionales a los puntos consumidos.
• Precios Variables: Si su modelo realiza tareas con costos computacionales impredecibles (por ej., renderizado de imágenes en alta resolución o análisis de documentos de contexto largo), puede configurar precios variables utilizando los endpoints authorize_cost y capture_cost. A los usuarios se les presenta una rate_card o cost_label clara antes de que se ejecuten las operaciones de alto costo.

# Setting dynamic rate cards in SettingsResponse
async def get_settings(self, setting: fp.SettingsRequest) -> fp.SettingsResponse:
    return fp.SettingsResponse(
        introduction_message="Professional analysis bot with dynamic compute points.",
        cost_label="50-200 pts",
        rate_card="* Base Query: 50 points\n* Extended Analysis: 150-200 points"
    )

Mejores Prácticas de Producción

Desplegar un bot de servidor confiable requiere abordar la volatilidad de la red, los presupuestos de latencia y la telemetría operativa:

• Implementar Streaming Inmediato: Los usuarios perciben baja latencia cuando el primer token aparece rápidamente. Evite almacenar en búfer generaciones enteras de modelos en la memoria antes de emitir resultados. Comience a emitir tokens tan pronto como llegue el primer bloque desde su backend de inferencia.
• Recuperación Elegante de Errores: Envuelva las llamadas al modelo en manejadores de excepciones estructurados. Si un worker de GPU ascendente falla, devuelva una fp.ErrorResponse con una explicación clara y establezca allow_retry=True para que el usuario pueda volver a activar la consulta sin recargar la aplicación.
• Seguimientos Sugeridos (Follow-Ups): Mejore el engagement agregando respuestas sugeridas a través de fp.MetaResponse(suggested_replies=["Explain further", "Provide code sample"]) al concluir una respuesta.
• Monitorear Telemetría: Implemente el método on_feedback en su clase PoeBot para registrar calificaciones positivas (pulgar arriba) y negativas (pulgar abajo) directamente en su plataforma de observabilidad (por ej., Datadog, Prometheus o Grafana).