Executar projetos de modelos open-source localmente

Use esta página para executar qualquer um dos projetos de modelos open-source extraídos. Um carrega um modelo Transformers.js no seu navegador; o outro executa um servidor Express que chama Ollama no seu computador. Identifique qual projeto você tem e siga apenas essa configuração.

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 novidade para você, Executar o código localmente orienta você sobre como instalar e verificar ambos.

O projeto Transformers.js precisa de um navegador atualizado, uma conexão com a internet para o download inicial da biblioteca e do modelo, e armazenamento e memória suficientes no navegador para o modelo. Não precisa de uma chave de API.

O projeto Ollama também precisa do Ollama, espaço em disco e memória suficientes para o modelo mistral, e seu serviço Ollama local em execução. Não precisa de uma conta de provedor ou chave de API.

JunoO que você precisa primeiro Instale Node.js LTS primeiro e depois escolha seu caminho: um navegador atualizado e uma conexão com a internet para Transformers.js, ou o app Ollama com seu serviço rodando para a lição Ollama. Nenhum deles precisa de uma chave de API, o que parecia bom demais para ser verdade na primeira vez que configurei um. Mas não é!

JunoO que você precisa primeiro Ambos os projetos executam o modelo no seu próprio hardware, então não há chave de provedor para configurar. Transformers.js puxa o modelo para a aba do navegador; a lição Ollama precisa do serviço Ollama separado instalado e em execução antes que seu servidor possa acessá-lo. Instale Node LTS de qualquer forma, porque npm orienta ambas as configurações.

JunoO que você precisa primeiro Dois caminhos de computação local, dois orçamentos de recursos. O caminho do navegador se apoia em ativos de biblioteca e modelo remotos mais cache, armazenamento e memória do navegador; o caminho Ollama precisa do serviço nativo, pesos baixados e capacidade suficiente da máquina para inferência. Verifique o hardware antes da lição, um hábito que adquiri depois de carregar um modelo em um laptop que não podia mantê-lo.

Identifique o projeto que você extraiu

Abra um terminal na pasta extraída contendo package.json:

$ cd path-to-your-downloaded-project

Se o nome da pasta não disser qual lição você extraiu, abra index.js. Uma importação express significa a lição Ollama, que precisa do conserto de pacote abaixo; uma importação Transformers.js significa o app do navegador, que executa como entregue.

JunoIdentifique o projeto que você extraiu Abra seu terminal bem ao lado de package.json, como você faria na cozinha antes de começar a cozinhar. Um projeto de modelo do navegador segue a seção Transformers.js; o servidor Express segue a seção Ollama. Uma vez executei uma configuração inteira uma pasta acima, então verifique onde você está primeiro.

JunoIdentifique o projeto que você extraiu Os dois downloads parecem iguais de fora, mas executam de forma diferente: o projeto de modelo do navegador começa com Vite, enquanto o projeto Ollama é um servidor Node que também precisa do serviço Ollama separado. Escolha a seção que corresponde à sua e siga apenas essa, porque os passos de configuração não se misturam.

JunoIdentifique o projeto que você extraiu Identifique o projeto pela evidência, não pelo nome da pasta: abra index.js. Uma importação express significa a lição Ollama e o conserto de pacote abaixo; uma importação Transformers.js significa o app do navegador Vite executa como entregue. Pulei essa verificação exatamente uma vez, e uma vez foi mais que o suficiente.

Execute o projeto Transformers.js

Use essas instruções para AI Models In The Browser With Transformers.js. Este projeto precisa de Node e npm para Vite.

Instale e inicie:

$ npm install
$ npm start

Abra a URL Local que Vite exibe, normalmente http://localhost:5173/. A página primeiro importa Transformers.js do jsDelivr e depois baixa o modelo de detecção de objetos Xenova/yolos-tiny. Aguarde até que seu status mude de Loading model... para Ready antes de selecionar Detect Objects.

O primeiro carregamento precisa de uma conexão com a internet e pode levar mais tempo do que uma página frontend comum; carregamentos posteriores vêm do cache do navegador. Se o status nunca atingir Ready, abra a aba DevTools Network: uma solicitação jsDelivr bloqueada aponta para um problema de CDN ou bloqueador de conteúdo, enquanto um arquivo de modelo crescendo lentamente significa que o download de pesos ainda está em andamento. Pare Vite com Ctrl+C.

Nenhuma credencial de provedor é necessária

O modelo é executado no seu navegador em vez de através de uma API de inferência hospedada. Não há arquivo .env ou chave de API para configurar nesta lição.

JunoExecute o projeto Transformers.js Execute npm install, depois npm start, abra a URL Local e aguarde o status atingir Ready antes de selecionar qualquer coisa. O primeiro download de modelo é como dia de mudança: lento uma vez, depois pronto. Eu costumava clicar cedo e assumir que tinha quebrado, então dê um tempo.

JunoExecute o projeto Transformers.js Três coisas carregam em ordem: Vite serve a página, jsDelivr fornece a biblioteca e os pesos do modelo baixam para o navegador para executar lá. Esse primeiro carregamento é limitado pela rede, então um status lento geralmente significa um download em andamento, não um bug. Aguarde Ready e depois detecte.

JunoExecute o projeto Transformers.js O primeiro carregamento é limitado pela rede; cada carregamento após isso sai do cache do navegador. Quando Ready nunca chega, a aba DevTools Network resolve: uma solicitação jsDelivr bloqueada é um problema de CDN ou bloqueador de conteúdo, enquanto um arquivo de modelo avançando aos poucos é uma paralisação de pesos. Verifico essa aba antes de culpar o modelo, uma lição que uma vez me custou uma hora.

Conserte e execute o projeto Ollama

Use essas instruções para Download and Run AI Models on Your Computer with Ollama. O ZIP exportado contém o código Node da lição, mas seu package.json gerado ainda descreve um projeto Vite. Não pode executar localmente sem um pequeno conserto de pacote.

Após instalar Ollama, certifique-se de que seu serviço local está em execução. Baixe o modelo nomeado pelo código da lição:

$ ollama pull mistral
$ ollama ls

O segundo comando deve listar mistral. Dependendo do seu sistema operacional, abrir o aplicativo Ollama inicia o serviço automaticamente. Se não fizer, execute ollama serve em um terminal separado e deixe em execução.

No projeto extraído, adicione "type": "module" como uma propriedade de nível superior de package.json, um irmão de "scripts":

{
  "type": "module",
  "scripts": {
    "start": "vite"
  }
}

Depois altere o script de início de:

"start": "vite"

para:

"start": "node index.js"

Instale as duas dependências importadas por index.js:

$ npm install express ollama
$ npm start

O servidor exibe:

Server is running on port 3000

Teste a rota sem invocar um modelo:

http://localhost:3000/

Deve pedir que você forneça um parâmetro question. Depois tente uma solicitação real de modelo local:

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

O servidor Express aguarda enquanto Ollama carrega o modelo e gera sua resposta. A primeira resposta pode ser notavelmente mais lenta. Pare Express com Ctrl+C. Pare um processo ollama serve iniciado separadamente com Ctrl+C quando não precisar mais dele.

Você não precisa de chave de API de provedor ou arquivo .env para nenhum dos projetos; os pesos do modelo e inferência permanecem na máquina rodando Ollama. Os projetos de modelo hospedado do curso funcionam de forma diferente: Executar Agents localmente mostra a configuração de chave e .env que eles precisam.

JunoConserte e execute o projeto Ollama Puxe o modelo mistral, mantenha Ollama em execução, depois conserte package.json: adicione o tipo de módulo e aponte o script de início para node index.js. Instale express e ollama, inicie o servidor e faça uma pergunta na porta 3000. Uma resposta lenta primeiro significa que o modelo está carregando, não que algo quebrou, o que gostaria que alguém tivesse me dito na primeira vez.

JunoConserte e execute o projeto Ollama Dois processos cooperam aqui: Ollama serve o modelo e Express expõe a rota da lição. O ZIP envia metadados de pacote com forma Vite, então adicione o tipo de módulo e reaponte o script de início para corresponder ao ponto de entrada Node, depois instale as duas importações. Se uma solicitação travá-la, verifique qual dos dois processos parou.

JunoConserte e execute o projeto Ollama A exportação descreve o tipo errado de app, então os edits de pacote são o conserto, não polimento: tipo de módulo ESM mais um script de início Node. Mesmo consertado, Express só responde se Ollama roda separadamente com mistral já puxado; o servidor nunca inicia o serviço de modelo para você. Espere que a primeira inferência seja a mais lenta enquanto os pesos carregam.

Solução de problemas

A página Transformers.js fica em Loading model...: Verifique o console do navegador e a conexão com a internet. Bloqueadores de conteúdo ou uma rede restrita podem bloquear jsDelivr ou o download do modelo. Tente um navegador atualizado com armazenamento e memória livres suficientes.

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

Node diz Cannot use import statement outside a module: Adicione "type": "module" ao package.json.

npm start inicia Vite ou reclama de um index.html faltando: Altere o script de início para node index.js. A lição Ollama é um servidor Node, não uma página Vite.

A rota não consegue se conectar a Ollama: Confirme que o aplicativo Ollama ou ollama serve está em execução, depois use ollama ls para confirmar que o modelo mistral está instalado.

A porta 3000 já está em uso: Pare o outro processo ou altere a constante port em index.js, reinicie Express e abra a URL correspondente.

JunoSolução de problemas Combine o conserto com o projeto: para Transformers.js, verifique a atividade de rede e Console do navegador, e para Ollama, verifique o conserto de pacote, o modelo instalado, o serviço em execução e a porta. A maioria dos erros aqui vem de uma etapa faltando, não de um computador quebrado. Digo isso como alguém que uma vez reinstalou Node por causa de um typo.

JunoSolução de problemas Descubra qual runtime falhou antes de mudar qualquer coisa: Vite e ativos do navegador pertencem ao projeto Transformers.js, enquanto Node, Express e o serviço Ollama pertencem ao outro. Leia o erro para ver qual mundo ele nomeia, depois execute a lista de verificação daquele projeto. Correções aplicadas ao projeto errado principalmente criam novos erros.

JunoSolução de problemas Para Transformers.js, a falha vive em downloads ou memória do navegador. Para Ollama, caminhe pela cadeia em ordem: Node aceita a sintaxe do módulo, Express possui a porta 3000, o serviço está em execução e mistral aparece em ollama ls. Sintomas posteriores geralmente são uma quebra anterior usando disfarce.