Como conectar tokens de conta do Hugging Face e endpoints de inferência personalizados ao HuggingChat

Executar modelos de código aberto privados ou versões proprietárias ajustadas (fine-tuning) na interface do HuggingChat exige compreender como a plataforma foi estruturada. Muitos desenvolvedores acessam a versão pública do HuggingChat (hf.co/chat) procurando uma tela de configurações onde possam inserir a URL de um endpoint próprio e um token de API. No entanto, o HuggingChat público opera como um serviço multilocatário hospedado diretamente sobre a infraestrutura de roteamento gerenciada do Hugging Face; por questões de segurança, isolamento e controle de tráfego, a plataforma pública não permite conectar endpoints dedicados externos à interface compartilhada.

A maneira oficial e recomendada para produção para utilizar a interface do HuggingChat com modelos privados é realizar o deploy da sua própria instância do Chat UI — a aplicação web em SvelteKit de código aberto que serve de base para o HuggingChat. O Chat UI possui compatibilidade nativa com APIs no padrão OpenAI, permitindo que você aponte as variáveis de ambiente OPENAI_BASE_URL e OPENAI_API_KEY diretamente para o seu Hugging Face Inference Endpoint dedicado, que roda com Text Generation Inference (TGI) ou vLLM. O deploy pode ser executado em poucos minutos em um Hugging Face Space privado ou em contêineres Docker locais.

Fluxo da arquitetura

A conexão completa une três partes essenciais:

1. Hugging Face Inference Endpoints: Hospeda os pesos do seu modelo privado ou customizado (como Llama 3.3, Mistral, Qwen ou adaptadores LoRA corporativos) utilizando motores de alto desempenho como TGI ou vLLM, expondo uma rota REST padrão OpenAI (/v1/chat/completions).
2. User Access Token (HF_TOKEN): Fornece autenticação para validar as chamadas enviadas ao seu endpoint privado.
3. Chat UI (Instância privada do HuggingChat): A aplicação frontend que consome o endpoint dedicado, disponibilizando recursos completos de conversação, suporte multimodal e execução de ferramentas.

+-------------------------------------------------------------+
|                 Instância privada de Chat UI                |
|             (Hugging Face Space / Docker local)             |
+-------------------------------------------------------------+
                               |
               OPENAI_BASE_URL | OPENAI_API_KEY (hf_xxx)
                               v
+-------------------------------------------------------------+
|             Hugging Face Inference Endpoint                 |
|   https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1   |
|                 (Executando TGI ou vLLM em GPU)             |
+-------------------------------------------------------------+
                               |
                               v
+-------------------------------------------------------------+
|               Repositório privado / Pesos do modelo         |
+-------------------------------------------------------------+

Passo 1: Criar o endpoint de inferência personalizado

Para disponibilizar um modelo privado com computação dedicada:

1. Acesse o painel de Inference Endpoints.
2. Clique no botão Create New Endpoint.
3. Model Repository: Informe o identificador do repositório privado (ex.: sua-organizacao/modelo-privado-8b-instruct) ou escolha um modelo do Hub.
4. Cloud Provider & Region: Selecione o provedor de nuvem (AWS ou Azure) e uma região próxima da sua equipe.
5. Instance Type: Escolha uma configuração de hardware com GPU compatível com o tamanho do modelo (ex.: 1x NVIDIA A10G para modelos de 8B, ou múltiplos nós A100/H100 para modelos de 70B).
6. Framework & Engine: Verifique se o container utiliza Text Generation Inference (TGI) ou vLLM. Ambos fornecem compatibilidade nativa com o formato de API da OpenAI.
7. Clique em Create Endpoint.

Aguarde até que o status passe de Building para Running. Copie a URL única gerada pelo painel:

https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud

Passo 2: Gerar um token de acesso à conta

Endpoints dedicados exigem autenticação obrigatória para todas as requisições:

1. Navegue até Settings > Access Tokens na sua conta (hf.co/settings/tokens).
2. Clique em Create new token.
3. Defina a categoria do token:
   • Fine-grained token (Recomendado): Em Inference, habilite a permissão "Make calls to your Inference Endpoints".
   • Read token: Tokens com permissão padrão de leitura também conseguem autenticar chamadas em endpoints vinculados à sua conta pessoal.
4. Copie o valor gerado (hf_...) e armazene-o de maneira segura.

Passo 3: Configurar e iniciar o Chat UI (HuggingChat)

O Chat UI descobre e consome modelos adicionando automaticamente o sufixo /v1 ao endereço base.

Opção A: Deploy direto no Hugging Face Spaces (Recomendado)

Para disponibilizar uma interface de chat compartilhada para sua equipe sem gerenciar infraestrutura de servidores:

1. Acesse o template oficial de Space do Chat UI.
2. Configure a visibilidade como Private para impedir o acesso público externo.
3. No menu Settings > Variables and Secrets do Space, adicione as variáveis de ambiente:
   • OPENAI_BASE_URL: https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1
   • OPENAI_API_KEY: hf_************************ (seu token de acesso gerado no Passo 2)
4. (Opcional) Configure MONGODB_URL caso deseje persistir os chats entre reinicializações do Space. Para testes individuais, o Chat UI utiliza um banco de dados local embutido automaticamente.
5. Reinicie o Space. O Chat UI consultará a rota /v1/models do seu endpoint e disponibilizará o modelo privado na interface.

Opção B: Deploy local ou corporativo (Node.js / Docker)

Caso queira executar a ferramenta na sua estação de trabalho ou em um cluster interno:

1. Clone o repositório do Chat UI:

   git clone https://github.com/huggingface/chat-ui.git
   cd chat-ui
   

2. Crie o arquivo .env.local:

   # Configuração do endpoint de inferência
   OPENAI_BASE_URL=https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1
   OPENAI_API_KEY=hf_seu_token_aqui
   
   # Banco de dados (opcional no desenvolvimento local; usa persistência em ./db se omitido)
   # MONGODB_URL=mongodb://localhost:27017
   

3. Se o seu endpoint não possuir suporte ao endpoint de descoberta /v1/models ou se você quiser travar o nome de exibição e parâmetros de geração, declare a variável JSON5 MODELS no .env.local:

   MODELS=`[
     {
       "id": "tgi",
       "name": "Modelo Privado Corporativo",
       "multimodal": false,
       "supportsTools": false,
       "parameters": {
         "temperature": 0.7,
         "max_tokens": 4096
       }
     }
   ]`
   

4. Instale as dependências e inicie o ambiente:

   npm install
   npm run dev -- --open
   

O navegador abrirá a interface em http://localhost:5173, conectada ao seu modelo privado com a mesma experiência do HuggingChat.

Teste de conectividade e validação

Antes de utilizar a interface web, valide a integridade do endpoint com uma chamada via curl:

curl -X POST "https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1/chat/completions" \
  -H "Authorization: Bearer hf_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello! Confirm endpoint readiness."}
    ],
    "max_tokens": 50
  }'

Se a requisição retornar um payload JSON contendo a mensagem gerada, seu endpoint e suas credenciais estão configurados com sucesso.

Recomendações e particularidades de produção

• Assistants públicos vs. Deploy dedicado: Criar um "Assistant" na interface pública hf.co/chat permite customizar prompts de sistema e carregar documentos para RAG, mas os modelos subjacentes continuam sendo os modelos públicos globais. Para isolamento completo dos pesos de rede e privacidade de dados, o auto-hospedagem do Chat UI com Inference Endpoints é o caminho obrigatório.
• Partida a frio (Scale-to-Zero): Se o endpoint estiver configurado para descer a 0 réplicas durante períodos de inatividade, o primeiro envio de mensagem a partir do Chat UI pode sofrer timeout enquanto a instância de GPU é iniciada. Em ambientes de trabalho diário, configure ao menos 1 réplica ativa permanente.
• Streaming de respostas: O Chat UI depende de Server-Sent Events (SSE) para exibir respostas em tempo real. Tanto o TGI quanto o vLLM suportam streaming nativamente; caso utilize um proxy reverso intermediário (como Nginx), certifique-se de desligar o buffer (proxy_buffering off;).

Referências

• Chat UI · Hugging Face
• Configuration Overview · Hugging Face
• Running Locally · Hugging Face
• Inference Endpoints · Hugging Face