Como os desenvolvedores criam e hospedam bots de servidor baseados em API no Poe para implantar modelos personalizados

Os Poe Server Bots permitem que os desenvolvedores conectem infraestrutura de computação externa, modelos de aprendizado de máquina personalizados e lógica proprietária diretamente à plataforma Poe do Quora usando um protocolo HTTP padronizado baseado em Server-Sent Events (SSE). Ao contrário dos bots de prompt padrão, que dependem dos modelos comerciais hospedados do Poe com prompts de sistema personalizados, os bots de servidor dão às equipes de engenharia controle total sobre mecanismos de inferência de back-end, pesos privados, pipelines de geração aumentada de recuperação (RAG) e integrações de API externas. Ao empacotar modelos personalizados na biblioteca Python leve fastapi_poe e implantar o serviço em um endpoint publicamente acessível, os desenvolvedores podem distribuir instantaneamente ferramentas de IA proprietárias para a base de usuários global do Poe em aplicativos web, iOS, Android e desktop.

Arquitetura e o Protocolo Poe Server Bot

A comunicação entre o Poe e seu back-end personalizado segue um modelo cliente-servidor assíncrono via HTTPS. Quando um usuário envia uma mensagem para o seu bot de servidor no Poe, a infraestrutura do Poe encaminha o contexto da mensagem como uma solicitação POST HTTP para o endpoint de servidor designado. O seu servidor processa o payload de entrada e transmite a resposta gerada de volta para o Poe usando Server-Sent Events (SSE). Essa arquitetura garante baixa latência e fornece streaming de tokens em tempo real para o usuário final.

A especificação do protocolo padroniza vários tipos de eventos e solicitações:

• QueryRequest: Contém todo o contexto conversacional, incluindo mensagens anteriores no thread (query), o identificador único da conversa (conversation_id), o identificador do usuário (user_id), metadados da mensagem e recursos do cliente.
• PartialResponse: O bloco de streaming atômico emitido pelo seu servidor. Cada resposta parcial produz texto incremental, payloads de dados ou atualizações de estado para o cliente.
• SettingsRequest / SettingsResponse: Permite que o seu servidor negocie configurações em nível de bot com o Poe, como mensagens de introdução, permissões de anexos de arquivo, sugestões de respostas e declarações de dependências para consultas bot a bot.
• ReportFeedbackRequest e ReportErrorRequest: Fornecem callbacks de telemetria e feedback do Poe para o seu servidor quando os usuários classificam mensagens ou quando ocorrem erros de transmissão no lado do cliente.

Para autenticar solicitações e proteger seu back-end contra tráfego não autorizado, o Poe emite uma Chave de Acesso (Access Key). O seu servidor verifica essa chave em relação ao cabeçalho Authorization: Bearer <access_key> enviado com cada solicitação de entrada.

Configurando o Ambiente de Desenvolvimento

A biblioteca oficial fastapi_poe fornece o caminho mais rápido para implementar um bot de servidor compatível. Ela abstrai a análise de HTTP, serialização de eventos e autenticação em uma interface assíncrona extensível.

Comece instalando fastapi-poe junto com um servidor ASGI como o Uvicorn:

pip install fastapi-poe uvicorn

Um bot de servidor mínimo estende PoeBot e implementa o gerador 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 a prototipagem local, você pode expor sua porta local (por exemplo, 8080) para a internet pública usando uma ferramenta de túnel como ngrok ou Cloudflare Tunnels:

ngrok http 8080

Isso gera uma URL HTTPS pública temporária (por exemplo, https://abcdef123.ngrok-free.app) que você pode inserir na interface de registro de bot do Poe para testes imediatos.

Implantando Modelos Personalizados e Pipelines de Inferência

Conectar um bot de servidor a um modelo personalizado envolve fazer a ponte das mensagens QueryRequest recebidas para um mecanismo de inferência e transmitir os tokens gerados como objetos PartialResponse.

Integração com um Back-end de Inferência vLLM ou Hugging Face

Ao executar modelos de pesos abertos (como Llama 3, Mistral ou Qwen) em hardware de GPU dedicado, servi-los através de um mecanismo otimizado como vLLM ou Hugging Face Text Generation Inference (TGI) oferece alta taxa de transferência e batching contínuo (continuous batching).

O exemplo a seguir ilustra um bot de servidor Poe encaminhando solicitações para um servidor de inferência vLLM compatível com a 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"))

Lidando com Contexto Multi-Turno e Anexos

O Poe envia o histórico completo do diálogo no array request.query, em ordem cronológica. Se o seu modelo personalizado tiver uma janela de contexto limitada, a lógica do seu bot de servidor deve podar ou resumir turnos anteriores antes da tokenização.

Quando o seu bot ativa allow_attachments=True em get_settings, os uploads de arquivos (imagens, PDFs, documentos de texto) aparecem em request.query[-1].attachments. Cada objeto de anexo contém uma URL de download e tipo MIME, permitindo que o seu back-end baixe o ativo, realize OCR, execute codificação de visão ou incorpore o documento em um armazenamento de vetor antes de gerar uma resposta.

Opções de Hospedagem para Bots de Servidor

Como o Poe requer um endpoint HTTPS ininterrupto capaz de transmitir respostas SSE, a seleção da plataforma de hospedagem certa depende do tamanho do seu modelo, requisitos de computação e orçamento.

Implantação Serverless de GPU com Modal

O Modal fornece suporte de primeira classe para bots de servidor Poe, permitindo que os desenvolvedores definam a infraestrutura de GPU como código e paguem apenas pelo tempo de execução real. O Modal dimensiona automaticamente instâncias de contêineres a partir de zero e fornece uma URL HTTPS.

Um script de implantação do Modal pronto para produção:

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"])

Implantar este serviço com modal deploy app.py emite uma URL permanente como: https://<organization>--poe-custom-model-bot-fastapi-app.modal.run.

Hospedagem de Contêineres em Provedores de Nuvem (AWS, GCP, Render, Fly.io)

Para equipes executando clusters de inferência proprietários ou aproveitando plataformas de contêineres gerenciadas:

1. Dockerize a Aplicação: Crie um Dockerfile leve executando uvicorn app:app --host 0.0.0.0 --port 8080 --workers 4.
2. Proxy Reverso e SSL: Implante por trás de um controlador de entrada (como AWS ALB, Cloudflare ou Nginx) que suporte conexões HTTP duradouras e respostas fragmentadas (chunked) em streaming. Certifique-se de que os tempos limite do proxy (por exemplo, proxy_read_timeout) sejam configurados para pelo menos 300 segundos para evitar desconexões no meio da transmissão.
3. Segredos de Ambiente: Injete POE_ACCESS_KEY e credenciais de inferência de forma segura por meio de variáveis de ambiente do contêiner.

Registrando e Configurando o Bot no Poe

Depois que o seu servidor estiver implantado e acessível via HTTPS público, conclua o registro na plataforma Poe:

1. Acesse poe.com/create_bot?server=1.
2. Nome de Usuário do Bot (Bot Handle): Escolha um identificador alfanumérico exclusivo (por exemplo, @MyCustomModel). Isso forma o link público do seu bot.
3. Tipo de Bot: Certifique-se de que "Server bot" está selecionado.
4. URL do Servidor: Insira o endpoint público completo (por exemplo, https://your-domain.com/ ou a sua URL de implantação do Modal).
5. Chave de Acesso (Access Key): Cole o token secreto configurado na chamada fp.make_app() do seu servidor. O Poe validará esse token com cada solicitação de teste.
6. Detalhes do Perfil: Defina o nome de exibição, descrição, avatar e instruções do sistema visíveis aos usuários.
7. Visibilidade: Selecione se o bot deve permanecer privado (acessível apenas para você ou membros da equipe designados) ou público (pesquisável no diretório Explorar do Poe).

Clique em Create Bot (Criar Bot). O Poe verifica a conectividade imediatamente emitindo um SettingsRequest para o seu endpoint. Se o servidor retornar uma resposta válida, o bot será ativado.

Monetização e Economia de Pontos de Computação

O Poe oferece monetização nativa de criadores para bots de servidor, permitindo que desenvolvedores ganhem receita à medida que os usuários interagem com suas ferramentas.

Preço por Mensagem e API de Monetização de Bots

Os criadores podem definir um custo fixo de pontos de computação por mensagem nas configurações do bot, ou utilizar a API de Monetização de Bots para faturamento dinâmico baseado no uso:

• Participação na Receita de Assinaturas: Quando novos usuários assinam o Poe após interagir com o seu bot, você recebe um pagamento de afiliado.
• Consumo de Pontos de Computação: Quando assinantes do Poe ou usuários gratuitos existentes gastam pontos de computação no seu bot, você ganha receita proporcional aos pontos consumidos.
• Preços Variáveis: Se o seu modelo realizar tarefas com custos computacionais imprevisíveis (por exemplo, renderização de imagem de alta resolução ou análise de documentos de longo contexto), você pode configurar preços variáveis usando os endpoints authorize_cost e capture_cost. Os usuários são avisados com um rate_card ou cost_label claro antes que operações de alto custo sejam executadas.

# 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"
    )

Melhores Práticas de Produção

A implantação de um bot de servidor confiável exige que se lide com a volatilidade da rede, orçamentos de latência e telemetria operacional:

• Implemente Streaming Imediato: Os usuários percebem baixa latência quando o primeiro token aparece rapidamente. Evite armazenar gerações inteiras de modelos em buffer na memória antes de gerar resultados. Comece a emitir tokens assim que o primeiro bloco chegar do seu back-end de inferência.
• Recuperação Elegante de Erros: Encapsule as chamadas do modelo em manipuladores de exceção estruturados. Se um worker de GPU falhar, retorne uma fp.ErrorResponse com uma explicação clara e defina allow_retry=True para que o usuário possa reativar a consulta sem recarregar o aplicativo.
• Sugestões de Acompanhamento (Follow-Ups): Melhore o envolvimento anexando respostas sugeridas por meio de fp.MetaResponse(suggested_replies=["Explain further", "Provide code sample"]) ao final de uma resposta.
• Monitore a Telemetria: Implemente o método on_feedback em sua classe PoeBot para registrar avaliações positivas (polegar para cima) e negativas (polegar para baixo) diretamente em sua plataforma de observabilidade (ex., Datadog, Prometheus ou Grafana).