Initial ForgeLM import
This commit is contained in:
Evandro Fonseca Junior committed
commit
a392b9dc60
4296 files changed
+1212675
No files matched your search
@@ -0,0 +1,100 @@
|
||||
# Comandos backend do app desktop
|
||||
|
||||
O backend Tauri exposto ao frontend vive principalmente em `tauri-app/src-tauri/src/lib.rs`.
|
||||
|
||||
Esta pagina documenta os comandos que o frontend usa para runtime, modelos e diagnostico.
|
||||
|
||||
## Runtime manager
|
||||
|
||||
### `bootstrap_runtime_command`
|
||||
|
||||
Carrega a configuracao persistida, reconstrui o snapshot do runtime e pode iniciar o runtime local automaticamente quando a politica e `on_app_launch` e o modo e `local`.
|
||||
|
||||
### `get_runtime_snapshot_command`
|
||||
|
||||
Retorna o `RuntimeSnapshot` atual com:
|
||||
|
||||
- `status`
|
||||
- `ready`
|
||||
- `process_running`
|
||||
- `resolved_url`
|
||||
- `binary_path`
|
||||
- `last_error`
|
||||
- `config`
|
||||
|
||||
### `save_runtime_config_command_handler`
|
||||
|
||||
Persiste `RuntimeConfig` e atualiza o estado backend usado pelo runtime manager.
|
||||
|
||||
Importante:
|
||||
|
||||
- se o processo local estiver rodando e a mudanca exigir restart, o backend pode recusar a alteracao com erro `restart_required`
|
||||
|
||||
### `start_runtime_command`
|
||||
|
||||
Inicia o runtime local usando a configuracao atualmente salva no backend Tauri.
|
||||
|
||||
### `stop_runtime_command`
|
||||
|
||||
Para o runtime local e atualiza o snapshot.
|
||||
|
||||
## GPU e modelos
|
||||
|
||||
### `query_gpu`
|
||||
|
||||
Usa `nvidia-smi` para detectar GPU NVIDIA e sugerir `recommended_layers`.
|
||||
|
||||
### `scan_models(dir)`
|
||||
|
||||
Escaneia um diretorio em busca de arquivos `.gguf`.
|
||||
|
||||
### `pick_models_dir`
|
||||
|
||||
Abre seletor nativo de pasta e devolve o diretorio escolhido junto com os modelos encontrados.
|
||||
|
||||
### `pick_model_files`
|
||||
|
||||
Abre seletor nativo de arquivos para escolher um ou mais `.gguf`.
|
||||
|
||||
### `import_model(src_path, dest_dir)`
|
||||
|
||||
Copia um arquivo `.gguf` para um diretorio de modelos.
|
||||
|
||||
## Configuracao e paths
|
||||
|
||||
### `find_server_binary`
|
||||
|
||||
Resolve o caminho do binario `localllm` para diagnostico e start local.
|
||||
|
||||
### `get_app_data_dir`
|
||||
|
||||
Retorna o diretorio de dados do app.
|
||||
|
||||
O backend desktop agora expoe apenas a superficie unificada do runtime manager para configuracao e ciclo de vida.
|
||||
|
||||
## Tipos principais
|
||||
|
||||
### `RuntimeConfig`
|
||||
|
||||
Campos relevantes:
|
||||
|
||||
- `connection_mode`
|
||||
- `start_policy`
|
||||
- `server_url`
|
||||
- `api_key`
|
||||
- `model_path`
|
||||
- `models_dir`
|
||||
- `addr`
|
||||
- `gpu_layers`
|
||||
- `ctx_size`
|
||||
- `extra_model_paths`
|
||||
|
||||
### `RuntimeSnapshot`
|
||||
|
||||
Representa o estado serializado usado pelo frontend para desenhar o runtime card, drawer e logica de start/stop.
|
||||
|
||||
## Observacoes importantes
|
||||
|
||||
- o backend Tauri e a source of truth da configuracao persistida do runtime do app
|
||||
- o frontend usa `useRuntimeManager()` para consumir essa superficie de comandos
|
||||
- readiness do runtime local depende de `GET /health`, nao apenas de socket aberto
|
||||
@@ -0,0 +1,114 @@
|
||||
# Visao geral do app desktop
|
||||
|
||||
O app desktop do ForgeLM vive em `tauri-app/` e combina:
|
||||
|
||||
- frontend React/Vite
|
||||
- backend Tauri em Rust
|
||||
- runtime manager para API local/remota
|
||||
- chat persistente com banco local em memoria exportado para `localStorage`
|
||||
|
||||
## Funcao do app
|
||||
|
||||
O app foi desenhado para ser a interface principal de uso do runtime local. Ele permite:
|
||||
|
||||
- iniciar ou parar a API local quando o modo e `local`
|
||||
- apontar para uma API existente quando o modo e `remote`
|
||||
- escolher/importar modelos `.gguf`
|
||||
- conversar com o backend via `POST /v1/chat/completions`
|
||||
- persistir historico de chats e mensagens
|
||||
- separar trechos de reasoning (`<think>...</think>`) da resposta final no frontend
|
||||
|
||||
## Arquitetura em alto nivel
|
||||
|
||||
### Frontend
|
||||
|
||||
Arquivos principais:
|
||||
|
||||
- `src/App.tsx` - shell principal do app
|
||||
- `src/components/Sidebar.tsx` - sidebar com runtime card, seletor de modelo e lista de chats
|
||||
- `src/components/ChatView.tsx` - fluxo de chat, streaming, memoria e persistencia de mensagens
|
||||
- `src/features/runtime/*` - runtime manager unificado
|
||||
|
||||
### Backend Tauri
|
||||
|
||||
Arquivos principais:
|
||||
|
||||
- `src-tauri/src/lib.rs` - comandos Tauri expostos ao frontend
|
||||
- `src-tauri/src/runtime/*` - estado, config, spawn, health probe e snapshot do runtime local
|
||||
|
||||
## Runtime manager
|
||||
|
||||
O runtime manager e a peca central do app.
|
||||
|
||||
Estados principais:
|
||||
|
||||
- `stopped`
|
||||
- `starting`
|
||||
- `ready`
|
||||
- `degraded`
|
||||
- `stopping`
|
||||
- `error`
|
||||
|
||||
Modos de conexao:
|
||||
|
||||
- `local` - o app controla o processo do backend
|
||||
- `remote` - o app so consome uma API externa ja existente
|
||||
|
||||
O frontend usa `useRuntimeManager()` como source of truth para:
|
||||
|
||||
- snapshot atual do runtime
|
||||
- URL resolvida da API
|
||||
- save de config
|
||||
- start/stop do runtime local
|
||||
|
||||
## Selecao de modelos
|
||||
|
||||
O app carrega modelos via `GET /v1/models` usando `useModels()`.
|
||||
|
||||
Comportamentos importantes:
|
||||
|
||||
- se nao houver endpoint configurado, o estado fica em erro e a lista e limpa
|
||||
- se a API responder sem modelos, o model selector fica vazio
|
||||
- se o modelo antes selecionado nao existir mais na lista, o app seleciona o primeiro disponivel
|
||||
|
||||
## Persistencia local
|
||||
|
||||
O chat usa `sql.js` com schema local gerenciado por `src/lib/db.ts`.
|
||||
|
||||
Tabelas principais:
|
||||
|
||||
- `chats`
|
||||
- `messages`
|
||||
|
||||
Campos persistidos por mensagem incluem:
|
||||
|
||||
- `role`
|
||||
- `content`
|
||||
- `reasoning_content`
|
||||
- `prompt_tokens`
|
||||
- `completion_tokens`
|
||||
- `total_tokens`
|
||||
- `tokens_per_second`
|
||||
|
||||
Importante: isso nao e um banco nativo do sistema operacional. O app injeta `sql.js` por CDN e persiste a exportacao do banco em `localStorage`.
|
||||
|
||||
## Chat e streaming
|
||||
|
||||
`ChatView.tsx` envia requests para `POST /v1/chat/completions`.
|
||||
|
||||
Recursos atuais:
|
||||
|
||||
- streaming opcional
|
||||
- memoria opcional com ate 20 mensagens recentes
|
||||
- separacao visual de reasoning (`<think>...</think>`) no frontend
|
||||
- contadores de tokens por mensagem e por chat
|
||||
- edicao, reenvio e exclusao de mensagens
|
||||
|
||||
## Limitacoes atuais
|
||||
|
||||
- o app depende de um binario `localllm` acessivel quando o modo local e usado
|
||||
- o fallback browser-only nao substitui os recursos desktop do Tauri
|
||||
- o chat depende da pequena API HTTP atual; o app nao expoe magica propria fora dela
|
||||
- o runtime manager faz polling periodico do snapshot; ele nao usa ainda um fluxo completo de eventos push
|
||||
|
||||
Para uso pratico, siga para `user-guide.md`.
|
||||
@@ -0,0 +1,135 @@
|
||||
# Guia de uso do app desktop
|
||||
|
||||
Este guia cobre o fluxo de uso do app Tauri no estado atual do projeto.
|
||||
|
||||
## 1. Abrir o app
|
||||
|
||||
Em desenvolvimento:
|
||||
|
||||
```bash
|
||||
cd tauri-app
|
||||
npm install
|
||||
npm run tauri dev
|
||||
```
|
||||
|
||||
## 2. Entender os modos de conexao
|
||||
|
||||
O Runtime Manager suporta dois modos.
|
||||
|
||||
### Local API
|
||||
|
||||
Use quando o app deve subir e controlar o backend local.
|
||||
|
||||
Voce configura:
|
||||
|
||||
- pasta de modelos
|
||||
- modelo selecionado
|
||||
- endereco de bind (`addr`)
|
||||
- numero de GPU layers
|
||||
- contexto (`ctx_size`)
|
||||
- politica de auto-start
|
||||
|
||||
### Remote API
|
||||
|
||||
Use quando a API ja esta rodando em outro lugar.
|
||||
|
||||
Voce configura:
|
||||
|
||||
- `server_url`
|
||||
- `api_key` opcional
|
||||
|
||||
Nesse modo o app nao tenta iniciar/parar o backend local.
|
||||
|
||||
## 3. Configurar o runtime local
|
||||
|
||||
Na sidebar, abra `Manage` ou o icone de configuracao.
|
||||
|
||||
Fluxo recomendado:
|
||||
|
||||
1. deixe `Connection mode` em `Local API`
|
||||
2. escolha a pasta de modelos com `Browse`, ou adicione arquivos individuais com `Add files`
|
||||
3. selecione o modelo desejado
|
||||
4. ajuste `Listen address`, `GPU layers` e `Context size` se necessario
|
||||
5. use `Save settings` ou `Save and start local API`
|
||||
|
||||
Observacoes:
|
||||
|
||||
- o app tenta descobrir o binario do backend automaticamente
|
||||
- se uma revarredura da pasta vier vazia, o app preserva o `model_path` salvo em vez de limpar a selecao imediatamente
|
||||
- o start local so fica disponivel quando existe binario e modelo selecionado
|
||||
|
||||
## 4. Configurar API remota
|
||||
|
||||
1. abra o Runtime Manager
|
||||
2. mude para `Remote API`
|
||||
3. preencha `Remote server URL`
|
||||
4. opcionalmente, preencha `API key`
|
||||
5. salve a configuracao
|
||||
|
||||
Depois disso, o app passa a usar essa URL para `GET /v1/models` e `POST /v1/chat/completions`.
|
||||
|
||||
## 5. Selecionar modelos no app
|
||||
|
||||
Quando a API estiver acessivel:
|
||||
|
||||
- o seletor de modelo na sidebar sera preenchido por `GET /v1/models`
|
||||
- o app tenta manter a selecao atual quando possivel
|
||||
- se o modelo sumir da API, o app troca para o primeiro disponivel
|
||||
|
||||
## 6. Conversar no chat
|
||||
|
||||
O fluxo principal fica em `ChatView`.
|
||||
|
||||
Recursos de uso:
|
||||
|
||||
- streaming on/off
|
||||
- memory on/off
|
||||
- historico persistente por conversa
|
||||
- edicao e reenvio de mensagens do usuario
|
||||
- edicao de resposta do assistente
|
||||
- copia de conteudo/markdown/codigo
|
||||
|
||||
## 7. Thinking e tokens
|
||||
|
||||
Quando a resposta inclui blocos `<think>...</think>`:
|
||||
|
||||
- o app separa esse conteudo como `Thinking`
|
||||
- o painel de thinking pode ser expandido/recolhido
|
||||
- a resposta final aparece separadamente do thinking
|
||||
|
||||
Metricas visiveis:
|
||||
|
||||
- tokens enviados (`Sent`)
|
||||
- tokens gerados (`Generated`)
|
||||
- total por mensagem e por chat
|
||||
- `tok/s` quando informado pela API
|
||||
|
||||
## 8. Troubleshooting rapido
|
||||
|
||||
### "Configure a local or remote API before sending messages"
|
||||
|
||||
O app esta sem endpoint valido. Abra o Runtime Manager e configure modo local ou remoto.
|
||||
|
||||
### Nenhum modelo aparece
|
||||
|
||||
- confirme que a API esta acessivel
|
||||
- use o botao de refresh da sidebar
|
||||
- no modo local, confirme que o modelo salvo foi iniciado corretamente
|
||||
|
||||
### O start local esta desabilitado
|
||||
|
||||
Verifique:
|
||||
|
||||
- se o binario do backend foi encontrado
|
||||
- se um modelo esta salvo/selecionado
|
||||
- se voce nao esta em modo remoto
|
||||
|
||||
### O runtime sobe mas nunca fica pronto
|
||||
|
||||
O app usa readiness por `GET /health`. Se a API local nao passar nesse check dentro do timeout, o runtime manager marca erro.
|
||||
|
||||
## 9. Persistencia e cuidado com dados
|
||||
|
||||
- chats e mensagens ficam no armazenamento local do app/frontend
|
||||
- o app nao implementa sincronizacao remota de conversas
|
||||
- apagar dados do navegador/webview pode remover o historico local
|
||||
Reference in new issue
Block a user