Immich: pesquisar suas fotos com uma IA locale

O Immich, a alternativa auto-hospedada ao Google Fotos, permite encontrar uma foto digitando uma descrição ("cachorro na praia", "bolo de aniversário") em vez de um nome de arquivo. Essa pesquisa de fotos com IA se baseia em um modelo CLIP que roda no seu servidor, no contêiner de machine learning do Immich. Este guia explica como ela funciona, como escolher um modelo multilíngue para pesquisar em francês, quais erros observar e o que realmente sai da sua rede. O procedimento descrito segue a documentação oficial; ele não foi reproduzido em uma instância de teste para este guia.
#Pesquisa de fotos com IA no Immich: o princípio
O recurso se chama Smart Search na documentação do Immich ("pesquisa inteligente" ou pesquisa por contexto na interface). Ele não lê suas fotos em tempo real no momento da consulta. Ele se baseia em duas operações distintas, ambas a cargo do serviço immich-machine-learning.
- 01Indexação das imagensPara cada foto, o codificador de imagens do modelo CLIP calcula um vetor numérico (um embedding) que resume seu conteúdo visual. Esse vetor é armazenado no banco de dados do Immich. Esse é o trabalho da tarefa "Smart Search" visível na administração; em uma fototeca grande, ela pode demorar bastante.
- 02Codificação da consultaQuando você digita uma frase, o codificador de texto do mesmo modelo a transforma, por sua vez, em um vetor.
- 03ComparaisonO Immich retorna as fotos cujo vetor está mais próximo do vetor da sua frase. Não há geração de texto nem "compreensão" no sentido de um chatbot: é uma busca por similaridade em um espaço comum de imagens e texto.
Consequência direta: o texto e as imagens precisam ter sido codificados pelo mesmo modelo. Se você trocar de modelo, todas as fotos precisam ser reindexadas; caso contrário, os vetores antigos e novos deixam de ser comparáveis.
#O CLIP não é um assistente de visão
Aproveite a nossa experiência e um percurso guiado para criar o seu assistente local e usar a sua IA no dia a dia.
- Espaço online vitalício
- PDF + arquivos
- Reembolsado em 30 dias
É comum confundir a pesquisa CLIP do Immich com os modelos de "visão" que rodamos com Ollama (Qwen3-VL, Gemma etc.). São duas ferramentas diferentes, que atendem a duas necessidades diferentes.
- O que o CLIP faz no Immich
- Classificar suas fotos por proximidade com uma frase. O resultado é uma lista de imagens ordenadas, não uma resposta redigida. O modelo é pequeno e a indexação é feita uma vez; depois, a busca é rápida.
- O que um assistente de visão faz
- Descrever uma imagem, responder a uma pergunta sobre o conteúdo dela, ler texto (OCR), comparar duas imagens. Ele gera texto, imagem por imagem, e custa muito mais em processamento e memória.
- O que o CLIP não sabe fazer
- Responder a « quantas pessoas há nesta foto? », descrever uma cena, ler de forma confiável um documento fotografado ou contar. Ele fornece uma pontuação de semelhança, nada mais.
- O que o Immich não integra nativamente
- Um LLM de visão que escreveria legendas ou conversaria com a sua fototeca. Existem projetos de terceiros, mas eles não fazem parte do Immich e não são abordados aqui.
Se você precisa encontrar “a foto do quadro branco de terça-feira”, o CLIP muitas vezes basta. Se você precisa extrair o texto desse quadro ou resumi-lo, é preciso um modelo de visão, por exemplo via Ollama, em uma imagem que você envia explicitamente para ele.
#Pré-requisitos
- Uma instância do Immich funcionando
- Instalada com o docker-compose.yml oficial, que inclui o serviço immich-machine-learning. Se você o removeu do seu arquivo compose, a busca inteligente não vai funcionar.
- Uma conta de administrador
- A escolha do modelo e a execução das tarefas de indexação são feitas na administração do servidor.
- Memória e tempo
- Um modelo CLIP maior exige mais RAM e indexa mais devagar. Não publicamos números de duração: eles dependem do modelo, da quantidade de fotos, da CPU ou da GPU, e não temos nenhuma medição documentada para lhe fornecer.
- Aceleração de hardware (opcional)
- O Immich documenta aceleração do machine learning (CUDA para NVIDIA, OpenVINO para Intel, ROCm para AMD, ARM NN e RKNN para algumas placas ARM). Ela não é obrigatória: a CPU basta, só que mais devagar.
- Um backup recente
- Trocar de modelo não mexe nos seus arquivos, mas reexecutar tarefas pesadas em um servidor doméstico é um bom momento para verificar se o backup do banco de dados e dos originais está em dia.
Para verificar se o serviço de machine learning está rodando, a partir da pasta que contém o seu docker-compose.yml:
#Ativar a busca de fotos com IA e escolher um modelo multilíngue
O modelo padrão indicado pela documentação do Immich é o ViT-B-32__openai, um CLIP treinado principalmente com legendas em inglês. Ele funciona, mas uma consulta em francês geralmente dá resultados menos relevantes do que a mesma consulta em inglês. A documentação recomenda usar um modelo multilíngue se você pesquisa em um idioma diferente do inglês.
- 01Abrir as configurações de machine learningNo Immich, abra Administração, depois Configurações e então a seção Machine Learning. Verifique se o machine learning está ativado e se a URL do serviço aponta de fato para o seu contêiner (por padrão, o serviço immich-machine-learning do arquivo compose).
- 02Escolher o modelo CLIPNa subseção Smart Search, substitua o nome do modelo. Os modelos oferecidos são publicados pela equipe do Immich no Hugging Face, e a documentação remete a uma lista que indica, para cada um, seu tamanho, seus requisitos de memória e se é multilíngue. Entre as famílias multilíngues citadas estão nllb-clip (por exemplo, nllb-clip-base-siglip__v1, nllb-clip-large-siglip__v1) e XLM-Roberta (por exemplo, XLM-Roberta-Large-Vit-B-16Plus). Copie o nome exato da lista oficial: um erro de digitação impede o download.
- 03GravarNa próxima vez que for necessário, o contêiner de ML baixa o modelo do Hugging Face e o mantém em cache (volume model-cache do compose oficial). Por isso, a primeira chamada pode ser lenta ou falhar se o servidor não tiver acesso à Internet.
- 04Reexecutar a indexação de toda a fototecaEm Administration, abra as tarefas (Jobs). Na linha Smart Search, execute o processamento em todas as fotos (« All »), e não apenas nas que estão faltando (« Missing »): os vetores calculados com o modelo antigo não são mais compatíveis. Acompanhe o andamento na mesma página e nos logs do contêiner.
- 05Testar com algumas consultas conhecidasEscolha três ou quatro fotos cujo conteúdo você conhece, pesquise-as em francês e verifique se elas aparecem nos resultados. Esse é o seu único teste de verdade: a relevância depende da sua biblioteca de fotos, e não podemos garanti-la a distância.
Qual modelo escolher? A documentação não aponta um « melhor » modelo universal. O trade-off é o clássico: um modelo maior (variantes large) promete mais relevância, mas consome mais memória e indexa mais devagar; um modelo base é mais leve. Em um servidor pequeno ou em um NAS sem GPU, comece com uma variante base multilíngue; se a relevância decepcionar e a máquina tiver folga, experimente uma variante maior, sabendo que será preciso reindexar tudo.
#Pesquisar suas fotos em francês
Depois que a indexação terminar, a busca é feita pela barra de pesquisa do aplicativo web ou mobile. Dependendo da versão, a interface oferece vários tipos de busca: contexto (a busca CLIP), nome do arquivo, descrição e, nas versões recentes, texto reconhecido por OCR. Para uma busca por descrição, mantenha o modo contexto.
- Descreva o que aparece na imagem
- “bicicleta vermelha encostada em um muro”, “pôr do sol no mar”, “criança soprando velinhas”. O CLIP reage a objetos, cenas, cores, atmosferas.
- Evite o que a imagem não mostra
- “férias de 2019 na casa do Paul” não corresponde a nada visível. Para data, local ou pessoa, use os filtros.
- Combine com os filtros
- O painel de filtros permite restringir por pessoas (reconhecimento facial, outra função do mesmo contêiner de ML), local, câmera, datas e tipo de mídia. Uma consulta curta com dois filtros costuma ser melhor do que uma frase longa.
- Reformulez
- Se "gato" der resultados demais, seja mais específico: "gato preto dormindo em um sofá". Se nada aparecer, simplifique. Teste também em inglês: se o inglês funcionar nitidamente melhor, seu modelo provavelmente é monolíngue.
- Não confunda com a busca por texto
- O modo de contexto não lê o texto das fotos. Para encontrar uma captura de tela pelo conteúdo escrito, use a pesquisa por OCR, se a sua versão oferecer, ou a pesquisa por nome de arquivo ou descrição.
Os resultados são ordenados por similaridade e não há um limiar de “corresponde / não corresponde”: a busca sempre retorna algo, mesmo para uma consulta absurda. Os primeiros resultados são os mais próximos; quanto mais você desce, menos relevantes eles são.
#Privacidade: o que fica com você
Esse é o principal argumento a favor de uma pesquisa de fotos com IA auto-hospedada, mas ele merece ser formulado com precisão. Este guia descreve a arquitetura documentada; ele não constitui uma auditoria da sua instalação e não garante que nenhum dado saia da sua rede.
- Os cálculos
- Na configuração oficial, a codificação das fotos e das consultas é feita pelo contêiner immich-machine-learning, na sua máquina. Os embeddings são armazenados no seu banco de dados PostgreSQL.
- O download dos modelos
- Os pesos dos modelos são baixados do Hugging Face no primeiro uso. Esse tráfego de saída é normal; ele não contém suas fotos. Depois que o modelo está em cache, ele não é baixado novamente enquanto você mantiver o volume.
- Um ML remoto
- A URL do serviço de machine learning é configurável: você pode rodar o contêiner de ML em outra máquina (um PC com GPU, por exemplo). Nesse caso, suas fotos trafegam até essa máquina. Mantenha-a na sua rede local ou atrás de uma VPN, nunca exposta diretamente na Internet.
- As outras funções
- Os mapas, a verificação de versão ou outras configurações podem contatar serviços externos. Eles são independentes da busca CLIP; revise as configurações do servidor se o seu objetivo é funcionar sem conexões de saída.
- Desativar
- O machine learning, ou apenas a pesquisa inteligente, pode ser desativado nas configurações. Suas fotos continuam acessíveis; você perde apenas a pesquisa por descrição.
#Erros frequentes e solução de problemas
- A pesquisa não retorna nada ou retorna um erro
- O contêiner de ML está parado ou inacessível, ou a URL nas configurações está errada. Verifique docker compose ps e os logs do immich-machine-learning.
- Falha no download do modelo
- Nome do modelo digitado errado, sem acesso ao Hugging Face ou disco cheio. Os logs do contêiner de ML geralmente indicam qual é o caso.
- O contêiner de ML reinicia em loop
- Muitas vezes é falta de memória com um modelo grande, ou uma imagem de aceleração (por exemplo, -cuda) que não corresponde ao hardware. Volte para um modelo menor ou para a imagem de CPU para isolar o problema.
- Resultados ruins após trocar de modelo
- A tarefa Smart Search foi executada apenas nas fotos faltantes, ou ainda não terminou. Execute-a novamente em todas as fotos.
- Resultados ruins em francês, corretos em inglês
- O modelo ativo é monolíngue (por exemplo, o padrão ViT-B-32__openai). Mude para um modelo multilíngue e reindexe.
- Fotos novas não encontradas
- A indexação de novos arquivos passa pela fila de tarefas. Se ela estiver pausada ou sobrecarregada, as fotos recentes ainda não têm vetor. Verifique a página de tarefas.
#Limitações e fontes
Este guia não publica nenhum tempo de indexação, nenhum consumo de memória medido nem nenhuma pontuação de relevância: não temos nenhuma medição documentada (hardware, versão, modelo, tamanho da fototeca) para apresentar a você. As ordens de grandeza que você encontra on-line dependem muito desses parâmetros; a única referência confiável é um teste no seu próprio servidor, com algumas consultas cuja resposta você conhece.
O Immich evolui rápido. Os nomes dos menus, a lista de modelos disponíveis e os tipos de pesquisa mudam de uma versão para outra. As informações acima se baseiam na página "Searching" da documentação oficial, consultada pela redação em 30 de outubro de 2026; elas não foram verificadas novamente no dia da publicação. Em caso de divergência, vale a documentação da sua versão: docs.immich.app/features/searching/.
#Para se aprofundar
A busca CLIP encontra fotos; para descrevê-las, fazer perguntas sobre elas ou extrair texto delas, é preciso um modelo de visão. Estes guias do site aprofundam o assunto.
- LLM multimodal com visão em execução local: analisar imagens com Ollama
- O guia relacionado: descrever uma imagem, fazer OCR, consultar uma foto com um modelo de visão local. O complemento natural da busca CLIP.
- Qwen3-VL local com Ollama
- Um modelo de visão preciso para analisar em detalhe as fotos que a busca do Immich ajudou você a encontrar.
- BGE-M3: embeddings que falam francês
- O mesmo princípio de embeddings multilíngues aplicado a texto, para entender por que um modelo monolíngue prejudica consultas em francês.
Um comentário, um erro ou uma observação? Avise-nos; isso ajuda a melhorar o guia para todos.