docs/tutorials/use_cases/technical_docs_chatbot.md

Caso de Uso: Chatbot de Documentacao Tecnica

Guia completo para criar um chatbot que responde perguntas sobre documentacao tecnica.

Nivel: Intermediario Tempo: 30-45 minutos Exemplo: Chatbot para documentacao de API

---

Cenario

Voce tem documentacao tecnica extensa (manuais, API docs, guias) e quer:

• Responder perguntas dos desenvolvedores rapidamente
• Reduzir tempo de onboarding
• Liberar time de suporte tecnico
• Garantir respostas precisas com citacao de fontes

---

Passo 1: Preparar Documentacao

1.1 Organizar Documentos

Estrutura recomendada:

docs/
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
├── guides/
│   ├── getting_started.md
│   ├── best_practices.md
│   └── deployment.md
└── reference/
    ├── cli.md
    └── configuration.md

1.2 Converter para Formato Suportado

O RAG Template suporta:

• TXT (texto plano)
• PDF (via pypdf)

Se sua documentacao esta em:

• Markdown: Converta para TXT ou use como esta
• HTML: Extraia texto com BeautifulSoup
• DOCX: Converta para PDF ou TXT

Exemplo de conversao MD para TXT:

for file in docs/**/*.md; do
    pandoc "$file" -t plain -o "${file%.md}.txt"
done

---

Passo 2: Otimizar Chunking para Docs Tecnicas

Documentacao tecnica tem caracteristicas especiais:

• Codigo embutido
• Listas de parametros
• Exemplos de uso
• Referencias cruzadas

2.1 Estrategia Recomendada

Use chunking recursivo com separadores customizados:

# Em src/chunking.py (ja implementado)
SEPARATORS = [
    "\n## ",  # Secoes Markdown
    "\n### ", # Subsecoes
    "\n\n",   # Paragrafos
    "\n",     # Linhas
    " "       # Palavras
]

2.2 Tamanho de Chunk

Para docs tecnicas:

• Chunk size: 800-1000 caracteres
• Overlap: 150-200 caracteres

Razao: Preservar contexto de exemplos de codigo completos.

2.3 Teste de Chunking

Use a aba "Comparacao de Chunking":

1. Cole exemplo de doc tecnica
2. Compare 4 estrategias
3. Veja qual mantem codigo/listas intactos

---

Passo 3: Configurar Embeddings para Dominio Tecnico

3.1 Modelo Recomendado

Para docs tecnicas em ingles:

EMBEDDING_MODEL_ID=sentence-transformers/all-MiniLM-L6-v2

Alternativas:

• BAAI/bge-small-en-v1.5 (melhor para docs tecnicos)
• sentence-transformers/all-mpnet-base-v2 (mais qualidade, 768d)

Para multilingu e (PT-BR + EN):

EMBEDDING_MODEL_ID=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

3.2 Ingerir Documentacao

# Inicie a aplicacao
python app.py

# Aba: Ingestao de Documentos
# 1. Upload de todos os arquivos (batch)
# 2. Estrategia: Recursivo
# 3. Chunk Size: 900
# 4. Overlap: 200
# 5. Iniciar Ingestao

Tempo estimado: ~5-10min para 100 docs

---

Passo 4: Configurar Retrieval Otimizado

4.1 Hybrid Search

Documentacao tecnica se beneficia de hybrid search:

• BM25: Para termos tecnicos exatos (nomes de funcoes, parametros)
• Vetorial: Para busca semantica (conceitos)

Configure:

USE_HYBRID_SEARCH=true
HYBRID_ALPHA=0.4  # Enfase em BM25 para termos exatos

4.2 Reranking

Ative reranking para melhor precisao:

USE_RERANKING=true
RERANKING_TOP_K=5

Pipeline:

1. Hybrid search recupera 20 documentos
2. Reranker seleciona top 5 mais relevantes
3. LLM usa apenas os 5 melhores

---

Passo 5: Configurar LLM para Docs Tecnicas

5.1 Escolher LLM

Para docs tecnicas, recomendamos:

• GPT-4 (melhor, mas caro): Entende codigo perfeitamente
• GPT-3.5-turbo (bom custo-beneficio): Adequado para maioria
• Claude 3 (excelente para textos longos)

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

5.2 Ajustar Parametros

TOP_K=5              # Contextos recuperados
TEMPERATURE=0.2      # Baixa = mais preciso
MAX_TOKENS=512       # Respostas concisas

5.3 Customizar Prompt

Edite src/generation.py para prompt especifico:

SYSTEM_PROMPT = """
Voce e um assistente especializado em documentacao tecnica.

DIRETRIZES:
1. Responda APENAS com base nos contextos fornecidos
2. Se a resposta nao esta nos contextos, diga "Nao encontrei essa informacao na documentacao"
3. Cite sempre a secao/arquivo de onde veio a informacao
4. Para codigo, use formatacao markdown com ```
5. Seja preciso e tecnico, nao simplifique demais

FORMATO DE RESPOSTA:
- Resposta direta e objetiva
- Exemplo de codigo (se aplicavel)
- Referencia: [Secao X da Documentacao]
"""

---

Passo 6: Testar e Refinar

6.1 Casos de Teste

Crie suite de perguntas comuns:

1. Como autenticar na API?
2. Quais sao os endpoints disponiveis?
3. Como tratar erro 401?
4. Qual o rate limit da API?
5. Como fazer deploy em producao?

6.2 Avaliar Qualidade

Para cada pergunta, verifique:

• Resposta esta correta?
• Fonte esta citada?
• Codigo de exemplo esta incluso (se relevante)?
• Resposta e completa mas concisa?

6.3 Iterar

Se qualidade nao e satisfatoria:

1. Ajuste chunk_size
2. Teste hybrid_alpha diferente
3. Aumente/diminua top_k
4. Melhore prompt
5. Considere modelo de LLM melhor

---

Passo 7: Interface Customizada (Opcional)

7.1 Adicionar Features Especificas

Exemplo: Botao "Ver na Documentacao":

# ui/chat_tab.py
def chat_tab():
    # ... codigo existente ...

    with gr.Accordion("Contextos Recuperados"):
        for ctx in contexts:
            with gr.Row():
                gr.Markdown(ctx['content'])
                gr.Button(
                    "Ver Doc Original",
                    link=f"/docs/{ctx['source']}"
                )

7.2 Adicionar Atalhos

Botoes para perguntas comuns:

common_questions = [
    "Como autenticar?",
    "Quais endpoints existem?",
    "Como tratar erros?",
]

for q in common_questions:
    gr.Button(q).click(
        fn=lambda x=q: x,
        outputs=query_input
    )

---

Passo 8: Deploy

8.1 Opcoes Recomendadas

Para chatbot de docs tecnicas:

• Interno: Docker em VPS privado
• Publico: Hugging Face Spaces ou Railway
• Enterprise: Kubernetes com autenticacao

8.2 Consideracoes de Seguranca

Se docs sao privadas:

1. Nao use Hugging Face Spaces publico
2. Configure autenticacao (Gradio auth)
3. Use VPN/firewall
4. Database privado

# app.py
demo.launch(
    auth=("username", "password"),
    server_name="0.0.0.0",
    server_port=7860,
    share=False  # Nao criar link publico
)

---

Passo 9: Monitoramento

9.1 Metricas Importantes

Track:

• Perguntas mais comuns: Identifique gaps na doc
• Taxa de "nao encontrei": Indica docs incompletas
• Tempo de resposta: Otimize se >5s
• Feedback dos usuarios: Thumbs up/down

9.2 Melhorias Continuas

Baseado em dados:

1. Adicione docs para perguntas frequentes sem resposta
2. Melhore chunking se contextos estao quebrados
3. Atualize prompt baseado em feedback
4. Considere fine-tuning se volume e alto

---

Resultados Esperados

Antes (sem chatbot)

• Tempo medio para resposta: 30min-2h
• Desenvolvedores pesquisando em docs extensas
• Suporte sobrecarregado

Depois (com RAG chatbot)

• Tempo medio: <30 segundos
• Auto-servico para 70-80% das perguntas
• Suporte focado em problemas complexos
• Onboarding 3x mais rapido

---

Casos Reais

Exemplo 1: Startup de API

Situacao: 500 paginas de API docs, time pequeno Solucao: RAG chatbot com GPT-3.5 Resultado:

• 60% reducao em tickets de suporte
• NPS +15 pontos
• Tempo de onboarding: 2 semanas → 3 dias

Exemplo 2: Empresa Enterprise

Situacao: Docs internas distribuidas, 10k+ paginas Solucao: RAG com hybrid search + reranking Resultado:

• Busca 10x mais rapida que busca nativa
• Encontra informacao cross-docs
• ROI positivo em 2 meses

---

Proximos Passos

1. Multi-idioma: Adicione docs em outros idiomas
2. Feedback loop: Implemente thumbs up/down
3. Analytics: Track metricas de uso
4. Integracoes: Slack bot, VS Code extension

---

Recursos

• Tutorial: Otimizando RAG
• Tutorial: Deploy em Producao
• FAQ

---

Tempo total de implementacao: 2-4 horas Manutencao: ~1h/semana (adicionar novos docs)