Executando a Chat UI com ML Intern localmente

Este guia é para desenvolvedores que desejam executar o ML Intern em sua própria máquina, testar alterações nele ou implantá-lo em sua própria instância de interface de chat. Se você apenas deseja usar o ML Intern, consulte Começando com o ML Intern.

ML Intern é um modo integrado à interface de chat. Quando ativado, uma conversa:

• executa em um conjunto fixo de modelos com capacidade de ferramentas
• conecta-se ao servidor MCP do Hugging Face com o conjunto de ferramentas intern do Hub
• recebe ferramentas integradas extras: planejamento, pesquisa, arquivos de script versionados, sandboxes, painéis do Trackio, gr.Workflow Spaces e espera por Jobs
• carrega um orçamento de computação que o servidor aplica a cada Job e sandbox que ele inicia

Pré-requisitos

• Node.js 20 ou posterior, e um clone de huggingface/chat-ui com npm install executado.
• Uma conta da Hugging Face com créditos. As conversas do ML Intern que você executa localmente iniciam Jobs e sandboxes reais na sua conta.
• Um token de acesso do Hugging Face com permissão para chamar os Inference Providers. O Chat UI o usa para se comunicar com os modelos.
• Um aplicativo OAuth da Hugging Face (configurado na Etapa 1), para que você possa fazer login. O ML Intern executa suas ferramentas do Hub com o token do usuário conectado. Sem login, essas ferramentas são executadas de forma anônima e não podem iniciar Jobs nem gravar no Hub.

MongoDB é opcional. Se MONGODB_URL não estiver definido, o Chat UI inicia um banco de dados em memória e o persiste em ./db.

Etapa 1: Crie um aplicativo OAuth do Hugging Face

1. Acesse huggingface.co/settings/applications/new.

2. Defina o URI de redirecionamento como http://localhost:5173/login/callback.

3. Permita estes escopos:

   • openid, profile
   • inference-api
   • read-mcp
   • read-billing
   • jobs
   • gated-repos
   • contribute-repos (opcional)

   jobs é obrigatório: sem ele, todo envio de Job retorna 403. contribute-repos permite que o ML Intern faça deploy em Spaces, e ele só pode atualizar os Spaces que criou. gated-repos permite que o ML Intern baixe modelos e datasets com acesso restrito aos quais o usuário foi autorizado. read-billing lista as organizações e grupos de recursos para os quais um usuário pode emitir faturas.

4. Anote o ID do cliente e o segredo do aplicativo.

Etapa 2: Configure .env.local

Crie .env.local na raiz do repositório. Os valores padrão e a documentação completa de cada variável estão em .env.

# Models, through the Hugging Face router
OPENAI_BASE_URL=https://router.huggingface.co/v1
OPENAI_API_KEY=hf_***

# Sign in with Hugging Face (Step 1)
OPENID_CLIENT_ID=<client id>
OPENID_CLIENT_SECRET=<client secret>
OPENID_SCOPES="openid profile inference-api read-mcp read-billing contribute-repos gated-repos jobs"
# Send the signed-in user's token to the Hugging Face MCP server
MCP_FORWARD_HF_USER_TOKEN=true

# Compile ML Intern in
ML_ASSISTANT_MODE=true
# Models ML Intern may run on; the first entry is the default
ML_ASSISTANT_MODELS=[{"id":"zai-org/GLM-5.3-Flash","provider":"together"},{"id":"moonshotai/Kimi-K3","provider":"baseten"}]

# Optional: HuggingChat-only UI, including the billing picker in Settings
PUBLIC_APP_ASSETS=huggingchat
# Optional: a GitHub token with no scopes, to raise the rate limit of the
# tools that read example scripts from public repositories
GITHUB_TOKEN=

Observações:

• ML_ASSISTANT_MODE é uma flag de compilação. O Vite a compila no bundle, portanto, um build implantado ou inclui o ML Intern ou não pode ativá-lo. Após alterá-la, reinicie o servidor de desenvolvimento.
• ML_ASSISTANT_MODELS é um array JSON5. Cada entrada precisa de um id que exista no catálogo de modelos do roteador e de um provider; o alias do roteador não é aceito. Um objeto opcional parameters é mesclado sobre o da entrada do catálogo. No roteador do Hugging Face, as conversas são fixadas nesse provedor, independentemente da preferência de provedor do próprio usuário. Em outros endpoints compatíveis com a OpenAI, essa fixação não é aplicada. Se a lista estiver vazia, o interruptor do ML Intern fica oculto e o modo se recusa a iniciar uma conversa.
  • Em relação ao roteador do Hugging Face, as conversas são fixadas naquele provedor, independentemente da preferência de provedor do próprio usuário.
  • Em relação a outros endpoints compatíveis com a OpenAI, o pin não é aplicado.
  • Se a lista estiver vazia, o interruptor do ML Intern fica oculto e o modo se recusa a iniciar uma conversa.
• Faturamento. Sem PUBLIC_APP_ASSETS=huggingchat, não há seletor de faturamento e os Jobs são faturados ao usuário conectado.

Etapa 3: Execute

npm run dev

Abra http://localhost:5173/?mode=ml-intern e faça login. O parâmetro ?mode=ml-intern ativa o modo (você também pode usar o interruptor abaixo da caixa de mensagem) e ele permanece na URL, de modo que um recarregamento mantém você no modo.

Toda conversa com o ML Intern começa com um orçamento de computação de $0, portanto, nenhum Job ou sandbox pode ser iniciado até que você defina um. Defina-o na barra de status acima da caixa de mensagem e mantenha-o baixo enquanto você experimenta.

Escolhendo modelos

O ML Intern executa loops longos de chamadas de ferramentas, muitas vezes com centenas de milhares de tokens de contexto. Nem todo modelo ou provedor lida com isso de forma confiável, motivo pelo qual cada entrada em ML_ASSISTANT_MODELS fixa um provedor. Para verificar um modelo e um provedor antes de adicioná-los, execute o script de sondagem. Ele reproduz um histórico no estilo ML Intern em tamanhos grandes de contexto e avalia como o stream termina:

npm run probe-model -- --model zai-org/GLM-5.3-Flash --provider together
npm run probe-model -- --model moonshotai/Kimi-K3 --suite quick

O cabeçalho de scripts/probe-model.ts documenta as suítes, tamanhos e vereditos.

Interruptores de recursos

Várias partes do ML Intern possuem interruptores de desligamento. Cada um deles está ativado, a menos que seja definido como false, e cada um é documentado em .env:

Onde o código está

Testes

Execute os testes unitários das partes que você alterou, por exemplo:

npx vitest run src/lib/server/mlRegistry
npx vitest run src/lib/server/textGeneration/builtinTools

npm run test executa tudo, e npm run test:e2e executa a suíte do Playwright. A suíte e2e usa um LLM mock e servidores MCP mock, portanto não precisa de chaves e não inicia nada no Hugging Face. É necessário Node.js 22.6 ou posterior.

Solução de problemas

• No alternador do ML Intern. Verifique se ML_ASSISTANT_MODE=true e ML_ASSISTANT_MODELS estão definidos e reinicie o servidor de desenvolvimento. O alternador só aparece em uma conversa vazia.
• Jobs fail with 403. The OAuth app or OPENID_SCOPES is missing jobs. Sign out and back in after adding it, so your token carries the new scope.
• Downloads de um repositório com controle de acesso falham com 403 após aceitar o controle de acesso. O aplicativo OAuth ou OPENID_SCOPES está sem gated-repos. O Hub ainda fornece os metadados e o README do repositório sem ele, o que faz parecer que o controle de acesso não foi aceito. Faça logout e login novamente após adicioná-lo.
• O ML Intern não consegue usar as ferramentas do Hub ou age de forma anônima. Verifique se você está conectado e se MCP_FORWARD_HF_USER_TOKEN=true está definido. Verifique também quais ferramentas estão habilitadas nas suas configurações do MCP do Hugging Face.
• Toda inicialização é recusada. O orçamento de computação da conversa ainda é $0. Defina-o a partir da barra de status.
• Os redirecionamentos de login falham. A URI de redirecionamento do aplicativo OAuth deve corresponder exatamente a http://localhost:5173/login/callback, incluindo a porta.