colab-ai

🇺🇸 English version

IA local e gratuita no Google Colab (GPU T4) com Ollama, exposta via túnel ngrok e integrada ao opencode no PC. Sem servidor próprio, sem custo.

Índice

• Recursos
• Pré-requisitos
• Início rápido
• Estrutura do projeto
• Catálogo de modelos (T4 16GB)
• Scripts utilitários
• Problemas comuns
• Documentação completa
• Referências
• Como contribuir
• Licença

Recursos

• Custo zero: Colab gratuito + ngrok gratuito + Ollama open source.
• Modelos com tool-calling (Qwen3, Qwen2.5-Coder, Mistral Nemo, Llama 3.1), prontos para uso como agente.
• Assistente interativo (colab-ai.sh): conecta a URL, testa, troca de modelo e limpa tudo.
• URL rotativa sem complicação: quando o túnel free muda, atualize com um comando.
• Saída limpa: ao encerrar, remove a configuração e deixa o PC como antes.
• Teste de fumaça (smoke-check.sh) que valida bash, JSON e as células do notebook.

Pré-requisitos

• Conta Google (para o Colab).
• Conta + token ngrok (gratuito em dashboard.ngrok.com).
• opencode instalado no PC.
• Internet.

Limites do plano gratuito: o Colab desliga em torno de 12h e o túnel free troca a URL a cada execução. Basta ligar de novo.

Início rápido

Parte A — Ligar a IA no Colab (cerca de 10 min)

1. Abra colab.research.google.com e faça upload de notebooks/colab-ollama-universal-opencode.ipynb.
2. Menu: Ambiente de execução > Alterar tipo > GPU T4 > Salvar.
3. Na célula 2 (a única que precisa de edição), informe o token ngrok — via Secrets (NGROK_AUTHTOKEN, recomendado) ou pelo campo do formulário — e confira o modelo.
4. Rode as células em ordem e anote o ENDPOINT da célula 6, por exemplo https://XXXX.ngrok-free.dev.

Parte B — Ligar o opencode no PC (cerca de 2 min)

./colab-ai.sh
# opção 2: cole o ENDPOINT da célula 6
opencode --model colab-ollama/qwen3:8b

Estrutura do projeto

colab-ai/
├── LICENSE                              # licença MIT
├── colab-ai.sh                        # assistente interativo principal
├── notebooks/
│   ├── colab-ollama-universal-opencode.ipynb  # notebook principal
│   └── colab-ollama-ngrok-opencode.ipynb      # notebook antigo (mantido)
├── scripts/
│   ├── update-colab-url.sh            # atualiza o baseURL quando a URL muda
│   ├── reset-colab-opencode.sh        # desfaz a config e restaura o PC
│   └── smoke-check.sh                 # validação (bash + JSON + células)
├── docs/
│   └── RELATORIO_IA_COLAB.md          # guia completo, para replicar do zero
├── README.md                          # este arquivo (PT-BR)
└── README.en.md                       # intro + quickstart (EN)

Catálogo de modelos (T4 16GB)

Modelo	Peso	Contexto	Papel
qwen3:8b	~5 GB	32k	agente padrão (tools nativas Qwen3)
qwen3:8b-q8_0	~9 GB	32k	agente qualidade máxima
qwen2.5-coder:7b	~5 GB	32k	código leve
qwen2.5-coder:7b-instruct-q8_0	~8 GB	32k	código preciso
mistral-nemo:12b	~7 GB	16k	PT-BR + chat longo
mistral-nemo:12b-instruct-2407-q8_0	~13 GB	8k	experimental (VRAM no limite)
qwen3:14b	~9 GB	16k	upgrade (se o 8B passar nos testes)
llama3.1:8b	~5 GB	32k	fallback (tools validadas aqui)

Para trocar depois sem recriar o túnel: colab-ai.sh, opção 6 (catálogo + modelo livre, qualquer tag Ollama).

Scripts utilitários

./colab-ai.sh                         # menu interativo completo
./scripts/update-colab-url.sh <URL>   # atualiza só a URL (modelo preservado)
./scripts/reset-colab-opencode.sh     # limpa a config colab-ollama
./scripts/reset-colab-opencode.sh --dry-run  # mostra o que faria, sem alterar
./scripts/smoke-check.sh              # valida o projeto

Problemas comuns

Sintoma	Solução
Failed to fetch / 404	URL antiga: pegue a nova na célula 6 e atualize (opção 2)
model_not_found	o modelo da config precisa ser exatamente o da célula 2
401	baseURL deve terminar em /v1; mantenha "apiKey": "dummy" + auth.json
could not connect to ollama	rode a célula 4 antes da 5
ERR_NGROK_334 / 502 failed to start tunnel: already online	túnel antigo preso: rode a célula 6 de novo (ela limpa + retry); se persistir, dashboard.ngrok.com > Endpoints > Stop ou Desconectar e excluir o runtime
Muito lento / OOM	desça no catálogo (14B → 8B → 7B) ou reduza o contexto para 8192

Nota de segurança: a URL do túnel é pública, nunca a compartilhe. Prefira Colab Secrets a colar o token no código.

Documentação completa

Guia detalhado, em linguagem simples, para replicar do zero: docs/RELATORIO_IA_COLAB.md.

Referências

Inspirado no projeto enescingoz/colab-llm (por enescingoz), notebook que transforma o Colab em servidor Ollama via túnel. Ideias aproveitadas: pre-check de RAM, readiness gate tolerante (200/404 = vivo), KEEP_ALIVE=-1, modelo livre em texto livre e a inspiração Q8 (ex: maryasov/qwen2.5-coder-cline:7b-instruct-q8_0). Este projeto segue caminho próprio (túnel ngrok + integração com opencode via colab-ai.sh).

Como contribuir

1. Faça um fork e crie uma branch a partir da main.
2. Rode ./scripts/smoke-check.sh antes de commitar.
3. Não commite tokens, URLs de túnel reais nem dados pessoais.
4. Abra um pull request descrevendo o que mudou e como testar.

Licença

Este projeto é licenciado sob a MIT License.

Os pesos dos modelos (Qwen, Llama, Mistral, etc.), Ollama, ngrok, Google Colab e opencode possuem licenças/termos próprios e não são cobertos por esta licença.