Ask AI

Um assistente na própria página fundamentado na sua documentação — perguntas sugeridas, instruções personalizadas, dimensionamento da recuperação, backends do Vercel AI Gateway a qualquer endpoint compatível com OpenAI, e a saída de servidor que ele exige.

Adicione um assistente que responde às perguntas dos leitores num painel de chat na própria página, apoiado por um endpoint de servidor com streaming e pelo AI SDK. É opcional, e a documentação estática continua totalmente estática até você ativá-lo:

ai: {
  ask: {
    enabled: true,
    provider: "gateway", // default
    model: "openai/gpt-5.5",
  },
}

Perguntas sugeridas

Preencha o estado vazio com alguns prompts iniciais. Cada um aparece como uma sugestão clicável — clique em uma para enviá-la — com um ícone Lucide opcional ao lado do rótulo:

ai: {
  ask: {
    enabled: true,
    suggestions: [
      { label: "What is Blume?", icon: "rocket" },
      { label: "How do I write a docs page?", icon: "file-text" },
      { label: "How do I configure the theme?", icon: "settings" },
    ],
  },
}

label é a pergunta que será feita; icon é opcional. Deixe suggestions sem definir (ou vazio) e o painel abre com um campo de entrada simples.

Instruções personalizadas

Adicione o seu próprio texto de system prompt com instructions — identidade, idioma, tom ou qualquer outra coisa que o assistente deva ter em mente:

ai: {
  ask: {
    enabled: true,
    instructions:
      "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
  },
}

Seu texto é acrescentado às instruções internas em vez de substituí-las: a parte interna carrega o contrato de fundamentação — responder apenas a partir das páginas recuperadas, citá-las como links Markdown — do qual as citações do painel de chat dependem, então ela permanece intacta independentemente do que você adicionar.

Fundamentação

O Ask AI é fundamentado na sua documentação. Para cada pergunta ele recupera as páginas mais relevantes — usando o mesmo índice léxico do Orama que alimenta a busca na página — e as injeta no system prompt do modelo, de forma que as respostas venham do seu conteúdo e não do conhecimento próprio do modelo. O assistente é instruído a responder apenas a partir das páginas recuperadas, a dizer quando algo não está coberto e a citar as páginas de onde tirou a informação.

A página em que o leitor está no momento é adicionada primeiro ao contexto e usada para limitar a recuperação ao idioma daquela página, para que as respostas continuem relevantes ao ponto em que ele está na documentação. A recuperação roda no momento da requisição a partir de um snapshot embutido no build, então funciona independentemente do seu provedor de busca — até mesmo quando a busca está definida como none — e não precisa de configuração.

A fundamentação está ativa para todos os backends, exceto o Inkeep, que roda a própria recuperação sobre o conteúdo que você indexou no painel dele.

Tamanho da recuperação

Quanta documentação uma pergunta carrega é a maior alavanca sobre quanto tempo o leitor espera pela primeira palavra: o modelo lê cada caractere injetado antes de emitir um token. Em um modelo de fronteira hospedado isso é imperceptível, mas em um backend auto-hospedado é o fator dominante. retrieval dimensiona isso:

ai: {
  ask: {
    enabled: true,
    retrieval: {
      maxResults: 3, // fewer pages retrieved per question
      excerptChars: 1200, // shorter excerpt from each one
      contextBudget: 3000, // smaller total injection
    },
  },
}

Os três não são intercambiáveis. contextBudget limita toda a injeção, excerptChars decide quão fundo o trecho de uma única página longa vai — aumente quando uma página contém a resposta inteira e o trecho a corta — e maxResults limita quantas páginas a recuperação adiciona. A página que o leitor está vendo é injetada além das recuperadas, então uma resposta pode citar até uma página a mais que maxResults.

Os padrões servem bem para um modelo hospedado. Reduza-os quando você estiver servindo a partir do seu próprio hardware e o tempo até o primeiro token importar mais que a abrangência; as respostas continuam fundamentadas de qualquer forma, e o assistente é instruído a dizer quando algo não está coberto em vez de preencher a lacuna.

Endpoint externo

Já tem um backend de API para IA? Aponte o painel para ele e mantenha o build da documentação estático:

ai: {
  ask: {
    enabled: true,
    endpoint: "https://api.example.com/v1/docs/ask",
  },
}

O Blume envia o mesmo corpo POST que a rota interna:

{
  "messages": [{ "role": "user", "content": "How do I deploy?" }],
  "page": { "path": "/deployment" }
}

Retorne uma resposta bem-sucedida cujo corpo seja um fluxo de texto UTF-8 puro. Se o endpoint estiver em outra origem, permita a origem da documentação com CORS: aceite OPTIONS e POST, permita o cabeçalho de requisição content-type e retorne os cabeçalhos CORS tanto no preflight quanto na resposta com streaming. Com endpoint definido, o Blume gera a interface de chat mas nenhuma rota de servidor, snapshot de fundamentação, dependência de provedor ou aviso de segredo de provedor; seu backend fica responsável pela recuperação, autenticação, limitação de taxa, acesso ao modelo e citações.

Saída de servidor obrigatória

O backend interno do Ask AI no Blume é uma rota de servidor (POST /api/ask), então ele não pode rodar num build estático. Mude para saída de servidor e escolha um adaptador:

deployment: {
  output: "server",
  adapter: "vercel",
}

Um build estático com o Ask AI ativado e sem um endpoint externo falha imediatamente com uma mensagem dizendo para você definir deployment.output como server. Veja Implantação para os adaptadores.

Backends

Por padrão o Ask AI passa pelo Vercel AI Gateway: model é uma string provider/model, então você troca de modelo alterando esse valor (openai/gpt-5.5, anthropic/claude-sonnet-4-5 e assim por diante) sem nenhum SDK de provedor para instalar. O gateway lê AI_GATEWAY_API_KEY do seu ambiente e é configurado automaticamente quando você faz o deploy na Vercel.

Defina provider para apontar o Ask AI para outro lugar. Cada backend lê sua chave de API a partir de uma variável de ambiente e faz streaming por meio de um SDK de provedor que você instala no seu projeto — apenas o que você usar:

Os SDKs são dependências de par opcionais, então adicione ao seu projeto aquele de que o seu backend precisa (por exemplo, npm install @openrouter/ai-sdk-provider). Se estiver faltando, o build avisa com o nome exato do pacote antes que o Vite falhe ao resolver o import.

Por exemplo, para usar o OpenRouter:

ai: {
  ask: {
    enabled: true,
    provider: "openrouter",
    model: "anthropic/claude-sonnet-4-5",
  },
}

Qualquer endpoint compatível com OpenAI funciona através de openai-compatible — informe a baseUrl e a variável de ambiente que contém a chave dele:

ai: {
  ask: {
    enabled: true,
    provider: "openai-compatible",
    baseUrl: "https://my-gateway.example.com/v1",
    apiKeyEnv: "MY_GATEWAY_API_KEY",
    model: "gpt-4o",
  },
}

Defina apiKeyEnv (e, para os provedores nomeados, baseUrl) em qualquer backend para apontar para uma variável de ambiente ou proxy diferente.

As chaves são lidas com process.env, o que cobre os adaptadores Node, Vercel e Netlify. No Cloudflare, exponha a chave através do runtime binding da plataforma. Ativar o Ask AI também liga o React para a ilha na página — veja Personalização.

Limitação de taxa

O endpoint POST /api/ask é não autenticado — ele precisa ser, para que o assistente na página possa chamá-lo. O Blume valida cada requisição — rejeitando corpos malformados, limitando a 1–40 mensagens e aceitando apenas os papéis user/assistant para que quem chama não possa injetar o próprio system prompt e reaproveitar a rota como um proxy genérico de LLM — para limitar quanto uma única chamada pode gastar com o seu modelo, mas isso não impede alguém de chamar o endpoint repetidamente. Se o abuso de custos for uma preocupação, coloque a rota atrás de um limitador de taxa — a limitação de taxa na borda do seu host (a da Vercel, por exemplo), um middleware, ou os limites de gasto por chave do seu provedor de modelos.

O endpoint é anunciado no manifesto de legibilidade para agentes junto com o restante da superfície legível por máquina do site.