Como configurar a busca web e as Community Tools no HuggingChat para fundamentar modelos abertos em fontes em tempo real

Os modelos de linguagem abertos (open-access models) oferecem transparência total sobre pesos e arquitetura, mas sofrem com janelas de treinamento estáticas e alucinações factuais diante de publicações científicas recentes, novos relatórios técnicos ou eventos dinâmicos. O ecossistema de conversação HuggingChat — mantido pela Hugging Face com base no projeto de código aberto chat-ui — soluciona essa deficiência por meio de dois recursos nativos de fundamentação (grounding): a busca web integrada (Web Search) e as ferramentas comunitárias (Community Tools).

Neste guia prático, detalhamos como pesquisadores e desenvolvedores podem habilitar a recuperação web, construir e registrar ferramentas personalizadas via Gradio Spaces e empacotar assistentes de pesquisa fundamentados com modelos como Command R+, Llama 3.1 e Qwen 2.5.

1. Fundamentação direta: Busca web nativa no HuggingChat

Para investigações cotidianas e conferência rápida de dados factuais, o HuggingChat integra um pipeline completo de Geração Aumentada por Recuperação (RAG).

Ativação na interface

1. Acesse o HuggingChat (https://huggingface.co/chat).
2. Escolha um modelo base com boa capacidade de raciocínio e seguimento de instruções (como Meta Llama 3.1 70B, Cohere Command R+ ou Qwen 2.5 72B).
3. Na caixa inferior de envio de mensagens, ative a chave Search web (representada pelo ícone de globo).
4. Digite a consulta desejada (por exemplo: "Quais são os principais benchmarks do relatório técnico do DeepSeek-V3 divulgado esta semana?").

Como o pipeline opera nos bastidores

O HuggingChat não se limita a concatenar resultados de busca no prompt. O backend do chat-ui executa um ciclo de seis etapas:

• Refinamento da consulta: Um modelo de tarefas interno interpreta a intenção do usuário e gera termos de pesquisa concisos.
• Consulta a provedores: O sistema contata serviços de busca (como Serper ou instâncias do SearXNG) para capturar as URLs mais relevantes.
• Raspagem headless com Playwright: Mecanismos de navegação sem interface gráfica carregam as páginas e convertem o HTML bruto em texto Markdown limpo.
• Segmentação e vetorização: O texto extraído é particionado em blocos semânticos e transformado em vetores através de um modelo leve de embeddings (como gte-small).
• Ranqueamento por similaridade: O sistema calcula a similaridade com a pergunta do usuário e seleciona os trechos mais relevantes dentro de um limite pré-estabelecido (geralmente até 8.000 caracteres).
• Injeção de contexto e citação: Os trechos selecionados entram no contexto do modelo, que formula a resposta final exibindo chips de citação clicáveis com os links diretos das fontes.

2. Fluxos avançados: Criação e configuração de Community Tools

A pesquisa acadêmica e a engenharia de software frequentemente exigem consultas a endpoints especializados, como o repositório de artigos ArXiv ou bases documentais internas. O recurso Community Tools do HuggingChat possibilita transformar qualquer Hugging Face Space público baseado em Gradio em uma ferramenta invocável pelo LLM.

Passo 1: Preparar o Space em Gradio

Qualquer Space público que exponha entradas e saídas bem definidas pode ser integrado.

• Modelos prontos: A Hugging Face fornece templates como o nsarrazin/rag-tool-template, que cria um mecanismo RAG sobre arquivos PDF ou Markdown colocados no diretório sources/.
• Ferramenta personalizada em Python: Você pode criar um arquivo app.py em uma máquina gratuita CPU Basic. Veja um exemplo simples para consultar preprints no ArXiv:

import gradio as gr
import urllib.request
import xml.etree.ElementTree as ET

def search_arxiv(query: str, max_results: int = 3) -> str:
    url = f"http://export.arxiv.org/api/query?search_query=all:{urllib.parse.quote(query)}&max_results={max_results}"
    response = urllib.request.urlopen(url).read().decode("utf-8")
    root = ET.fromstring(response)
    results = []
    for entry in root.findall("{http://www.w3.org/2005/Atom}entry"):
        title = entry.find("{http://www.w3.org/2005/Atom}title").text.strip()
        summary = entry.find("{http://www.w3.org/2005/Atom}summary").text.strip()
        results.append(f"Title: {title}\nSummary: {summary}\n")
    return "\n---\n".join(results) if results else "No papers found."

demo = gr.Interface(
    fn=search_arxiv,
    inputs=[gr.Textbox(label="Query"), gr.Number(label="Max Results", value=3)],
    outputs="text",
    title="ArXiv Search Tool"
)

demo.launch()

Passo 2: Registrar a ferramenta no HuggingChat

1. Acesse https://huggingface.co/chat/tools e clique em Create New Tool (ou acesse https://huggingface.co/chat/tools/new).
2. No campo Hugging Face Space URL, cole a URL do seu Space (por exemplo: https://huggingface.co/spaces/seu-usuario/arxiv-search).
3. O HuggingChat lê automaticamente o esquema do Gradio e identifica os parâmetros.
4. Preencha os campos essenciais:
   • Tool Description: Escreva uma descrição concisa em inglês explicando a finalidade da ferramenta e quando utilizá-la (exemplo: "Searches ArXiv for the latest AI and computer science preprints based on query keywords"). O modelo lê essa descrição para decidir quando acionar o método.
   • AI Function Name: Defina um nome identificador único no padrão snake_case (exemplo: search_arxiv_preprints).
   • Configuração de argumentos (Arguments):
     • Required: O modelo é obrigado a fornecer um valor para chamar a ferramenta.
     • Optional: Possui um valor padrão que pode ser substituído pelo modelo conforme a necessidade.
     • Fixed: Valor fixado na criação da ferramenta e invisível para o modelo (útil para chaves de API internas ou filtros fixos).
5. Salve a ferramenta. Ela estará disponível na sua biblioteca para uso imediato.

3. Empacotamento em um Assistente Dedicado (HuggingChat Assistant)

Para evitar reconfigurações manuais em cada nova sessão de pesquisa, crie um Assistant personalizado com parâmetros e ferramentas consolidados:

1. Abra Settings > Assistants ou navegue até https://huggingface.co/chat/settings/assistants/new.
2. Definições básicas: Forneça um nome para o assistente (exemplo: "Assistente de Pesquisa Científica") e escolha um avatar.
3. Seleção do modelo: Escolha modelos abertos treinados para chamada de ferramentas (tool calling). O Cohere Command R+ e o Llama 3.1 70B são especialmente eficientes no acionamento consistente de funções e citação precisa.
4. Instruções do sistema (System Instructions): Defina critérios rigorosos de verificação de fatos:

   Você é um assistente de pesquisa técnica e científica.
   Ao responder sobre artigos recentes, benchmarks ou lançamentos, execute sempre a busca web ou as ferramentas de consulta antes de emitir qualquer afirmação.
   Não faça suposições que não estejam expressamente fundamentadas nos dados retornados pelas fontes.
   Inclua sempre os títulos e URLs das fontes originais na sua resposta.
   

5. Vincular recursos e ferramentas:
   • Habilite Web search para conferir acesso contínuo à internet ao assistente.
   • Na seção Community Tools, selecione até 3 ferramentas ativas da sua biblioteca ou da comunidade.
6. Clique em Create. O assistente pode ser compartilhado via link direto ou mantido restrito para avaliações internas de sua equipe.

4. Implementação em infraestrutura própria (chat-ui)

Para laboratórios acadêmicos e organizações que necessitam de isolamento total de dados e conformidade com privacidade, a Hugging Face disponibiliza o código integral no repositório huggingface/chat-ui.

Configuração no .env.local

Defina os provedores de busca e os servidores de inferência locais:

# Banco de dados MongoDB
MONGODB_URL=mongodb://localhost:27017
MONGODB_DB_NAME=chat-ui

# Ponto de inferência compatível com OpenAI (vLLM, Ollama, llama.cpp ou Hugging Face Router)
OPENAI_BASE_URL=https://router.huggingface.co/v1
OPENAI_API_KEY=hf_seu_token_huggingface

# Provedor de busca na web
SERPER_API_KEY=sua_chave_api_serper
# Ou utilizando uma instância própria do SearXNG:
# SEARXNG_QUERY_URL=http://localhost:8080/search?q=<query>&format=json

# Parâmetros de raspagem e segurança
USE_LOCAL_WEBSEARCH=false
WEBSEARCH_ALLOWLIST=[]
WEBSEARCH_BLOCKLIST=[]

Após rodar npm install e npm run dev, sua organização terá um ambiente privativo de chat com navegação web e RAG em execução direta na sua infraestrutura.

Boas práticas e trade-offs técnicos

• Porte do modelo e consistência de ferramentas: Modelos de 8B ou menores apresentam maior probabilidade de gerar argumentos com formatação incorreta ou forjar URLs fictícias na ausência de resultados. Para análises acadêmicas e técnicas, prefira modelos na faixa de 70B ou arquiteturas especializadas como o Command R+.
• Latência versus atualização: Respostas puramente textuais levam de 1 a 3 segundos, enquanto uma rodada completa de RAG na web (com crawling do Playwright, chunking e embeddings) costuma acrescentar de 3 a 6 segundos. Se houver um conjunto fixo de artigos a consultar, prefira pré-indexá-los em um Space de RAG dedicado em vez de raspar a web a cada chamada.
• Inspeção de citações: O maior valor do RAG aberto é a auditabilidade. Sempre clique nos chips de citação para checar se o trecho original realmente respalda a conclusão formulada pelo modelo, evitando o viés de confirmação.

Ao aliar a busca web nativa às Community Tools, o HuggingChat transforma modelos de pesos abertos em plataformas de pesquisa altamente atualizadas e ancoradas em evidências do mundo real.

Referências

• Introducing Community Tools on HuggingChat
• HuggingChat - Chat with AI models
• GitHub - huggingface/chat-ui: The open source codebase powering HuggingChat
• Rag Community Tool Template - a Hugging Face Space by nsarrazin