Chat de IA

O chat de IA do Docsbook é um widget no seu site de documentação que responde à pergunta de um leitor com base no conteúdo dessa documentação. O leitor faz uma pergunta, o servidor pesquisa suas páginas, busca as que correspondem e transmite de volta uma resposta que as cita.

O que vale a pena verificar em qualquer assistente de documentação não é se ele responde — é o que ele faz quando não consegue. Esta página é o contrato de ambos os lados. O pipeline em si está em Qualidade das respostas.

O que você obtém#

Uma resposta na página, não um chamado. Um leitor que formula a pergunta de maneira diferente do seu título ainda chega à página que a responde.
Um rastro visível. O widget imprime Found N results, depois uma linha Reading <page> para cada página aberta. Cada linha é um link, para que um leitor cético possa acessar e verificar a fonte por conta própria.
Citações abaixo da resposta. Uma citação só permanece se o servidor realmente buscou essa página para esta pergunta ou se a resposta citou o caminho dela no texto. Um caminho que o modelo não leu nem citou é removido antes que o leitor o veja.
Perguntas de acompanhamento. Três próximas perguntas curtas são geradas a partir da resposta e oferecidas como botões.
Um registro do que falhou. As perguntas que o assistente não conseguiu responder tornam-se um relatório de perguntas sem resposta e um webhook chat.no_answer, que é a lista de páginas que você ainda não escreveu.

O que o assistente não fará#

Ele não irá	Por quê
Responder com base no conhecimento pré-treinado do próprio modelo	O bloco de instruções proíbe recorrer ao conhecimento geral para definir um termo ou preencher uma lacuna que sua documentação não aborda
Citar uma página que ele não leu nem mencionou	Uma citação só é válida se o caminho tiver sido mencionado em linha na resposta ou se for uma página que o servidor realmente buscou. A parte buscada é fundamentada por construção; a parte em linha não é — consulte Qualidade da resposta
Inventar um fluxo de configuração	Para "como configuro X", ele deve apontar para uma frase no seu conteúdo que nomeie um caminho de menu, botão ou etapa concreta. Uma simples menção a X não é um fluxo de configuração, e ele foi instruído a dizer isso
Omitir uma pré-condição declarada	Se uma página declarar um plano, função, etapa anterior, versão ou cota obrigatória, a resposta deverá incluí-la — inclusive quando esse requisito estiver declarado apenas na introdução da página
Misturar um recurso gratuito com sua atualização paga	Páginas que descrevem coisas relacionadas, mas diferentes, são mantidas distintas de propósito
Adivinhar uma âncora	O destino do link para um título citado é calculado pelo servidor com o mesmo gerador de identificadores que renderiza sua página, nunca obtido do modelo

Como uma resposta é produzida?#

Versão curta; os detalhes estão em Qualidade das respostas.

Pré-hook opcional. Se você registrou um, seu endpoint recebe a pergunta primeiro e pode bloqueá-la ou injetar contexto. Consulte Hooks de chat.
Recuperação. A pesquisa vetorial e a pesquisa de texto completo do Postgres são executadas, e os resultados são mesclados — limitados a cinco páginas no total. Dois fallbacks lexicais abrangem corpora sem índice vetorial.
Busca. Cada página selecionada é lida do seu repositório em seu branch padrão e limitada a 12.000 caracteres, mantendo o início e o fim.
Geração. As páginas, seu prompt de sistema e as regras de fundamentação são enviados ao modelo; a resposta retorna em fluxo como markdown, além de um array de citações.
Filtragem de citações. As referências são verificadas em relação às páginas realmente lidas, e as âncoras são recalculadas no servidor.
Registro. As contagens de tokens e o custo do provedor são gravados no seu registro de uso; chat.question_asked é acionado, e chat.no_answer também quando a resposta admitiu que não sabia.

O que você pode configurar#

Controle	O que ele altera	Onde
Prompt do sistema	Substitui a instrução padrão pela sua voz e pelas suas regras. Ele é adicionado junto às regras de fundamentação, não em vez delas	Configurações do chat
Perguntas sugeridas	Os prompts iniciais no estado vazio — o texto de maior impacto no widget, pois informa ao leitor para que serve o assistente	Configurações do chat
URL de chamada para ação	O assistente responde à pergunta primeiro e, em seguida, aponta para esse link em uma frase — somente quando o leitor está avaliando, comparando ou perguntando sobre limites, preços ou planos, e nunca mais de uma vez por resposta	Configurações do chat
Modelo	Qual modelo responde aos leitores. Gratuito em todos os planos	Configurações do chat
Hooks de pré / pós-processamento / streaming	Seus próprios endpoints HTTPS em torno de cada resposta	Hooks do chat
Índice semântico	Recuperação baseada em significado sobre a correspondência de palavras-chave	Float Widget → AI Chat → Semantic Search

Um assistente que termina todas as respostas com um link de preços deixa de ser confiável, o que custa mais conversões do que gera — por isso, a chamada para ação é formulada como uma restrição sobre quando oferecê-la, em vez de uma instrução permanente para fazer publicidade.

Qual modelo executa o chat?#

O padrão gerenciado do chat do leitor é openai/gpt-4o-mini por meio do OpenRouter: uma janela de contexto de 128.000 tokens e um limite de saída de 16.384 tokens, de acordo com a referência de modelos da OpenAI. Em vez disso, você pode escolher qualquer modelo do catálogo de chats, em qualquer plano, e o seletor exibe ao lado de cada modelo seu preço por milhão de tokens.

Existem duas configurações de modelo porque há dois assistentes diferentes em ação, e eles são medidos separadamente:

Modelo de Chat dos Visitantes de IA — o que responde aos seus leitores.
Modelo do Administrador e do Agente de IA — o que executa o assistente dentro do seu painel, que chama ferramentas e edita sua documentação.

Deliberadamente, elas não são uma única configuração. Certa vez, o Docsbook lançou uma versão em que o loop do administrador executava silenciosamente usando o padrão do chat do leitor porque um parâmetro não era repassado, e ambas as interfaces pareciam idênticas externamente durante semanas. Um modelo avaliado para chamadas de ferramentas não é automaticamente o modelo certo para perguntas e respostas dos leitores, e vice-versa; manter as constantes separadas é o que torna cada escolha verificável.

Apenas os modelos do catálogo publicado são aceitos na chave do Docsbook, porque os gastos são cobrados pelo preço real do modelo — um modelo não reconhecido seria cobrado a uma taxa que nunca foi exibida para você. Se você usar sua própria chave de provedor, poderá indicar qualquer modelo oferecido pelo seu provedor, e o uso será debitado da sua chave pelo preço do seu provedor, em vez do seu saldo do Docsbook.

Disponibilidade e custo#

O chat de IA para leitores é um recurso Pro. Em um projeto Free, a pergunta de um visitante é recusada antes que qualquer modelo seja chamado, independentemente da chave que o projeto possua — o bloqueio é uma decisão de nível, não de custo, portanto usar sua própria chave não o reativa. As próprias perguntas do proprietário no chat de administração continuam disponíveis em todos os planos. Os planos atuais estão na página de preços.

Três coisas no chat são contabilizadas no saldo do projeto: uma resposta a um leitor, a criação ou reconstrução do índice semântico (e a geração do embedding de cada pergunta recebida) e uma execução do agente iniciada a partir do chat. Hospedar o widget, disponibilizar a página, a pesquisa por palavras-chave, o feedback da página e as chamadas de hooks não são contabilizados.

O que é contabilizado e o que chama um modelo não são a mesma lista, e vale a pena saber em qual categoria cada item se enquadra. Atualmente, duas chamadas de modelo no fluxo do leitor não são cobradas: as três perguntas de acompanhamento sob uma resposta e o loop de pesquisa agentiva, que só é executado quando todos os recuperadores retornam vazio. Uma chamada de modelo que não faz parte do fluxo do leitor é cobrada: o avaliador que preenche a coluna Respondido na aba Chat, cobrado como trabalho de IA do proprietário.

Quando o saldo se esgota, o chat é interrompido em vez de gerar cobranças adicionais. A própria resposta do servidor distingue um limite do plano de um limite que você definiu, e apenas o primeiro é contabilizado como acesso bloqueado por paywall — portanto, um limite de origem imposto por você nunca aparece no seu funil como uma demanda por upgrade. O leitor é informado de que o chat foi pausado de qualquer forma.

O que um leitor vê quando algo falha#

Situação	O que o leitor recebe
Nenhum chat de IA conectado para este site	Uma explicação simples pedindo que entre em contato com o proprietário do site. Nunca um stack trace
Projeto no plano Free	Nada. A interface de chat não é renderizada, portanto não há botão nem mensagem — o leitor vê um site de documentação sem um assistente
Saldo esgotado	O chat pausa e informa isso
A recuperação não encontrou nada	Uma resposta que informa claramente que a documentação não aborda o assunto — e uma linha no seu relatório de perguntas sem resposta
Seu pre-hook bloqueou a pergunta	Uma mensagem de erro genérica. Veja o limite abaixo
Falha no modelo ou na rede	"Algo deu errado. Tente novamente.", no idioma do leitor

Limites#

Uma pergunta bloqueada não mostra o motivo ao leitor. A string reason do pre-hook é enviada no fluxo de resposta, mas o widget do site de documentação renderiza a mensagem de erro genérica. Em relação à pergunta: o campo é entregue e um front-end personalizado pode lê-lo, mas o widget fornecido não. Considere reason um valor para os seus próprios registos até que isto seja corrigido.
O chat multijogador está implementado, mas não está ativado. A interface de convite, o botão de presença e as rotas da API existem; o transporte não, portanto ativar uma sessão partilhada retorna "Temporarily unavailable". Não planeie com base nisso.
O detetor de ausência de resposta é uma correspondência de padrões em inglês. Uma recusa escrita noutro idioma não é reconhecida, portanto chat.no_answer e o relatório de perguntas sem resposta ficam subcontabilizados em sites que não estejam em inglês.
O feedback da resposta e o feedback da página são séries diferentes. Um polegar para baixo numa resposta não é o mesmo evento que um polegar para baixo numa página; consulte Feedback da página para saber a que cada um chega.
Não existe um valor de precisão publicado. O Docsbook não afirma uma percentagem de precisão das respostas. Qualidade das respostas explica o que é medido em alternativa e por que motivo não indicamos um valor.
O modelo de leitor predefinido pode ser alterado pelo fornecedor. A janela de contexto, o comportamento perante recusas e o preço são da responsabilidade deles; o mecanismo de recuperação e citação é nosso.

Qualidade das respostas — o pipeline completo de recuperação e fundamentação, com fontes.
Fontes — o que o assistente pode ler além das suas próprias páginas.
Hooks de chat — bloqueie, enriqueça ou replique cada resposta.
Pesquisa — o índice de palavras-chave que o chat compartilha com sua caixa de pesquisa.
Servidor MCP — gerencie as configurações do chat pelo Claude Code ou Cursor.
Preços — em que uma resposta se baseia.

Updated Sep 5, 2026