Facial Recognition

Lychee can automatically detect faces in your photos, group similar-looking faces together, and let you label them as People. Once people are tagged you can browse “all photos of X” the same way you browse albums or tags, and even build Person Albums — smart albums that match one or more people.

All of the machine-learning work (face detection, embeddings, clustering, selfie matching) runs in a dedicated Lychee-Facial-Recognition microservice, kept separate from the main PHP application so the heavier workload doesn’t run on your gallery server.

• Auto-scan on upload — newly uploaded photos are automatically queued for face detection once both AI Vision and facial recognition are enabled.
• Detection — the AI Vision service finds faces in each photo and returns bounding boxes plus an embedding (a numeric “fingerprint”) for each face.
• Clustering — faces that aren’t yet linked to a person are grouped into clusters of similar-looking faces, so you can label a whole group at once instead of one face at a time.
• Overlays — when viewing a photo, detected faces are shown as overlays. Press P to toggle their visibility.

• Person management — create, rename, merge, and delete people from the People page.
• Assign faces — assign an individual detected face, or a whole face cluster, to a person.
• Dismiss faces — mark false-positive detections as dismissed so they stop appearing for review; admins (or photo owners, depending on the permission mode) can also purge dismissed faces in bulk.
• Person Albums — smart albums that automatically include every photo containing one or more chosen people (matched with AND/OR logic), the same way tag-based smart albums work.
• Searchable people — people can be excluded from search results individually (the ai_vision_face_person_is_searchable_default setting controls the default for newly created people).

Users can link a Person record to their own account (“claiming”), which is useful for letting people find themselves automatically:

• Manual claim — pick yourself from the People list.
• Claim by selfie — upload a selfie; Lychee forwards it to the AI Vision service’s matching endpoint and automatically claims the best-matching person if the match confidence is above ai_vision_face_selfie_confidence_threshold (default 0.8). The uploaded selfie itself is discarded immediately after matching — it is never stored.
• A person can only be claimed by one user at a time, and (unless you’re an admin) you can’t claim a second person once you already have one linked.
• Whether non-admin users may claim people at all is controlled by the ai_vision_face_allow_user_claim setting; admins can always claim/unclaim/merge regardless.

Who can see and manage faces is controlled by a single setting, ai_vision_face_permission_mode:

The feature is controlled by a AI Vision category of Settings, all disabled/conservative by default:

Facial recognition requires running the Lychee-Facial-Recognition service (FastAPI + DeepFace) alongside Lychee, then pointing Lychee at it via the AI_VISION_FACE_URL and AI_VISION_FACE_API_KEY environment variables — see AI Vision in the configuration reference. The diagnostics page reports whether the service is reachable and correctly configured.

The service is configured independently, via its own .env file (copy .env.example to .env). All of its variables are prefixed VISION_FACE_; missing required variables produce a formatted error at startup instead of a raw traceback.

Detection and clustering jobs are processed asynchronously via a persistent queue shared across all worker processes. Requests that arrive when the queue is full receive 429 Too Many Requests.

docker run --rm \
  --env-file .env \
  -v /path/to/lychee/public/uploads:/data/photos:ro \
  -v ai-vision-embeddings:/data/embeddings \
  -p 8000:8000 \
  lychee-ai-vision

The container exposes interactive API docs at /docs and a health check at /health once running.