Rodando projetos de Modelos Open-source localmente

Use esta página para rodar um projeto Modelos Open-source extraído no seu computador. O módulo tem dois tipos de projeto. Um roda um modelo de detecção de objetos dentro do seu navegador com Transformers.js e precisa de uma configuração adicionada antes de carregar. O outro é um pequeno servidor Express que passa sua pergunta para um modelo rodando no Ollama, e seu package.json precisa de um reparo. Nenhum dos dois precisa de uma chave de API.

O que você precisa primeiro

Instale uma versão LTS suportada do Node.js. Node 24 é recomendado e inclui npm. Se Node e npm são novos para você, Running the code locally mostra como instalar e verificar os dois.

Verifique que ambos os comandos funcionam. Seus números de versão podem ser diferentes:

$ node --version
v24.18.0
$ npm --version
11.18.0

O projeto do navegador também precisa de uma conexão com a internet na primeira vez que carrega, porque a página baixa cerca de 20 MB de arquivos de biblioteca e modelo.

O projeto Ollama também precisa do Ollama e seu modelo mistral, um download de cerca de 4,4 GB. Você começa esse download na seção Ollama abaixo.

JunoO que você precisa primeiro Instale Node.js LTS, que inclui npm, e verifique que node --version e npm --version imprimem uma versão.

Você não precisa de uma chave de API para nenhum dos projetos. Se index.js começa com import ollama, instale o app Ollama também.

JunoO que você precisa primeiro Ambos os projetos rodam o modelo no seu próprio computador, por isso não há chave. O projeto do navegador baixa seu modelo na aba; o projeto Ollama pede a um programa separado, Ollama, que mantém o modelo no seu disco.

JunoO que você precisa primeiro Os dois downloads diferem em duas ordens de magnitude: cerca de 10 MB de pesos quantizados para o modelo do navegador contra cerca de 4,4 GB para mistral, que também precisa de vários gigabytes de memória livre enquanto Ollama o executa.

Identifique o projeto que você extraiu

Abra um terminal na pasta extraída. É aquela que contém package.json e index.js:

$ cd path-to-your-extracted-project

Abra index.js e leia sua primeira linha. O projeto do navegador, AI Models In The Browser With Transformers.js, começa com:

import { pipeline } from 'https://cdn.jsdelivr.net/npm/@xenova/[email protected]'

O projeto Ollama, Download and Run AI Models on Your Computer with Ollama, começa com:

import ollama from "ollama";

O projeto do navegador também tem index.html e uma foto road.jpeg; o projeto Ollama não tem nenhum dos dois. Siga apenas a seção do projeto que você tem.

JunoIdentifique o projeto que você extraiu Abra index.js e veja a primeira linha. @xenova/transformers significa o projeto do navegador; ollama significa o projeto Ollama.

Depois pule para a seção desse projeto. As duas configurações não se misturam.

JunoIdentifique o projeto que você extraiu Ambos os arquivos package.json são idênticos exceto pelas linhas de nome e descrição: cada um começa com Vite. Isso é correto para a página do navegador e errado para o servidor Ollama, que é um programa Node sem página nenhuma.

JunoIdentifique o projeto que você extraiu O reparo para o projeto Ollama substitui Vite por node index.js. Aplicado ao projeto do navegador, Node para na primeira linha com ERR_UNSUPPORTED_ESM_URL_SCHEME, porque não consegue importar um módulo de um endereço https:.

Rode o projeto Transformers.js

Instale os pacotes:

$ npm install

npm termina informando quantos pacotes foram adicionados.

Antes de iniciar, altere uma linha em index.js. Quando a página carrega, Transformers.js primeiro procura pelos arquivos do modelo no mesmo servidor que a página, sob /models/. Vite responde qualquer endereço que não conhece com a própria página, então a biblioteca recebe HTML onde esperava as configurações do modelo, e a página fica em Loading model... indefinidamente. Uma configuração diz ao Transformers.js para pular essa verificação local e baixar o modelo diretamente do Hugging Face.

Altere a primeira linha de:

import { pipeline } from 'https://cdn.jsdelivr.net/npm/@xenova/[email protected]'

para estas duas linhas:

import { pipeline, env } from 'https://cdn.jsdelivr.net/npm/@xenova/[email protected]'
env.allowLocalModels = false

Inicie o servidor de desenvolvimento:

$ npm start

Vite pode primeiro imprimir um aviso que começa com (!) Your Vite config uses features. Isso não para o app. Abaixo dele, Vite imprime o endereço a abrir:

  VITE v8.3.4  ready in 99 ms

  ➜  Local:   http://localhost:5173/

Abra o endereço Local exato. A página mostra Loading model... acima de um botão Detect Objects acinzentado enquanto a biblioteca e o modelo baixam. Quando o status muda para Ready, selecione Detect Objects. Após alguns segundos (até cerca de vinte em uma máquina mais lenta) o status lê Done! e caixas rotuladas aparecem na foto, como bus: 99%, car: 97% e vários semáforos. Carregamentos posteriores são mais rápidos porque o navegador mantém os arquivos baixados.

Se o status ficar em Loading model... ou nunca aparecer, abra as ferramentas de desenvolvimento do navegador (F12, ou Cmd+Option+J no Chrome em um Mac) e leia a aba Console; a solução de problemas abaixo combina com cada mensagem. Um 404 vermelho para favicon.ico é inofensivo.

Pare o projeto com Ctrl+C.

JunoRode o projeto Transformers.js Rode npm install, adicione env e a linha env.allowLocalModels = false no topo de index.js, depois rode npm start e abra o endereço Local.

Aguarde Ready, depois selecione Detect Objects. Caixas com rótulos na foto significam que o modelo funciona.

JunoRode o projeto Transformers.js Vite serve apenas seus arquivos: index.html, index.js e a foto. A biblioteca vem de jsDelivr e o modelo de Hugging Face, ambos diretamente no navegador, que então roda a detecção ele mesmo na foto que Vite serviu.

JunoRode o projeto Transformers.jsenv.allowLocalModels está ativado por padrão em Transformers.js 2.8.0. O fallback de Vite responde /models/Xenova/yolos-tiny/config.json com 200 e index.html, então a biblioteca nunca vê um 404 que a enviaria para Hugging Face; em vez disso, falha ao analisar o HTML como JSON.

Conserte e rode o projeto Ollama

Instale o Ollama e abra-o. No macOS e Windows o app inicia o serviço local do Ollama; no Linux o instalador configura isso. Se os comandos ollama dizem que não conseguem se conectar, execute ollama serve em um terminal separado e deixe rodando.

Baixe o modelo que o código da lição pede. São cerca de 4,4 GB, então você pode fazer os edits abaixo em outro terminal enquanto baixa:

$ ollama pull mistral
$ ollama ls

O segundo comando deve listar mistral:latest.

Agora o projeto em si. Seu package.json foi gerado para uma página web Vite: npm start roda Vite e o único pacote listado é Vite. Mas index.js é um servidor Node que importa express e ollama. Como baixado, npm start inicia Vite, e o endereço que imprime mostra HTTP ERROR 404, porque não há página para servir.

Faça duas edições em package.json: adicione "type": "module" e altere o script start para node index.js. O topo do arquivo então lê:

{
  "name": "Scrim-s06c53f",
  "description": "https://scrimba.com/ai-engineer-path-c02v/~07uj",
  "type": "module",
  "scripts": {
    "start": "node index.js",
    "dev": "vite",

Deixe o resto do arquivo como está. "type": "module" diz ao Node que index.js usa import; sem isso, Node ainda roda o arquivo mas imprime um aviso MODULE_TYPELESS_PACKAGE_JSON primeiro.

Instale os dois pacotes que index.js importa, depois inicie o servidor:

$ npm install express ollama
$ npm start

O servidor imprime:

Server is running on port 3000

Abra http://localhost:3000/. A página deve dizer:

Ask something via the `?question=` parameter

Faça perguntas apenas depois que ollama pull terminar. Então faça uma pergunta ao modelo:

http://localhost:3000/?question=Why%20is%20the%20sky%20blue%3F

A resposta aparece como texto simples quando Mistral termina de escrevê-la. A primeira resposta é a mais lenta, porque Ollama carrega o modelo na memória primeiro; a página não mostra nada até então.

Pare o servidor com Ctrl+C. Ollama continua rodando em background até você sair do app ou parar ollama serve.

JunoConserte e rode o projeto Ollama Execute ollama pull mistral e mantenha Ollama aberto. Em package.json, adicione "type": "module" e altere o script start para node index.js.

Depois execute npm install express ollama e npm start, e abra o endereço da pergunta. Uma primeira resposta lenta é normal.

JunoConserte e rode o projeto Ollama Dois programas cooperam: seu servidor Express na porta 3000 recebe a pergunta, e o pacote ollama a envia para o serviço Ollama na porta 11434, que roda mistral. Express nunca inicia Ollama, então ambos devem estar rodando.

JunoConserte e rode o projeto Ollamanpm install express agora instala Express 5, que captura a chamada ollama.chat rejeitada na rota assíncrona e responde com uma página 500 em vez de travar. Seu callback app.listen também roda quando a porta está em uso, então a mensagem de início sozinha não prova que o servidor está escutando.

Solução de problemas

A página Transformers.js fica em Loading model... e o console diz Unexpected token '<', "<!DOCTYPE "... is not valid JSON: A linha env.allowLocalModels = false está faltando, ou env não está na importação. Adicione ambas como mostrado acima e recarregue a página.

A página mostra apenas um botão Detect Objects acinzentado sem status acima, e o console nomeia cdn.jsdelivr.net: A biblioteca não conseguiu baixar. Um bloqueador de conteúdo ou uma rede restrita é geralmente a causa; permita cdn.jsdelivr.net ou tente outra rede.

A página fica em Loading model... e o console diz Failed to fetch para huggingface.co: O modelo não conseguiu baixar. Permita huggingface.co em seu bloqueador de conteúdo ou rede, depois recarregue.

No projeto Ollama, npm start imprime VITE e seu endereço mostra HTTP ERROR 404: O script start ainda roda Vite. Altere para node index.js.

Node diz Cannot find package 'ollama' ou Cannot find package 'express': Execute npm install express ollama na pasta contendo package.json.

O endereço da pergunta mostra TypeError: fetch failed, e o terminal mostra ECONNREFUSED 127.0.0.1:11434: Express está rodando mas Ollama não está. Abra o app Ollama ou execute ollama serve, depois faça a pergunta novamente.

O endereço da pergunta mostra um erro dizendo que o modelo mistral não foi encontrado: Ollama está rodando sem o modelo. Execute ollama pull mistral e aguarde terminar.

npm start imprime Server is running on port 3000 e depois retorna ao prompt: Outro programa já usa a porta 3000. Pare-o, ou altere a constante port em index.js e abra o endereço correspondente.

JunoSolução de problemas Para o projeto do navegador, leia a primeira linha vermelha no Console além de favicon.ico. Para o projeto Ollama, leia o que o endereço da pergunta mostra e o que o terminal imprimiu. Depois combine com um título em negrito acima.

JunoSolução de problemas O projeto do navegador falha na ordem que carrega: a biblioteca de jsDelivr, depois os arquivos do modelo, depois o modelo. O projeto Ollama falha na ordem que uma pergunta viaja: npm start, Express, o serviço Ollama, o modelo.

JunoSolução de problemasfetch failed com ECONNREFUSED significa que nada está escutando na 11434, então a requisição nunca chegou ao Ollama. Um erro do próprio Ollama, como um modelo faltando, significa que a conexão funcionou e o serviço respondeu.