LibrePhotos 后端开发实战指南Django 结构、Sidecar 服务与 ONNX 机器学习管线【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos本指南以 LibrePhotos 仓库中的后端贡献文档 apps/docs/docs/development/contribution/backend/index.md 为主体结合apps/backend/下的源码、配置与测试系统梳理后端的整体技术栈、代码规范、调试手段、目录结构、独立服务架构与全部机器学习模块。读完本文你将掌握在 LibrePhotos 后端新增 Django 命令、调试查询、定位功能模块、以及理解图片描述、人脸识别、自动打标与语义搜索四条 ONNX 模型管线的完整运行原理。技术栈概览LibrePhotos 后端位于 apps/backend/由三部分核心技术组成Python全部后端逻辑的实现语言目标版本为 Python 3.11见 apps/backend/pyproject.toml 中的target-version py311Django承载 REST API、数据模型、数据库迁移与管理命令的 Web 框架业务代码集中在api/目录ONNX Runtime所有机器学习推理的统一执行引擎。镜像内不包含 PyTorch模型全部以 ONNX 格式导出后交给 ONNX Runtime 执行这一设计同时带来了两个直接好处CPU 镜像体积更小同一套模型文件可以直接运行在 GPU 镜像上换用onnxruntime-gpu即可。重型机器学习推理并不直接跑在 Django 进程里而是由独立的 Flask 服务Sidecar承担Django 通过 localhost 上的普通 HTTP 与之通信这一架构细节将在后文“独立服务架构”小节展开。代码规范与格式化pre-commit ruff为了保证代码风格一致后端仓库配置了 pre-commit 钩子。在apps/backend/目录下执行一次安装即可启用cd apps/backend pre-commit install此后每次git commit之前linter 与 formatter 都会自动检查并修复你的改动。钩子配置位于 apps/backend/.pre-commit-config.yaml它引入了两个来自ruff-pre-commit仓库的钩子且版本被严格锁定为v0.15.22repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.15.22 # Must match required-version in pyproject.toml hooks: - id: ruff args: [--fix] # Fix lint format - id: ruff-format # Format coderuff 同时承担 lint 与 format 两项职责相关配置全部写在 apps/backend/pyproject.toml 的[tool.ruff]与[tool.ruff.format]表中也可以脱离 pre-commit 手动执行ruff check . ruff format .值得注意的几项关键配置required-version 0.15.22ruff 的检查结果会随版本漂移锁死版本可保证本地工具与 CI 结论一致。pyproject 中的注释明确要求该版本必须与requirements.dev.txt、.pre-commit-config.yaml、.github/workflows/lint-backend.yml四处保持同步line-length 88单行最大长度 88 字符extend-exclude [migrations, im2txt, blip, places365]数据库迁移与旧模型目录不参与检查当前实际启用的规则为Gflake8-logging-format、LOGflake8-logging、PLE1205、PLE1206日志格式化字符串参数个数检查并忽略E501、E203、E231与G004f-string 日志。格式风格统一为双引号字符串、空格缩进、LF 换行quote-style double、indent-style space、line-ending lf。调试手段pdb 与 silk贡献文档介绍了两种互补的调试工具面向代码逻辑的pdb与面向查询性能的silk。使用 pdb 打断点在需要暂停的 Python 代码处插入import pdb; pdb.set_trace()然后附加到后端容器按容器名过滤docker attach $(docker ps --filter namebackend -q)即可在容器内的 pdb 中正常调试。调试结束后输入c继续执行随后按Ctrl-P再按Ctrl-Q脱离容器而不会停止容器本身。一个重要的前提这个docker attach pdb 的技巧只对 Django 进程有效。推理 Sidecar 是独立进程attach 不到它们——调试服务时需要改看/logs/下的日志或在对应服务的main.py中自行添加日志输出详见下文“独立服务架构”。使用 silk 分析查询以开发模式启动后端容器后Django 的实时分析与检查工具 silk 会暴露在/api/silk路径下。silk 会拦截并存储每个 HTTP 请求及其产生的数据库查询随后在 Web 界面中呈现非常适合排查 N1 查询、慢查询等性能问题。后端目录结构总览apps/backend/下的文件夹较多贡献文档给出了一张“寻宝图”路径内容librephotos/Django 工程本体配置settings/、URL 路由urls.py、wsgi.pyapi/绝大多数应用代码模型、视图、序列化器、迁移、管理命令scripts/辅助脚本如 setup_test_env.sh、build_ocr_bundle.pychunked_upload/分块上传应用支持断点续传nextcloud/Nextcloud 集成目录监听、directory_watcher.py等service/7 个机器学习/媒体处理 Sidecar 服务image_similarity/独立的图片相似度服务单独顶层目录Django 应用代码分布api/ 目录大部分应用代码都位于 api/ 目录下使用 Django 组织。贡献文档把这里的结构归纳为四块每块职责清晰managementapi/management/commands/暴露所有可通过命令行调用的命令。当前内置了scan、createadmin、createuser、start_service、build_similarity_index、clear_cache、save_metadata、start_cleaning_service、start_job_cleanup_service等。如果想新增一个命令这里就是添加位置migrationsapi/migrations/每当模型变更时借助 Django 的迁移机制生成迁移文件实现无痛数据库升级。仓库内已累积 0138 个迁移文件其中0099_photo_uuid_primary_key主键切换为 UUID、0112_convert_file_stacks_to_variants等迁移可以清晰看到历史演进脉络modelsapi/models/真实的数据类型定义。想弄清一张照片的数据结构photo.py、人脸如何与人物关联face.py、person.py、或照片堆栈关系photo_stack.py都在这里viewsapi/views/API 的具体实现与模型目录一一对应。暴露照片的视图位于 photos.py其他如albums.py、faces.py、search.py、duplicates.py等同样按业务垂直划分serializersapi/serializers/负责把 Python 模型对象转换为 JSON以及反向解析例如 photos.py 序列化照片、face.py 序列化人脸。独立服务Sidecar架构并非所有逻辑都运行在 Django 内部重型的机器学习推理由 7 个位于 service/ 下的独立 Flask 进程承担——thumbnail缩略图、face_recognition人脸识别、clip_embeddings语义嵌入、image_captioning图片描述、exifEXIF 提取、tags自动打标、ocr文字识别——另外image_similarity/作为单独顶层目录承载图片相似度服务。Django 通过 localhost 上的普通 HTTP 与它们通信。每个服务都由 gevent 的WSGIServer运行在固定端口上端口定义在 api/services.py 的SERVICES字典中SERVICES { image_similarity: 8002, thumbnail: 8003, face_recognition: 8005, clip_embeddings: 8006, image_captioning: 8007, exif: 8010, tags: 8011, ocr: 8012, }启动与管理命令使用管理命令启动服务python manage.py start_service service_name对应实现为 api/management/commands/start_service.py参数service的可选值来自SERVICES.keys()以及特殊值all传all时会遍历启动所有服务并额外在 django-q2 中调度api.services.check_services为每分钟执行一次的定时任务Schedule.MINUTES每个服务实际通过subprocess.Popen([python, fservice/{service}/main.py])拉起image_similarity则为image_similarity/main.py见 api/services.py 的start_service。健康检查看门狗api.services.check_services同样位于 api/services.py是这套 Sidecar 体系的“看门狗”其逻辑为遍历SERVICES中的每个服务跳过标记为系统不兼容的服务通过is_service_enabled判断该服务在当前部署配置下是否应该运行——服务与特性开关的映射记录在SERVICE_FEATURE_FLAGS如face_recognition对应FEATURE_FACE_DETECTION、image_captioning对应FEATURE_IMAGE_CAPTIONING、tags对应FEATURE_SCENE_CLASSIFICATION而ocr属于例外它由站点设置site setting而不是环境变量控制见SERVICE_SITE_GATES中的_ocr_model_selected调用is_healthy(service)轮询各服务/health端点超时由api.http_timeouts.HEALTH_CHECK控制健康检查不止看 HTTP 200如果响应中的last_request_time早于当前时间 120 秒该服务会被判定为“陈旧”stale并触发重启不健康的服务先stop_service通过psgrep找到进程后kill -9再重新start_service。子进程的环境变量由_service_environment()构造会显式注入BASE_LOGS与LOG_LEVEL因为 Sidecar 从不加载 Django需要从根日志配置中继承日志位置。由于是独立进程它们的日志写在/logs/下调试时直接查看日志文件或在自己的main.py里加打印。机器学习全线 ONNX Runtime每个模型都运行在 ONNX Runtime 上。贡献文档明确了两条硬约束镜像内没有 PyTorch——CPU 镜像因此更小同一代码可在 GPU 镜像中切换为onnxruntime-gpu新模型必须以 ONNX 导出形式接入并配套tokenizers包可加载的tokenizer.json分词器文件。Hugging Face 上的onnx-community与Xenova组织发布了大量现成的 ONNX 导出。模型注册表在 api/ml_models.py 的ML_MODELS列表中每项包含id、name、下载url、类型MlTypescaptioning/face_recognition/clip/tagging/ocr、解压命令与sha256 校验和。下载校验失败的模型会被当作普通下载失败处理部分文件被清理永远不会进入模型目录ModelChecksumError。例如 CLIPid 2与 MobileCLIP-S2id 3均来自 Xenova 的 ONNX 导出而 InsightFace 的buffalo_scid 5因其非商业研究许可刻意保留在上游 release 地址而不镜像。图片描述Image Captioning图片描述由image_captioning服务service/image_captioning/端口 8007按需生成。该服务运行 Liquid AI 的 LFM2.5-VL-450M被导出为三个 ONNX 图SigLIP2 NaFlex 视觉编码器输入 patch、输出投影后的图像 tokentoken embedding合并后的 LFM2 decoder自带 key/value 缓存与 LFM2 层维护的短卷积状态。驱动代码是 service/image_captioning/lfm2_vl.py解码方式为贪心解码greedy decoding默认提示词为Describe this image in a short, natural image caption.。站点设置中的Captioning Model取值为lfm2_vl_450m或none模型文件始终会被下载因此随时开启描述功能都不会等待下载。值得注意的是它的输入约束照片始终被缩放为单块one tile、最多 256 个图像 token。预处理仿照 transformers 的Lfm2VlImageProcessor单 tile 分支先 smart-resize 到 32 的倍数token 预算区间为 64256见MIN_IMAGE_TOKENS/MAX_IMAGE_TOKENS再以均值/标准差 0.5 归一化切成 16×16 patch。模块 docstring 解释了这样设计的原因256 个 token 正是该模型的基准测试设定缩略图本身不携带分块能发现的额外细节且该设定同时约束了单次描述的时间与内存上限。与固定模板的 captioner 不同LFM2 接受提示词因此可以把 LibrePhotos 已知的信息注入其中PhotoCaption.generate_captions_im2txt会根据用户的描述上下文开关历史命名User.llm_settings构造提示词——识别出的人物姓名与地理编码得到的地点会进入提示词由模型直接写进描述文本不再有独立的 LLM 处理环节。最终描述以im2txt键存储在PhotoCaption.captions_json中。用户侧的多模型对比见 图片描述用户指南。人脸识别Face Recognition人脸检测与识别基于 InsightFace运行于 ONNX Runtime 之上两阶段管线为SCRFD 检测器负责在图片中找出人脸ArcFace 模型将每张人脸编码为512 维嵌入向量。这套管线替换了此前的 dlib /face_recognition方案后者产出 128 维编码。模型通过站点设置Face Recognition Model选择默认buffalo_sc。服务端实现service/face_recognition/main.py支持antelopev2、buffalo_l、buffalo_m、buffalo_s、buffalo_sc五种模型未知模型名会回退到默认值加载时使用FaceAnalysis且只启用detection与recognition两个模块det_size(640, 640)。识别出的人脸按如下方式组织未知人脸通过自动聚类clustering分组成簇随后一个独立的分类步骤把新检测到的人脸与已标注人物labelled people进行匹配。人脸与人物关系的完整数据模型位于 api/models/face.py 与 api/models/person.py。自动打标模型Tagging Modelstags服务service/tags/为照片生成自动标签通过站点设置Tagging Model可选两种模型mobileclip_s2service/tags/mobileclip/默认——Apple 的 MobileCLIP-S2 以 ONNX 形式运行。针对 tags.txt 中的共享词表做零样本分类由于不同照片之间的原始 CLIP 余弦相似度不可比标签阈值基于所有标签上的 softmax 概率CLIP logit scale 100进行截断siglip2service/tags/siglip2/——Google 的 SigLIP 2 视觉-语言模型以 ONNX 形式运行使用同一份词表但直接按原始余弦相似度截断。准确率更高计算开销也重数倍。服务端service/tags/main.py的TAGGERS字典记录了两种模型及其阈值siglip2余弦阈值 0.05、mobileclip_s2softmax 阈值 0.02单张照片最多保留 10 个标签MAX_TAGS 10。请求走POST /generate-tags模型实例按需懒加载并缓存。两个打标器首次运行后都会把标签嵌入缓存到模型文件旁边并将{tags: [...]}按模型键mobileclip_s2、siglip2写入PhotoCaption.captions_json同时把照片归入类型为model_tag的AlbumThing记录自动相册。读取时只读取当前激活模型的键因此切换打标模型无需重新生成数据。语义搜索Semantic Search语义搜索让用户可以按“trees in a valley”这类自然语言描述检索图片其实现位于clip_embeddings服务service/clip_embeddings/clip_onnx.py运行 OpenAI 的CLIP ViT-B/32的 ONNX 版本。关键兼容性保证这些权重与此前 sentence-transformers 打包的clip-ViT-B-32完全一致api/ml_models.py 中 CLIP 条目的注释明确写道“the same weights the sentence-transformers clip-ViT-B-32 bundle used to wrap, exported to ONNX”因此在切换实现之前就已入库的嵌入向量仍然有效无需重新计算。文本与视觉两个子模型vision_model.onnx、text_model.onnx及tokenizer.json均在模型注册表中配好了固定 sha256保证下载内容可复现。小结LibrePhotos 后端的工程形态可以概括为“一个 Django 核心 八个推理 Sidecar 全线 ONNX 推理”Django 负责模型、视图、序列化与迁移是业务与 API 的家七个 Flask 服务加上独立的image_similarity承担全部机器学习工作由start_service管理命令拉起、由每分钟执行的check_services看门狗保证存活所有模型统一走 ONNX Runtime通过带 sha256 校验的模型注册表分发覆盖图片描述、人脸识别、自动打标与语义搜索四条完整管线。配合 pre-commit ruff 的代码规范约束、pdb 与 silk 的调试手段这套结构为新增命令、修改模型、调试查询乃至接入新的 ONNX 模型提供了清晰的路径。【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考