Minima

RAG local (on-premises) com servidor MCP.

GitHub
1k
Experimente este MCPPatrocinado

Documentação

MNMA Logo

Minima é um RAG open source em contêineres on-premises, com capacidade de integração com ChatGPT e MCP. Minima também pode ser usado como um RAG totalmente local ou com seu próprio LLM implantado.

O Minima atualmente suporta quatro modos:

  1. Instalação isolada (Ollama) – Opere totalmente on-premises com contêineres, livre de dependências externas como ChatGPT ou Claude. Todas as redes neurais (LLM, reranker, embedding) rodam na sua nuvem ou PC, garantindo que seus dados permaneçam seguros.

  2. LLM personalizado (API compatível com OpenAI) – Use seu próprio LLM implantado com API compatível com OpenAI (vLLM, servidor Ollama, TGI, etc.). O indexador roda localmente enquanto o LLM pode estar no seu servidor, nuvem ou máquina local. Não é necessário implantar Ollama, uso mais leve de recursos e controle total sobre sua infraestrutura de LLM.

  3. GPT personalizado – Consulte seus documentos locais usando o aplicativo ou web do ChatGPT com GPTs personalizados. O indexador roda na sua nuvem ou PC local, enquanto o LLM principal permanece o ChatGPT.

  4. Anthropic Claude – Use o aplicativo Anthropic Claude para consultar seus documentos locais. O indexador opera no seu PC local, enquanto o Anthropic Claude serve como LLM principal.

Executando como Contêineres

Início Rápido com run.sh

A maneira mais fácil de iniciar o Minima é usando o script run.sh:

./run.sh

Você verá as seguintes opções:

Select an option:
1) Fully Local Setup (Ollama)
2) Custom LLM (OpenAI-compatible API)
3) ChatGPT Integration
4) MCP usage
5) Quit

Comandos Manuais do Docker Compose

  1. Crie um arquivo .env no diretório raiz do projeto (onde você encontrará .env.sample). Coloque o .env na mesma pasta e copie todas as variáveis de ambiente do .env.sample para o .env.

  2. Certifique-se de que seu arquivo .env inclua as seguintes variáveis:

  • LOCAL_FILES_PATH
  • EMBEDDING_MODEL_ID
  • EMBEDDING_SIZE
  • OLLAMA_MODEL (somente para modo Ollama)
  • RERANKER_MODEL (somente para modo Ollama)
  • LLM_BASE_URL (somente para modo LLM personalizado)
  • LLM_MODEL (somente para modo LLM personalizado)
  • LLM_API_KEY (opcional para modo LLM personalizado)
  • USER_ID
    • - necessário para integração com ChatGPT, basta usar seu e-mail
  • PASSWORD
    • - necessário para integração com ChatGPT, basta usar qualquer senha

  1. Para instalação totalmente local, use: docker compose -f docker-compose-ollama.yml --env-file .env up --build.

  2. Para implantação de LLM personalizado (API compatível com OpenAI), use: docker compose -f docker-compose-custom-llm.yml --env-file .env up --build.

  3. Para instalação com ChatGPT habilitado, use: docker compose -f docker-compose-chatgpt.yml --env-file .env up --build.

  4. Para integração MCP (uso do aplicativo Anthropic Desktop): docker compose -f docker-compose-mcp.yml --env-file .env up --build.

  5. No caso de instalação com ChatGPT habilitado, copie o OTP do terminal onde você iniciou o docker e use Minima GPT

  6. Se você usar o Anthropic Claude, basta adicionar o seguinte ao /Library/Application\ Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
      "minima": {
        "command": "uv",
        "args": [
          "--directory",
          "/path_to_cloned_minima_project/mcp-server",
          "run",
          "minima"
        ]
      }
    }
  }

  1. Para usar a instalação totalmente local, vá para cd electron, depois execute npm install e npm start que iniciarão o aplicativo electron do Minima.

  2. Pergunte qualquer coisa, e você obterá respostas baseadas nos arquivos locais na pasta {LOCAL_FILES_PATH}.

Variáveis Explicadas

LOCAL_FILES_PATH: Especifique a pasta raiz para indexação (na sua nuvem ou PC local). A indexação é um processo recursivo, ou seja, todos os documentos dentro de subpastas desta pasta raiz também serão indexados. Tipos de arquivo suportados: .pdf, .xls, .docx, .txt, .md, .csv.

EMBEDDING_MODEL_ID: Especifique o modelo de embedding a ser usado. Atualmente, apenas modelos Sentence Transformer são suportados. Testes foram feitos com sentence-transformers/all-mpnet-base-v2, mas outros modelos Sentence Transformer podem ser usados.

EMBEDDING_SIZE: Defina a dimensão do embedding fornecida pelo modelo, que é necessária para configurar o armazenamento vetorial Qdrant. Certifique-se de que este valor corresponda ao tamanho real do embedding do EMBEDDING_MODEL_ID especificado.

OLLAMA_MODEL: Configure o modelo Ollama, use um ID disponível no site do Ollama. Por favor, use o modelo LLM aqui, não um embedding. Isso é necessário apenas ao usar Ollama (não é necessário ao usar LLM personalizado).

LLM_BASE_URL: (Opcional) URL base para seu endpoint de API LLM personalizado compatível com OpenAI. Quando definido, o Ollama não será usado e você não precisa implantá-lo.

LLM_MODEL: (Opcional) Nome do modelo para seu LLM personalizado. Necessário quando LLM_BASE_URL está definido.

LLM_API_KEY: (Opcional) Chave de API para seu LLM personalizado. Se seu LLM não exigir autenticação, você pode omitir isso ou definir qualquer valor.

RERANKER_MODEL: Especifique o modelo de reranker para o modo Ollama. Atualmente, testamos com rerankers BAAI. Você pode explorar todos os rerankers disponíveis usando este link. Nota: Isso NÃO é necessário para o modo LLM personalizado - o modelo de reranker não será baixado se você estiver usando LLM_BASE_URL.

USER_ID: Basta usar seu e-mail aqui, isso é necessário para autenticar o GPT personalizado para pesquisar em seus dados.

PASSWORD: Coloque qualquer senha aqui, isso é usado para criar uma conta firebase para o e-mail especificado acima.

Exemplos

Exemplo de arquivo .env para uso on-premises/local com Ollama:

LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
EMBEDDING_SIZE=768
OLLAMA_MODEL=qwen2:0.5b # must be LLM model id from Ollama models page
RERANKER_MODEL=BAAI/bge-reranker-base # please, choose any BAAI reranker model

Exemplo de arquivo .env para implantação de LLM personalizado (API compatível com OpenAI):

LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
EMBEDDING_SIZE=768
LLM_BASE_URL=http://your-llm-address:port/v1 # Your custom LLM endpoint
LLM_MODEL=Qwen/Qwen-1.7B # Your model name
LLM_API_KEY=not-needed # Optional: API key if required

# NOTE: OLLAMA_MODEL and RERANKER_MODEL are NOT needed for custom LLM mode
# The Docker build will skip reranker download automatically

Importante: Ao usar o modo LLM personalizado, você NÃO precisa definir as variáveis OLLAMA_MODEL ou RERANKER_MODEL. O fluxo de trabalho do LLM personalizado usa recuperação direta sem reranking para melhor desempenho. O Dockerfile pulará automaticamente o download do modelo de reranker durante a construção.

Para usar uma interface de chat, navegue até http://localhost:3000

O modo LLM personalizado usa um fluxo de trabalho diferente em comparação ao Ollama:

Fluxo de Trabalho Ollama:

  1. Consulta do usuário → Aprimoramento da consulta (chamada LLM)
  2. Recuperação de documentos com reranking (HuggingFace CrossEncoder)
  3. Geração de resposta (chamada LLM)

Fluxo de Trabalho LLM Personalizado:

  1. Consulta do usuário → LLM decide se a pesquisa de documentos é necessária (chamada de função)
  2. Se necessário: Pesquisa vetorial direta (sem reranking)
  3. LLM gera resposta com ou sem contexto recuperado

Servidores LLM Compatíveis:

  • vLLM - Servidor de inferência de alto desempenho (http://your-server:8000/v1)
  • Text Generation Inference (TGI) - Servidor de inferência da Hugging Face
  • Servidor Ollama - Ollama rodando em modo API
  • LiteLLM - Proxy para múltiplos provedores de LLM
  • LocalAI - Inferência local compatível com OpenAI
  • API OpenAI - Use diretamente a API da OpenAI
  • Qualquer endpoint compatível com OpenAI

Isso usará automaticamente docker-compose-custom-llm.yml que implanta apenas os serviços necessários (sem contêiner Ollama).

Exemplo de arquivo .env para o aplicativo Claude:

LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
EMBEDDING_SIZE=768

Para o aplicativo Claude, aplique as alterações no arquivo claude_desktop_config.json conforme descrito acima.

Para usar MCP com GitHub Copilot:

  1. Crie um arquivo .env no diretório raiz do projeto (onde você encontrará env.sample). Coloque o .env na mesma pasta e copie todas as variáveis de ambiente do env.sample para o .env.

  2. Certifique-se de que seu arquivo .env inclua as seguintes variáveis:

    • LOCAL_FILES_PATH
    • EMBEDDING_MODEL_ID
    • EMBEDDING_SIZE

  3. Crie ou atualize o .vscode/mcp.json com a seguinte configuração:

{
  "servers": {
    "minima": {
      "type": "stdio",
      "command": "path_to_cloned_minima_project/run_in_copilot.sh",
      "args": [
        "path_to_cloned_minima_project"
      ]
    }
  }
}

Exemplo de arquivo .env para uso com GPT personalizado do ChatGPT:

LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
EMBEDDING_SIZE=768
USER_ID=user@gmail.com # your real email
PASSWORD=password # you can create here password that you want

Além disso, você pode executar o minima usando run.sh.

Para uso com MCP, certifique-se de que o python da sua máquina local seja >=3.10 e que 'uv' esteja instalado.

Minima (https://github.com/dmayboroda/minima) é licenciado sob a Mozilla Public License v2.0 (MPLv2).