141 lines
3.9 KiB
Markdown
141 lines
3.9 KiB
Markdown
# Arquitetura do projeto
|
|
|
|
Esta pagina resume a arquitetura atual do workspace ForgeLM para quem vai manter ou evoluir o sistema.
|
|
|
|
## Mapa do workspace Rust
|
|
|
|
O `Cargo.toml` raiz declara os membros:
|
|
|
|
- `crates/llama-sys`
|
|
- `crates/inference-core`
|
|
- `crates/inference-server`
|
|
- `crates/api-contracts`
|
|
- `crates/metrics`
|
|
- `crates/localllm-cli`
|
|
|
|
O app desktop fica fora do workspace Rust principal, em `tauri-app/`, mas conversa diretamente com esse ecossistema por binario, comandos Tauri e HTTP local.
|
|
|
|
## Responsabilidade de cada modulo
|
|
|
|
### `api-contracts`
|
|
|
|
Tipos compartilhados para:
|
|
|
|
- chat completions
|
|
- model listing
|
|
- health
|
|
- payloads de erro
|
|
|
|
Serve como contrato comum entre `inference-server` e consumidores da API.
|
|
|
|
### `inference-core`
|
|
|
|
Responsavel pela engine de inferencia local:
|
|
|
|
- carga do modelo
|
|
- sessao de inferencia
|
|
- sampler
|
|
- perfis de runtime
|
|
|
|
### `inference-server`
|
|
|
|
Camada HTTP baseada em Axum:
|
|
|
|
- leitura de env vars
|
|
- montagem de `ServerConfig`
|
|
- auth, CORS e aliases de modelos
|
|
- endpoints `/health`, `/v1/models`, `/v1/chat/completions`
|
|
|
|
### `localllm-cli`
|
|
|
|
CLI de operacao e automacao. Hoje ela ja tem uma superficie ampla, mas a parte com execucao real comprovada contra o backend publico atual esta mais concentrada em `status`, `models list` e `bench throughput`.
|
|
|
|
### `metrics`
|
|
|
|
Contadores e registros de throughput/token usage usados no backend.
|
|
|
|
### `llama-sys`
|
|
|
|
Bindings e integracao de baixo nivel com a stack de inferencia.
|
|
|
|
### `tauri-app`
|
|
|
|
App desktop composto por:
|
|
|
|
- frontend React/Vite
|
|
- backend Tauri em Rust
|
|
- runtime manager local/remoto
|
|
- chat persistente com `sql.js`
|
|
|
|
## Fluxo entre API, CLI e app
|
|
|
|
## 1. Backend HTTP
|
|
|
|
`inference-server` sobe, carrega o modelo e expoe a API HTTP.
|
|
|
|
## 2. CLI
|
|
|
|
A CLI pode falar com a API HTTP por URL configurada via `--server` e `--api-key`.
|
|
|
|
## 3. App desktop
|
|
|
|
O app usa duas camadas:
|
|
|
|
- backend Tauri para gerenciar processo, configuracao e integracoes locais
|
|
- frontend React para runtime manager, selecao de modelos e chat
|
|
|
|
Quando em modo local, o app inicia/para o backend por meio do runtime manager do Tauri. Quando em modo remoto, o app apenas consome uma URL externa.
|
|
|
|
## Runtime manager do app
|
|
|
|
Arquivos centrais:
|
|
|
|
- `tauri-app/src/features/runtime/useRuntimeManager.ts`
|
|
- `tauri-app/src/features/runtime/types.ts`
|
|
- `tauri-app/src/features/runtime/components/RuntimeStatusCard.tsx`
|
|
- `tauri-app/src/features/runtime/components/RuntimeSettingsDrawer.tsx`
|
|
- `tauri-app/src-tauri/src/runtime/*`
|
|
|
|
Conceitos importantes:
|
|
|
|
- `RuntimeConfig` e persistido no backend Tauri
|
|
- `RuntimeSnapshot` e consumido pelo frontend
|
|
- modo `local` e `remote` compartilham a mesma superficie de configuracao
|
|
- readiness do modo local depende de `GET /health`
|
|
|
|
## Chat e persistencia
|
|
|
|
Arquivos centrais:
|
|
|
|
- `tauri-app/src/components/ChatView.tsx`
|
|
- `tauri-app/src/components/MessageBubble.tsx`
|
|
- `tauri-app/src/lib/db.ts`
|
|
- `tauri-app/src/lib/chat.ts`
|
|
|
|
Caracteristicas importantes:
|
|
|
|
- conversas e mensagens ficam em `sql.js` persistido em `localStorage`
|
|
- o app separa reasoning de resposta final ao analisar `<think>...</think>`
|
|
- tokens por mensagem e por chat ficam persistidos
|
|
- memoria do chat envia ate 20 mensagens recentes quando habilitada
|
|
|
|
## Limites e fronteiras atuais
|
|
|
|
- a API publica ainda e pequena; nao documente ou desenvolva assumindo uma plataforma completa estilo OpenAI
|
|
- a CLI esta mais avancada no parser/superficie do que nas capacidades HTTP publicas realmente disponiveis
|
|
- o app desktop e a interface mais rica do projeto hoje, mas ainda depende do backend HTTP local/remoto para inferencia real
|
|
|
|
## Termos recomendados
|
|
|
|
- `runtime` - processo + configuracao + estado operacional do backend local
|
|
- `API local` - o `inference-server` rodando na maquina do usuario
|
|
- `modo local` - o app controla o processo
|
|
- `modo remoto` - o app consome uma API externa
|
|
- `snapshot de runtime` - estado serializado do runtime usado pelo frontend
|
|
|
|
## Leitura complementar
|
|
|
|
- `../api/overview.md`
|
|
- `../cli/overview.md`
|
|
- `../app/overview.md`
|