ForgeLM/docs/api/overview.md

Visao geral da API e backend

O backend do ForgeLM e um servidor HTTP local escrito em Rust, montado sobre Axum e conectado a uma engine de inferencia em inference-core.

Componentes principais

• crates/inference-server - inicializacao do servidor, leitura de configuracao por variaveis de ambiente e roteamento HTTP
• crates/api-contracts - tipos de request/response para chat, health, models e erros
• crates/inference-core - engine, sessoes, perfis de runtime e sampler
• crates/metrics - contadores de throughput e metricas de geracao

Endpoints publicos

Hoje o servidor expoe:

• GET /health
• GET /v1/models
• POST /v1/chat/completions

Essa superficie e pequena de proposito: o foco atual do projeto esta em chat local, descoberta de modelos e integracao com o runtime manager do app.

Inicializacao do servidor

O binario principal do backend esta em crates/inference-server/src/main.rs.

Na inicializacao, o servidor:

1. configura tracing/logs
2. le variaveis de ambiente como LOCALLLM_MODEL, LOCALLLM_PROFILE, LOCALLLM_ADDR, LOCALLLM_GPU_LAYERS e LOCALLLM_CTX
3. cria a configuracao da engine a partir do perfil selecionado
4. carrega e aquece o modelo (warmup())
5. monta o router com CORS e estado compartilhado
6. faz bind no endereco configurado e serve as rotas HTTP

Perfil de runtime

Os perfis atuais ficam em crates/inference-core/src/profile.rs:

• Turbo4B - foco em throughput, contexto moderado e uso de GPU agressivo
• Balanced9B - equilibrio entre qualidade e custo
• CpuFallback - fallback para maquinas sem GPU

Esses perfis definem defaults como n_gpu_layers, n_ctx, n_batch, n_ubatch, flash_attn e n_threads.

Auth e CORS

A configuracao de compatibilidade HTTP mora em crates/inference-server/src/compat.rs.

• auth e opcional; se LOCALLLM_API_KEY nao estiver configurada, a API aceita requests sem chave
• GET /health nao passa por verificacao de auth
• GET /v1/models e POST /v1/chat/completions passam por authorize_request()
• CORS aceita * por default ou uma lista configuravel por LOCALLLM_CORS_ORIGINS

Cabecalhos aceitos para auth:

• cabecalho configurado em LOCALLLM_AUTH_HEADER (default: authorization)
• Authorization
• x-api-key

Se LOCALLLM_AUTH_SCHEME estiver configurado, o backend tenta remover esse prefixo antes de comparar a chave.

Catalogo de modelos

O backend monta um catalogo de modelos em memoria a partir do nome canonico do modelo carregado e de aliases opcionais configurados por LOCALLLM_MODEL_ALIASES.

Regras importantes:

• o modelo carregado vira o ID canonico principal
• aliases adicionais podem apontar para o mesmo root
• local-model e default entram como aliases comuns quando possivel
• GET /v1/models retorna tanto o canonico quanto os aliases conhecidos

Chat completions

O endpoint de chat aceita mensagens em formato semelhante ao da OpenAI, com suporte para:

• roles system, developer, user, assistant e tool
• stream: true|false
• stop como string unica, array de strings ou null
• response_format
• tools e tool_choice
• stream_options.include_usage

O servidor, porem, continua com escopo limitado. Alguns campos sao aceitos por compatibilidade de contrato, mas isso nao significa paridade total com a plataforma OpenAI.

Streaming

No modo stream, o backend usa SSE e envia chunks no formato chat.completion.chunk.

Dois modos de streaming existem internamente:

• LiveTokens - emite tokens incrementais quando o fluxo suporta token streaming
• Buffered - produz a resposta inteira e a entrega em blocos compativeis

O chunk final pode incluir usage quando stream_options.include_usage=true.

Erros e validacao

Os erros seguem ErrorResponse { error: ApiError } com:

• message
• type
• param opcional
• code opcional

Validacoes conhecidas:

• model inexistente retorna model_not_found
• messages vazia retorna empty_messages
• n != 1 retorna unsupported_value
• tools com tool calls desabilitadas retorna tool_calls_disabled

Limitacoes atuais

• nao ha endpoints publicos para embeddings, uploads, files ou responses API
• n diferente de 1 nao e suportado
• response_format e tool calling passam por compatibilidade de prompt/pos-processamento, nao por enforcement forte de decoder
• parallel_tool_calls existe no contrato, mas nao deve ser tratado como capacidade plena documentada
• GET /health e um health check operacional; nao e uma prova profunda de qualidade do modelo

Para referencia detalhada de requests e respostas, siga para endpoints.md e configuration.md.