Murad Library
RESEARCH#md

RESEARCH

Manual de Uso do Anagnorisis

manual_anagnorisis.md

research·#MD·manual_anagnorisis.md
Date
Reading
14 min read

Manual de Uso do Anagnorisis

Versão do manual: 1.0
Idioma: Português
Projeto: volotat/Anagnorisis
Site/artigo relacionado: File Sharing is All We Need

1. O que é o Anagnorisis

O Anagnorisis é uma plataforma local de gerenciamento, busca e recomendação de arquivos. A proposta é permitir que você organize e descubra conteúdos como imagens, músicas, textos e vídeos usando modelos de inteligência artificial que rodam no seu próprio computador.

A ideia principal é simples:

  1. Você adiciona pastas com seus arquivos.
  2. O sistema analisa esses arquivos localmente.
  3. Você avalia conteúdos de 0 a 10.
  4. O sistema treina um modelo com base nas suas avaliações.
  5. Esse modelo passa a prever quais novos conteúdos combinam mais com o seu gosto.

O foco do projeto é privacidade: seus arquivos, avaliações e modelos ficam no seu computador, sem depender de uma plataforma centralizada.

2. Para quem este sistema serve

O Anagnorisis pode ser útil para quem quer:

  • organizar coleções grandes de arquivos pessoais;
  • buscar imagens, músicas, vídeos e textos por similaridade ou significado;
  • criar um sistema local de recomendação personalizado;
  • experimentar IA local aplicada a arquivos próprios;
  • evitar depender de algoritmos de plataformas centralizadas;
  • testar uma alternativa local a sistemas de recomendação como YouTube, Spotify ou feeds sociais.

Este não é, pelo menos por enquanto, um programa casual com instalador simples. Ele é mais indicado para usuários com alguma familiaridade com terminal, Docker, Git e configuração de caminhos de pastas.

3. Requisitos recomendados

3.1 Hardware

Segundo a documentação do projeto, o sistema pode rodar com:

  • GPU com pelo menos 8 GB de VRAM, preferencialmente Nvidia; ou
  • modo CPU-only com pelo menos 16 GB de RAM.

Para uma experiência melhor, o próprio autor recomenda algo mais próximo de:

  • GPU Nvidia relativamente moderna;
  • pelo menos 8 GB de VRAM;
  • 32 GB de RAM;
  • bastante espaço livre em disco.

O container Docker pode ocupar dezenas de gigabytes depois de baixar dependências e modelos de IA.

3.2 Software

Você vai precisar de:

  • Git;
  • Docker;
  • Docker Compose;
  • navegador web moderno;
  • no Windows, Docker Desktop com WSL2;
  • em Linux com GPU Nvidia, NVIDIA Container Toolkit.

4. Visão geral da instalação

A forma recomendada de executar o Anagnorisis é via Docker. Isso evita boa parte dos problemas com dependências Python, versões de CUDA, PyTorch e bibliotecas de machine learning.

O fluxo geral é:

  1. Instalar Docker.
  2. Baixar o código do Anagnorisis pelo GitHub.
  3. Copiar o arquivo de configuração de exemplo.
  4. Editar os caminhos das suas pastas de mídia.
  5. Subir o container com Docker Compose.
  6. Abrir o sistema no navegador.

5. Download do projeto

Abra um terminal e execute:

git clone https://github.com/volotat/Anagnorisis.git
cd Anagnorisis

Isso baixa o código do projeto para uma pasta chamada Anagnorisis.

6. Configuração inicial

Depois de entrar na pasta do projeto, copie o arquivo de configuração de exemplo:

cp docker-compose.override.example.yaml docker-compose.override.yaml

No Windows PowerShell, o comando equivalente pode ser:

Copy-Item docker-compose.override.example.yaml docker-compose.override.yaml

Agora abra o arquivo docker-compose.override.yaml em um editor de texto.

Você deverá configurar quais pastas do seu computador serão acessíveis dentro do container.

Exemplo em Linux/macOS:

volumes:
  # Configuração do projeto: banco de dados, modelos treinados e cache
  - /home/seu_usuario/Anagnorisis-config:/mnt/project_config

  # Imagens
  - /home/seu_usuario/Fotos:/mnt/media/images/Fotos

  # Músicas
  - /home/seu_usuario/Musicas:/mnt/media/music/Musicas

  # Textos/documentos
  - /home/seu_usuario/Documentos:/mnt/media/text/Documentos

  # Vídeos
  - /home/seu_usuario/Videos:/mnt/media/videos/Videos

Exemplo conceitual no Windows:

volumes:
  - C:/Users/SeuUsuario/Anagnorisis-config:/mnt/project_config
  - C:/Users/SeuUsuario/Pictures:/mnt/media/images/Pictures
  - C:/Users/SeuUsuario/Music:/mnt/media/music/Music
  - C:/Users/SeuUsuario/Documents:/mnt/media/text/Documents
  - C:/Users/SeuUsuario/Videos:/mnt/media/videos/Videos

6.1 Como interpretar os caminhos

Cada linha segue este formato:

/caminho/no/seu/computador:/mnt/media/TIPO/NOME

Onde:

  • /caminho/no/seu/computador é a pasta real no seu sistema;
  • /mnt/media/TIPO/NOME é o caminho usado dentro do container;
  • TIPO pode ser images, music, text ou videos;
  • NOME é o nome que aparecerá dentro da interface do Anagnorisis.

Exemplo:

- /home/pablo/FotosViagem:/mnt/media/images/Viagens

Nesse caso, a pasta local /home/pablo/FotosViagem aparecerá no módulo de imagens com o nome Viagens.

7. Atenção no Docker Desktop

Se você usa Docker Desktop, especialmente no Windows ou macOS, talvez precise permitir explicitamente o acesso às pastas de mídia.

No Docker Desktop:

  1. Abra Settings.
  2. Vá em Resources.
  3. Entre em File Sharing.
  4. Adicione as pastas que você quer montar no Anagnorisis.
  5. Salve as alterações.

Se você não fizer isso, o container pode iniciar, mas não conseguir ler suas pastas.

8. Iniciando o sistema

Na pasta do projeto, execute:

docker compose up -d

O parâmetro -d executa o container em segundo plano.

Na primeira inicialização, o sistema pode demorar bastante porque precisa baixar modelos de IA e preparar caches.

Depois de iniciado, abra no navegador:

http://localhost:5001

Se você alterou a porta no arquivo de configuração, use a porta configurada.

9. Verificando logs

Se a interface não abrir ou parecer travada na inicialização, consulte os logs.

Na pasta do projeto, procure a pasta:

logs/

O arquivo de log costuma seguir o padrão:

logs/anagnorisis-app_log.txt

ou usar o nome do container configurado.

Você também pode verificar pelo Docker:

docker compose logs -f

Esse comando mostra os logs em tempo real.

10. Parando o sistema

Para parar o Anagnorisis, execute:

docker compose down

Isso desliga o container, mas mantém suas configurações, banco de dados e arquivos de projeto nas pastas configuradas.

11. Reiniciando o sistema

Para iniciar novamente:

docker compose up -d

Para reiniciar reconstruindo a imagem, por exemplo depois de atualizar código ou módulos:

docker compose up -d --build

12. Primeiro uso na interface

Depois de abrir http://localhost:5001, você deve ver a interface web do Anagnorisis.

A interface é organizada por módulos. Os módulos internos incluem:

  • Images: gerenciamento e busca de imagens;
  • Music: gerenciamento e recomendação de músicas;
  • Text: gerenciamento e busca de textos/documentos;
  • Videos: gerenciamento e busca de vídeos;
  • Train: treinamento do modelo de avaliação/recomendação.

A disponibilidade e comportamento exato podem mudar conforme a versão instalada.

13. Como funciona o fluxo principal

O uso básico do Anagnorisis segue este ciclo:

  1. Adicionar dados
    Você monta pastas com seus arquivos no docker-compose.override.yaml.

  2. Explorar arquivos
    Você navega pelos módulos de imagem, música, texto ou vídeo.

  3. Avaliar conteúdos
    Você dá notas para os itens, geralmente em uma escala de 0 a 10.

  4. Treinar o modelo
    Depois de acumular avaliações suficientes, você usa a página Train para ajustar um modelo às suas preferências.

  5. Receber recomendações ou ordenações melhores
    O modelo passa a estimar quais arquivos você provavelmente avaliaria melhor.

  6. Corrigir o modelo
    Se o sistema errar, você altera a nota. Essas correções viram novos dados para treinamentos futuros.

  7. Repetir o ciclo
    Quanto mais avaliações boas e variadas você fornece, melhor tende a ficar o modelo.

14. Avaliando arquivos

A avaliação é a base do sistema.

Use uma escala consistente. Uma sugestão prática:

NotaSignificado sugerido
0Detesto / irrelevante / não quero ver
1-2Muito ruim
3-4Fraco ou pouco interessante
5Neutro
6-7Bom
8Muito bom
9Excelente
10Exatamente o tipo de coisa que quero encontrar mais

O ponto importante: não avalie tudo com nota alta. Se você der 8, 9 ou 10 para quase tudo, o modelo aprende pouco. Ele precisa de contraste.

15. Treinando o modelo

Depois de avaliar uma quantidade razoável de arquivos, vá até o módulo Train.

O objetivo do treinamento é criar um modelo que tente prever suas notas para conteúdos ainda não avaliados.

Um fluxo sensato:

  1. Avalie um conjunto inicial de arquivos.
  2. Entre em Train.
  3. Inicie o treinamento do avaliador.
  4. Aguarde o processo terminar.
  5. Volte aos módulos de conteúdo.
  6. Ordene ou filtre arquivos pelas notas previstas.
  7. Corrija as notas quando o sistema errar.
  8. Treine novamente depois de juntar mais correções.

Não espere mágica com poucas avaliações. Um modelo com 20 avaliações provavelmente será instável. Um modelo com centenas de avaliações bem distribuídas tende a ser muito mais útil.

16. Busca e descoberta

O Anagnorisis oferece mecanismos de busca baseados em nomes, conteúdo, embeddings e metadados, dependendo do módulo e da versão.

Na prática, você pode usar o sistema para:

  • procurar arquivos por nome;
  • buscar conteúdos semanticamente parecidos;
  • encontrar imagens ou músicas similares;
  • filtrar por metadados;
  • ordenar arquivos por preferência prevista;
  • explorar arquivos que talvez você não encontraria manualmente.

A versão 0.3.x do projeto dá bastante ênfase a busca unificada e uso de descrições .meta.

17. Arquivos .meta

Uma ideia importante do projeto é usar arquivos pequenos de metadados para representar arquivos grandes.

Exemplo:

video_exemplo.mp4
video_exemplo.mp4.meta

O arquivo .meta pode conter descrições como:

  • título;
  • autor;
  • duração;
  • descrição textual do conteúdo;
  • transcrição;
  • tags;
  • observações relevantes.

Isso permite que o sistema busque e recomende arquivos pesados sem precisar processar o arquivo inteiro o tempo todo.

Exemplo simples de .meta:

Title: Aula sobre redes P2P
Author: Exemplo
Description: Vídeo explicando BitTorrent, IPFS, compartilhamento de arquivos e descoberta descentralizada de conteúdo.
Tags: p2p, bittorrent, ipfs, redes, descentralização

18. Organização recomendada das pastas

Uma estrutura simples pode ser:

Anagnorisis-config/
Fotos/
Musicas/
Documentos/
Videos/

Exemplo mais organizado:

Midia/
  Imagens/
    Fotos Pessoais/
    Referencias Visuais/
    Screenshots/
  Musicas/
    Biblioteca Principal/
    Downloads/
  Textos/
    Artigos/
    Notas/
    PDFs/
  Videos/
    Aulas/
    Documentarios/

No docker-compose.override.yaml, você pode montar várias pastas por módulo:

volumes:
  - /home/user/Anagnorisis-config:/mnt/project_config
  - /home/user/Midia/Imagens/Fotos Pessoais:/mnt/media/images/Fotos
  - /home/user/Midia/Imagens/Screenshots:/mnt/media/images/Screenshots
  - /home/user/Midia/Musicas/Biblioteca Principal:/mnt/media/music/Biblioteca
  - /home/user/Midia/Textos/Artigos:/mnt/media/text/Artigos
  - /home/user/Midia/Videos/Aulas:/mnt/media/videos/Aulas

19. Múltiplas instâncias

O projeto permite executar várias instâncias independentes. Isso pode ser útil para:

  • separar usuários;
  • separar projetos;
  • separar bibliotecas pessoais e profissionais;
  • testar configurações diferentes.

O repositório inclui exemplos na pasta instances/.

Fluxo geral:

cp instances/example-personal.yaml instances/personal.yaml

Edite instances/personal.yaml e configure:

  • nome único do projeto;
  • porta única;
  • nome único do container;
  • pasta própria de configuração;
  • pastas de mídia desejadas.

Depois execute:

docker compose -f docker-compose.yaml -f instances/personal.yaml up -d

Para parar:

docker compose -f docker-compose.yaml -f instances/personal.yaml down

20. Instalando módulos externos

O Anagnorisis usa um sistema modular. Módulos ficam dentro da pasta:

modules/

Para instalar um módulo externo:

cd modules
git clone <url-do-modulo>
cd ..
docker compose up -d --build

Segundo a documentação do projeto, existem módulos externos experimentais como:

  • WebSearch;
  • YouTube.

Por serem experimentais, use com cautela. A estabilidade pode variar.

21. Atualizando o projeto

Para atualizar o código:

git pull

Depois reconstrua e reinicie:

docker compose up -d --build

Antes de atualizar, faça backup da pasta de configuração, especialmente do banco de dados.

22. Backup

O arquivo mais importante é o banco de dados do projeto. Ele guarda suas avaliações, preferências e histórico.

Depois da primeira execução, o projeto cria uma estrutura dentro da pasta configurada como:

/mnt/project_config

No seu computador, isso corresponde à pasta que você mapeou, por exemplo:

/home/user/Anagnorisis-config

Dentro dela, procure por algo como:

database/project.db

Faça backup periódico desse arquivo ou da pasta inteira de configuração.

Exemplo:

cp -r /home/user/Anagnorisis-config /home/user/Backups/Anagnorisis-config-backup

23. Segurança

Por padrão, o Anagnorisis foi pensado para rodar localmente, acessível apenas pela própria máquina.

A configuração padrão costuma usar:

127.0.0.1

Isso significa que apenas o computador local acessa o sistema.

Evite expor o Anagnorisis diretamente à internet. O próprio projeto alerta que ainda não há trabalho de segurança suficiente para tratar a aplicação como um serviço público exposto.

Se você alterar o binding para:

0.0.0.0:5001:5001

outros dispositivos da rede poderão acessar. Isso pode ser útil em uma rede doméstica, mas aumenta o risco.

Recomendação direta: se você não entende bem rede, autenticação, firewall e proxy reverso, não exponha esse sistema fora do seu computador.

24. Solução de problemas

24.1 A página não abre

Verifique se o container está rodando:

docker compose ps

Veja os logs:

docker compose logs -f

Confirme se está acessando a porta correta:

http://localhost:5001

24.2 O sistema demora muito na primeira execução

Isso pode ser normal. Na primeira inicialização, o sistema baixa modelos grandes de IA e prepara caches.

Espere e acompanhe os logs.

24.3 Erro de permissão em pasta montada

Se aparecer erro parecido com:

Cannot start service anagnorisis: error while creating mount source path ... operation not permitted

Crie manualmente a pasta no sistema host e garanta que o Docker tenha permissão para acessá-la.

24.4 Minhas pastas não aparecem

Confira:

  • se os caminhos no docker-compose.override.yaml estão corretos;
  • se você usou caminhos absolutos;
  • se o Docker Desktop tem permissão para acessar essas pastas;
  • se o tipo foi escrito corretamente: images, music, text ou videos;
  • se você reiniciou o container após editar a configuração.

24.5 O sistema está lento

Possíveis causas:

  • ausência de GPU compatível;
  • pouca RAM;
  • muitos arquivos na primeira indexação;
  • modelos ainda sendo baixados;
  • cache de embeddings sendo criado;
  • execução em CPU-only.

Solução prática: espere a indexação inicial terminar, reduza o número de pastas montadas ou use uma máquina com GPU Nvidia compatível.

24.6 Download de modelos corrompido ou interrompido

Se a inicialização foi interrompida durante o download de modelos, tente iniciar novamente. O sistema deve tentar corrigir automaticamente.

Se continuar falhando, pare o container e remova a pasta de modelos dentro da configuração/projeto, conforme orientação do README, para forçar novo download.

25. Boas práticas

  • Comece com poucas pastas, não com sua vida digital inteira.
  • Avalie arquivos com notas variadas.
  • Não treine cedo demais com poucas avaliações.
  • Faça backup do banco project.db.
  • Não exponha a aplicação à internet.
  • Leia os logs antes de assumir que travou.
  • Atualize com cautela, porque o projeto está em desenvolvimento ativo.
  • Separe instâncias se quiser perfis diferentes de recomendação.

26. Exemplo de fluxo completo

Cenário

Você quer usar o Anagnorisis para organizar fotos e músicas.

Passo 1: baixar

git clone https://github.com/volotat/Anagnorisis.git
cd Anagnorisis

Passo 2: criar configuração

cp docker-compose.override.example.yaml docker-compose.override.yaml

Passo 3: editar volumes

volumes:
  - /home/pablo/Anagnorisis-config:/mnt/project_config
  - /home/pablo/Fotos:/mnt/media/images/Fotos
  - /home/pablo/Musicas:/mnt/media/music/Musicas

Passo 4: iniciar

docker compose up -d

Passo 5: abrir

http://localhost:5001

Passo 6: avaliar

Entre nos módulos de imagens e músicas. Avalie arquivos de 0 a 10.

Passo 7: treinar

Entre no módulo Train e inicie o treinamento.

Passo 8: usar recomendações

Volte aos módulos e ordene/filtre arquivos com base nas notas previstas.

Passo 9: corrigir

Quando o modelo errar, ajuste a nota manualmente.

Passo 10: repetir

Depois de novas avaliações, treine de novo.

27. Limitações atuais

O Anagnorisis é promissor, mas ainda tem limitações claras:

  • instalação ainda é técnica;
  • uso depende de hardware razoável;
  • primeira inicialização pode ser demorada;
  • módulos externos podem ser experimentais;
  • desempenho sem GPU pode ser fraco;
  • a segurança não deve ser considerada adequada para exposição pública;
  • a qualidade da recomendação depende muito da quantidade e qualidade das suas avaliações.

Em termos práticos: trate como um projeto poderoso, mas ainda hacker/experimental, não como um produto comercial polido.

28. Comandos rápidos

Baixar

git clone https://github.com/volotat/Anagnorisis.git
cd Anagnorisis

Criar configuração

cp docker-compose.override.example.yaml docker-compose.override.yaml

Iniciar

docker compose up -d

Ver logs

docker compose logs -f

Parar

docker compose down

Reconstruir

docker compose up -d --build

Atualizar

git pull
docker compose up -d --build

29. Fontes consultadas

30. Resumo final

O Anagnorisis é um sistema local de busca, organização e recomendação de arquivos. Você monta suas pastas, avalia conteúdos, treina um modelo com base no seu gosto e passa a usar esse modelo para filtrar e descobrir arquivos de forma personalizada.

A ideia é forte: criar um recomendador privado, local e treinável. A execução ainda exige paciência técnica. Para usuários comuns, pode ser áspero. Para quem gosta de self-hosting, IA local e controle sobre os próprios dados, é um projeto muito interessante.

Related documents

Manual de Uso do Anagnorisis · Murad Library