NekoImageGallery

GitHub Workflow Status (with event) codecov Maintainability Man hours Docker Pulls

基于Clip模型与Qdrant向量数据库的在线AI图片搜索引擎。支持关键字搜索以及相似图片搜索。

English Document

✨特性

📷截图

Screenshot1 Screenshot2 Screenshot3 Screenshot4 Screenshot5 Screenshot6

以上截图可能包含来自不同画师的版权图片，请不要将其用作其它用途。

✈️部署

📦 系统要求

硬件要求

硬件 最低要求 推荐配置
CPU X86_64 或 ARM64 处理器，2 核或以上 4 核或以上
内存 4GB 或以上 8GB 或以上
存储 至少 10GB 用于库、模型和数据 50GB 或以上，推荐使用 SSD
GPU 不需要 支持 CUDA 的 GPU 以加速计算，具有4GB或以上的显存

软件要求

🖥️ 本地部署

选择元数据存储方式

NekoImageGallery支持两种元数据存储方式：Qdrant数据库存储与本地文件存储。您可以根据自己的需求选择其中一种方式。

Qdrant数据库 （推荐）

在大多数情况下，我们推荐使用Qdrant数据库存储元数据。Qdrant数据库提供了高效的检索性能，灵活的扩展性以及更好的数据安全性。

请根据Qdrant文档部署Qdrant数据库，推荐使用docker部署。

如果你不想自己部署Qdrant，可以使用Qdrant官方提供的在线服务。

本地文件存储

本地文件存储直接将图片元数据（包括特征向量等）存在本地的Sqlite数据库中。仅建议在小规模部署或开发部署中使用。

本地文件存储不需要额外的数据库部署流程，但是存在以下缺点：

部署NekoImageGallery

[!NOTE] 本教程适用于NekoImageGallery v1.4.0及之后的版本，我们在该版本切换到了uv作为包管理器。如果您使用的是早期版本，请参考对应版本标签中的README文件。

  1. 将项目目录clone到你自己的PC或服务器中，然后按需checkout到特定版本tag（如v1.4.0）。
  2. 安装所需依赖： 
     uv sync --no-dev --extra cpu # 仅CPU部署

 uv sync --no-dev --extra cu124 # CUDA v12.4 部署

 uv sync --no-dev --extra cu118 # CUDA v11.8 部署

[!NOTE]

  1. 按需修改位于config目录下的配置文件，您可以直接修改default.env，但是建议创建一个名为local.env的文件，覆盖 default.env中的配置。
  2. 运行本应用： 
     uv run main.py

    你可以通过--host指定希望绑定到的ip地址(默认为0.0.0.0)，通过--port指定希望绑定到的端口(默认为8000)。
    通过uv run main.py --help可以查看所有可用命令和选项。

  3. (可选)部署前端应用：NekoImageGallery.App 是本项目的一个简易web前端应用，如需部署请参照它的部署文档。

🐋 Docker 部署

关于Docker镜像

NekoImageGallery镜像发布在DockerHub上，并包含多个变种，设计于在不同的环境使用。

Tags 介绍 Latest 镜像尺寸
edgeneko/neko-image-gallery:<version>
edgeneko/neko-image-gallery:<version>-cuda
edgeneko/neko-image-gallery:<version>-cuda12.4		 基于CUDA12.4, 支持GPU推理的镜像 Docker Image Size (tag)
edgeneko/neko-image-gallery:<version>-cuda11.8 基于CUDA11.8, 支持GPU推理的镜像 Docker Image Size (tag)
edgeneko/neko-image-gallery:<version>-cpu 仅支持CPU推理的镜像 Docker Image Size (tag)
edgeneko/neko-image-gallery:<version>-cpu-arm (Alpha) 支持ARM64(AArch64)平台的CPU推理 Docker Image Size (tag)

其中，<version>为NekoImageGallery的版本号或版本代称，具体如下：

Version 介绍
latest 最新的稳定版本
v*.*.* / v*.* 特定版本号(与GitHub Tag对应)
edge 最新的开发版本，与master分支同步更新，可能包含未经完善测试的功能和breaking changes

在每个镜像中，我们捆绑了必要的依赖项，包括 openai/clip-vit-large-patch14 模型权重、bert-base-chinese 模型权重和 easy-paddle-ocr 模型，以提供一个完整且可直接使用的镜像。

镜像使用 /opt/NekoImageGallery/static 作为存储图像文件的卷，如果需要本地存储，可以将其挂载到您自己的卷或目录。

对于配置，我们建议使用环境变量来覆盖默认配置。机密信息（如 API 令牌）可以通过 docker secrets 提供。

准备nvidia-container-runtime

如果你希望在推理时支持CUDA加速，请参考Docker GPU相关文档 准备支持GPU的容器运行时。

相关文档：

  1. https://docs.docker.com/config/containers/resource_constraints/#gpu
  2. https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker
  3. https://nvidia.github.io/nvidia-container-runtime/

运行

  1. 下载docker-compose.yml文件。 
    # For cuda deployment (default)
wget https://raw.githubusercontent.com/hv0905/NekoImageGallery/master/docker-compose.yml
# For CPU-only deployment
wget https://raw.githubusercontent.com/hv0905/NekoImageGallery/master/docker-compose-cpu.yml && mv docker-compose-cpu.yml docker-compose.yml
  2. 按需修改docker-compose.yml文件
  3. 运行下面命令启动docker-compose 
    # start in foreground
docker compose up
# start in background(detached mode)
docker compose up -d

将图片上传至NekoImageGallery

有几种方法可以将图片上传至NekoImageGallery：

-

通过网页界面：您可以使用网页界面将图片上传到服务器。网页界面由 NekoImageGallery.App 提供。请确保您已启用 Admin API 并在配置文件中设置了您的 Admin Token。

通过API：您可以使用NekoImageGallery提供的上传API来上传图片。通过此方法，可允许服务器本地不保存图片文件而仅仅存储其URL以及元数据。
请确保您已启用 Admin API 并在配置文件中设置了您的 Admin Token。
此方法适用于自动化图片上传或将NekoImageGallery与外部系统进行同步。更多信息请查看 API文档。

📚 API文档

API文档由FastAPI内置的Swagger UI提供。您可以通过访问服务器的/docs或/redoc路径来查看API文档。

⚡ 相关项目

以下项目基于NekoImageGallery工作！

NekoImageGallery.App LiteLoaderQQNT-NekoImageGallerySearch nonebot-plugin-nekoimage

📊仓库信息

Alt

❤️贡献指南

有很多种可以为本项目提供贡献的方式：记录 Bug，提交 Pull Request，报告问题，提出建议等等。

即使您拥有对本仓库的写入权限，您也应该在有需要时创建自己的功能分支并通过 Pull Request 的方式提交您的变更。 这有助于让我们的主仓库保持整洁并使您的个人工作流程不可见。

我们也很感兴趣听到您关于这个项目未来的反馈。您可以通过 Issues 追踪器提交建议或功能请求。为了使这个过程更加有效，我们希望这些内容包含更多信息，以更清晰地定义它们。

Copyright 2025 EdgeNeko

Licensed under GPLv3 license.