Upload 97 files

.dockerignore

@@ -0,0 +1,43 @@
+# Include any files or directories that you don't want to be copied to your
+# container here (e.g., local build artifacts, temporary files, etc.).
+#
+# For more help, visit the .dockerignore file reference guide at
+# https://docs.docker.com/engine/reference/builder/#dockerignore-file
+
+**/.DS_Store
+**/__pycache__
+**/.venv
+**/.classpath
+**/.dockerignore
+**/.env
+**/.git
+**/.gitignore
+**/.project
+**/.settings
+**/.toolstarget
+**/.vs
+**/.vscode
+**/*.*proj.user
+**/*.dbmdl
+**/*.jfm
+**/.idea
+**/bin
+**/charts
+**/docker-compose*
+**/compose*
+**/*Dockerfile*
+**/node_modules
+**/npm-debug.log
+**/obj
+**/secrets.dev.yaml
+**/values.dev.yaml
+**/venv
+
+.github/
+static/
+web/
+tests/
+pylintrc.toml
+LICENSE
+readme.md
+readme_cn.md

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+web/screenshots/1.png filter=lfs diff=lfs merge=lfs -text
+web/screenshots/2.png filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/bug-report---错误反馈.md

@@ -0,0 +1,28 @@
+---
+name: Bug report / 错误反馈
+about: Create a report to help us improve 报告您在使用本项目过程中遇到的Bug。
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+## Environment
+NekoImageGallery version: Place the version of NekoImageGallery you're using here. 在此处添加您正在使用的NekoImageGallery版本。
+
+Deployment Method: `Local / Docker`
+
+## Describe the bug
+<!-- A clear and concise description of what the bug is. 简要介绍您遇到的问题。-->
+
+## To Reproduce
+<!-- Steps to reproduce the behavior (including config, environment setup if necessary). 简要说明复现此BUG的步骤（必要时包含配置信息，环境信息）-->
+
+## Expected behavior
+<!--A clear and concise description of what you expected to happen. 简要说明您期望应用实现的行为。-->
+
+## Screenshots
+<!-- If applicable, add screenshots to help explain your problem. 必要时可以使用截图说明此BUG。-->
+
+## Additional context
+<!-- Add any other context about the problem here. 在此处补充其它信息（如有必要）-->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Ask a question about the project. 询问有关本项目的问题。
+    url: https://github.com/hv0905/NekoImageGallery/discussions/new?category=q-a
+    about: Ask a question if you encounter a problem when using NekoImageGallery. Please use this option instead of Bug Report unless you are sure your problem is caused by a bug. 询问在您使用NekoImageGallery过程中遇到的问题。请优先使用此选项（而不是Bug Report），除非您认为您的问题是由NekoImageGallery的BUG造成。

.github/ISSUE_TEMPLATE/feature-request---功能请求.md

@@ -0,0 +1,20 @@
+---
+name: Feature request / 功能请求
+about: Suggest an idea for this project 向本项目提交新的功能建议。
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/page_build/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-cayman

.github/workflows/jekyll-gh-pages.yml

@@ -0,0 +1,61 @@
+name: Deploy project pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+    paths: 
+      - '**/*.md'
+      - '**/*.png' # for screenshots
+      - 'page_build/**'
+      - '.github/workflows/**'
+      
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: prepare site src
+        run: |
+          mkdir -p .github/page_build
+          cp *.md .github/page_build/
+          cp web/ .github/page_build/ -r
+          ls -lR .github/page_build/
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./.github/page_build/
+          destination: ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/prod.yml

@@ -0,0 +1,74 @@
+name: Check & deploy to DockerHub
+
+on:
+  push:
+    branches:
+      - 'master'
+    tags:
+      - '*'
+  workflow_dispatch:
+
+jobs:
+  perform-check:
+    uses: ./.github/workflows/test_lint.yml
+    secrets: inherit
+  docker:
+    runs-on: ubuntu-latest
+    environment: DockerHub
+    needs:
+      - perform-check
+    strategy:
+      matrix:
+        configurations:
+          - dockerfile: "Dockerfile"
+            suffixes: |
+              ""
+              "-cuda"
+              "-cuda12.1"
+            args: |
+              CUDA_VERSION=12.1
+          - dockerfile: "Dockerfile"
+            suffixes: '"-cuda11.8"'
+            args: |
+              CUDA_VERSION=11.8
+          - dockerfile: "cpu-only.Dockerfile"
+            suffixes: '"-cpu"'
+            args: ""
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Docker Meta
+        id: docker-meta
+        uses: docker/metadata-action@v5
+        with:
+          images: edgeneko/neko-image-gallery
+          tags: |
+            type=edge,branch=master
+            type=semver,pattern=v{{version}}
+            type=semver,pattern=v{{major}}.{{minor}}
+      - name: Build combined tags
+        id: combine-tags
+        run: |
+          SUFFIXES=(${{ matrix.configurations.suffixes }})
+          echo 'tags<<EOF' >> $GITHUB_OUTPUT
+          for SUFFIX in "${SUFFIXES[@]}"; do
+            echo '${{ steps.docker-meta.outputs.tags }}' | sed 's/$/'"$SUFFIX"'/' >> $GITHUB_OUTPUT
+          done
+          echo EOF >> $GITHUB_OUTPUT
+          
+          printf 'cache_tag=%s' "$(echo '${{ steps.docker-meta.outputs.tags }}' | tail -1 | sed 's/$/'"${SUFFIXES[0]}"'/')" >> $GITHUB_OUTPUT
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          file: ${{ matrix.configurations.dockerfile }}
+          push: true
+          tags: ${{ steps.combine-tags.outputs.tags }}
+          build-args: ${{ matrix.configurations.args }}
+          labels: ${{ steps.docker-meta.outputs.labels }}
+          cache-from: type=registry,ref=${{steps.combine-tags.outputs.cache_tag}}
+          cache-to: type=inline

.github/workflows/test_lint.yml

@@ -0,0 +1,50 @@
+name: Test and Lint Project
+
+on:
+  workflow_call:
+  push:
+    branches-ignore:
+      - 'master'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "3.10", "3.11" ]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      - name: Cache for models
+        id: cache-models
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/huggingface/
+          key: ${{ runner.os }}-models-${{ hashFiles('requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-models-
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+          pip install -r requirements.txt
+          pip install -r requirements.dev.txt
+      - name: Test the code with pytest
+        run: |
+          pytest --cov=app .
+      - name: Upload coverage reports to Codecov with GitHub Action
+        uses: codecov/[email protected]
+        if: ${{ matrix.python-version == '3.11' }} # Only upload coverage reports for the latest Python version
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      - name: Analysing the code with pylint
+        run: |
+          pylint --rc-file pylintrc.toml -j 0 app scripts tests && lint_result=$? || lint_result=$?
+          exit $(( $lint_result & 35 ))
+        

.gitignore

@@ -0,0 +1,246 @@
+### PyCharm template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+static/
+qdrant_data/
+images_metadata/
+local_*/
+.idea

.idea/.gitignore

@@ -0,0 +1,8 @@
+# 默认忽略的文件
+/shelf/
+/workspace.xml
+# 基于编辑器的 HTTP 客户端请求
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

.idea/NekoImageGallery.iml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PackageRequirementsSettings">
+    <option name="versionSpecifier" value="Don't specify version" />
+  </component>
+</module>

.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,14 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="PyPep8NamingInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true">
+      <option name="ignoredErrors">
+        <list>
+          <option value="N802" />
+          <option value="N801" />
+          <option value="N806" />
+        </list>
+      </option>
+    </inspection_tool>
+  </profile>
+</component>

.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.10 (NekoImageGallery)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.10 (NekoImageGallery)" project-jdk-type="Python SDK" />
+</project>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/NekoImageGallery.iml" filepath="$PROJECT_DIR$/.idea/NekoImageGallery.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published
+    by the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

app/Controllers/admin.py

@@ -0,0 +1,164 @@
+from datetime import datetime
+from io import BytesIO
+from pathlib import PurePath
+from typing import Annotated
+from uuid import UUID
+
+from PIL import Image, UnidentifiedImageError
+from fastapi import APIRouter, Depends, HTTPException, params, UploadFile, File
+from loguru import logger
+
+from app.Models.api_models.admin_api_model import ImageOptUpdateModel, DuplicateValidationModel
+from app.Models.api_models.admin_query_params import UploadImageModel
+from app.Models.api_response.admin_api_response import ServerInfoResponse, ImageUploadResponse, \
+    DuplicateValidationResponse
+from app.Models.api_response.base import NekoProtocol
+from app.Models.errors import PointDuplicateError
+from app.Models.img_data import ImageData
+from app.Services.authentication import force_admin_token_verify
+from app.Services.provider import ServiceProvider
+from app.Services.vector_db_context import PointNotFoundError
+from app.config import config
+from app.util.generate_uuid import generate_uuid_from_sha1
+from app.util.local_file_utility import VALID_IMAGE_EXTENSIONS
+
+admin_router = APIRouter(dependencies=[Depends(force_admin_token_verify)], tags=["Admin"])
+
+services: ServiceProvider | None = None
+
+
+@admin_router.delete("/delete/{image_id}",
+                     description="Delete image with the given id from database. "
+                                 "If the image is a local image, it will be moved to `/static/_deleted` folder.")
+async def delete_image(
+        image_id: Annotated[UUID, params.Path(description="The id of the image you want to delete.")]) -> NekoProtocol:
+    try:
+        point = await services.db_context.retrieve_by_id(str(image_id))
+    except PointNotFoundError as ex:
+        raise HTTPException(404, "Cannot find the image with the given ID.") from ex
+    await services.db_context.deleteItems([str(point.id)])
+    logger.success("Image {} deleted from database.", point.id)
+
+    if config.storage.method.enabled:  # local image
+        if point.local:
+            image_files = [itm[0] async for itm in
+                           services.storage_service.active_storage.list_files("", f"{point.id}.*")]
+            assert len(image_files) <= 1
+            if not image_files:
+                logger.warning("Image {} is a local image but not found in static folder.", point.id)
+            else:
+                await services.storage_service.active_storage.move(image_files[0], f"_deleted/{image_files[0].name}")
+                logger.success("Image {} removed.", image_files[0].name)
+        if point.thumbnail_url is not None and (point.local or point.local_thumbnail):
+            thumbnail_file = PurePath(f"thumbnails/{point.id}.webp")
+            if await services.storage_service.active_storage.is_exist(thumbnail_file):
+                await services.storage_service.active_storage.delete(thumbnail_file)
+                logger.success("Thumbnail {} removed.", thumbnail_file.name)
+            else:
+                logger.warning("Thumbnail {} not found.", thumbnail_file.name)
+
+    return NekoProtocol(message="Image deleted.")
+
+
+@admin_router.put("/update_opt/{image_id}", description="Update a image's optional information")
+async def update_image(image_id: Annotated[UUID, params.Path(description="The id of the image you want to delete.")],
+                       model: ImageOptUpdateModel) -> NekoProtocol:
+    if model.empty():
+        raise HTTPException(422, "Nothing to update.")
+    try:
+        point = await services.db_context.retrieve_by_id(str(image_id))
+    except PointNotFoundError as ex:
+        raise HTTPException(404, "Cannot find the image with the given ID.") from ex
+
+    if model.thumbnail_url is not None:
+        if point.local or point.local_thumbnail:
+            raise HTTPException(422, "Cannot change the thumbnail URL of a local image.")
+        point.thumbnail_url = model.thumbnail_url
+    if model.url is not None:
+        if point.local:
+            raise HTTPException(422, "Cannot change the URL of a local image.")
+        point.url = model.url
+    if model.starred is not None:
+        point.starred = model.starred
+    if model.categories is not None:
+        point.categories = model.categories
+
+    await services.db_context.updatePayload(point)
+    logger.success("Image {} updated.", point.id)
+
+    return NekoProtocol(message="Image updated.")
+
+
+IMAGE_MIMES = {
+    "image/jpeg": "jpeg",
+    "image/png": "png",
+    "image/webp": "webp",
+    "image/gif": "gif",
+}
+
+
+@admin_router.post("/upload",
+                   description="Upload image to server. The image will be indexed and stored in the database. If "
+                               "local is set to true, the image will be uploaded to local storage.")
+async def upload_image(image_file: Annotated[UploadFile, File(description="The image to be uploaded.")],
+                       model: Annotated[UploadImageModel, Depends()]) -> ImageUploadResponse:
+    # generate an ID for the image
+    img_type = None
+    if image_file.content_type.lower() in IMAGE_MIMES:
+        img_type = IMAGE_MIMES[image_file.content_type.lower()]
+    elif image_file.filename:
+        extension = PurePath(image_file.filename).suffix.lower()
+        if extension in VALID_IMAGE_EXTENSIONS:
+            img_type = extension[1:]
+    if not img_type:
+        logger.warning("Failed to infer image format of the uploaded image. Content Type: {}, Filename: {}",
+                       image_file.content_type, image_file.filename)
+        raise HTTPException(415, "Unsupported image format.")
+    img_bytes = await image_file.read()
+    try:
+        img_id = await services.upload_service.assign_image_id(img_bytes)
+    except PointDuplicateError as ex:
+        raise HTTPException(409,
+                            f"The uploaded point is already contained in the database! entity id: {ex.entity_id}") \
+            from ex
+    try:
+        image = Image.open(BytesIO(img_bytes))
+        image.verify()
+        image.close()
+    except UnidentifiedImageError as ex:
+        logger.warning("Invalid image file from upload request. id: {}", img_id)
+        raise HTTPException(422, "Cannot open the image file.") from ex
+
+    image_data = ImageData(id=img_id,
+                           url=model.url,
+                           thumbnail_url=model.thumbnail_url,
+                           local=model.local,
+                           categories=model.categories,
+                           starred=model.starred,
+                           format=img_type,
+                           index_date=datetime.now())
+
+    await services.upload_service.queue_upload_image(image_data, img_bytes, model.skip_ocr, model.local_thumbnail)
+    return ImageUploadResponse(message="OK. Image added to upload queue.", image_id=img_id)
+
+
+@admin_router.get("/server_info", description="Get server information")
+async def server_info() -> ServerInfoResponse:
+    return ServerInfoResponse(message="Successfully get server information!",
+                              image_count=await services.db_context.get_counts(exact=True),
+                              index_queue_length=services.upload_service.get_queue_size())
+
+
+@admin_router.post("/duplication_validate",
+                   description="Check if an image exists in the server by its SHA1 hash. If the image exists, "
+                               "the image ID will be returned.\n"
+                               "This is helpful for checking if an image is already in the server without "
+                               "uploading the image.")
+async def duplication_validate(model: DuplicateValidationModel) -> DuplicateValidationResponse:
+    ids = [generate_uuid_from_sha1(t) for t in model.hashes]
+    valid_ids = await services.db_context.validate_ids([str(t) for t in ids])
+    exists_matrix = [str(t) in valid_ids or t in services.upload_service.uploading_ids for t in ids]
+    return DuplicateValidationResponse(
+        exists=exists_matrix,
+        entity_ids=[(str(t) if exists else None) for (t, exists) in zip(ids, exists_matrix)],
+        message="Validation completed.")

app/Controllers/images.py

@@ -0,0 +1,43 @@
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Path, HTTPException, Query
+
+from app.Models.api_response.images_api_response import QueryByIdApiResponse, ImageStatus, QueryImagesApiResponse
+from app.Models.query_params import FilterParams
+from app.Services.authentication import force_access_token_verify
+from app.Services.provider import ServiceProvider
+from app.Services.vector_db_context import PointNotFoundError
+from app.config import config
+
+images_router = APIRouter(dependencies=([Depends(force_access_token_verify)] if config.access_protected else None),
+                          tags=["Images"])
+
+services: ServiceProvider | None = None  # The service provider will be injected in the webapp initialize
+
+
+@images_router.get("/id/{image_id}", description="Query the image info with the given image ID. \n"
+                                                 "This can also be used to check the status"
+                                                 " of an image in the index queue.")
+async def query_image_by_id(image_id: Annotated[UUID, Path(description="The id of the image you want to query.")]):
+    try:
+        return QueryByIdApiResponse(img=await services.db_context.retrieve_by_id(str(image_id)),
+                                    img_status=ImageStatus.MAPPED,
+                                    message="Success query the image with the given ID.")
+    except PointNotFoundError as ex:
+        if services.upload_service and image_id in services.upload_service.uploading_ids:
+            return QueryByIdApiResponse(img=None,
+                                        img_status=ImageStatus.IN_QUEUE,
+                                        message="The image is in the indexing queue.")
+        raise HTTPException(404, "Cannot find the image with the given ID.") from ex
+
+
+@images_router.get("/", description="Query images in order of ID.")
+async def scroll_images(filter_param: Annotated[FilterParams, Depends()],
+                        prev_offset_id: Annotated[UUID, Query(description="The previous offset image ID.")] = None,
+                        count: Annotated[int, Query(ge=1, le=100, description="The number of images to query.")] = 15):
+    # validate the offset ID
+    if prev_offset_id is not None and len(await services.db_context.validate_ids([str(prev_offset_id)])) == 0:
+        raise HTTPException(404, "The previous offset ID is invalid.")
+    images, offset = await services.db_context.scroll_points(str(prev_offset_id), count, filter_param=filter_param)
+    return QueryImagesApiResponse(images=images, next_page_offset=offset, message="Success query images.")

app/Controllers/search.py

@@ -0,0 +1,214 @@
+from io import BytesIO
+from typing import Annotated, List
+from uuid import uuid4, UUID
+
+from PIL import Image
+from fastapi import APIRouter, HTTPException
+from fastapi.params import File, Query, Path, Depends
+from loguru import logger
+
+from app.Models.api_models.search_api_model import AdvancedSearchModel, CombinedSearchModel, SearchBasisEnum
+from app.Models.api_response.search_api_response import SearchApiResponse
+from app.Models.query_params import SearchPagingParams, FilterParams
+from app.Models.search_result import SearchResult
+from app.Services.authentication import force_access_token_verify
+from app.Services.provider import ServiceProvider
+from app.config import config
+from app.util.calculate_vectors_cosine import calculate_vectors_cosine
+
+search_router = APIRouter(dependencies=([Depends(force_access_token_verify)] if config.access_protected else None),
+                          tags=["Search"])
+
+services: ServiceProvider | None = None  # The service provider will be injected in the webapp initialize
+
+
+class SearchBasisParams:
+    def __init__(self,
+                 basis: Annotated[SearchBasisEnum, Query(
+                     description="The basis used to search the image.")] = SearchBasisEnum.vision):
+        if basis == SearchBasisEnum.ocr and not config.ocr_search.enable:
+            raise HTTPException(400, "OCR search is not enabled.")
+        self.basis = basis
+
+
+async def result_postprocessing(resp: SearchApiResponse) -> SearchApiResponse:
+    if not config.storage.method.enabled:
+        return resp
+    for item in resp.result:
+        if item.img.local:
+            img_extension = item.img.format or item.img.url.split('.')[-1]
+            img_remote_filename = f"{item.img.id}.{img_extension}"
+            item.img.url = await services.storage_service.active_storage.presign_url(img_remote_filename)
+        if item.img.thumbnail_url is not None and (item.img.local or item.img.local_thumbnail):
+            thumbnail_remote_filename = f"thumbnails/{item.img.id}.webp"
+            item.img.thumbnail_url = await services.storage_service.active_storage.presign_url(
+                thumbnail_remote_filename)
+    return resp
+
+
+@search_router.get("/text/{prompt}", description="Search images by text prompt")
+async def textSearch(
+        prompt: Annotated[
+            str, Path(max_length=100, description="The image prompt text you want to search.")],
+        basis: Annotated[SearchBasisParams, Depends(SearchBasisParams)],
+        filter_param: Annotated[FilterParams, Depends(FilterParams)],
+        paging: Annotated[SearchPagingParams, Depends(SearchPagingParams)],
+        exact: Annotated[bool, Query(
+            description="If using OCR search, this option will require the ocr text contains **exactly** the "
+                        "criteria you have given. This won't take any effect in vision search.")] = False
+) -> SearchApiResponse:
+    logger.info("Text search request received, prompt: {}", prompt)
+    text_vector = services.transformers_service.get_text_vector(prompt) if basis.basis == SearchBasisEnum.vision \
+        else services.transformers_service.get_bert_vector(prompt)
+    if basis.basis == SearchBasisEnum.ocr and exact:
+        filter_param.ocr_text = prompt
+    results = await services.db_context.querySearch(text_vector,
+                                                    query_vector_name=services.db_context.vector_name_for_basis(
+                                                        basis.basis),
+                                                    filter_param=filter_param,
+                                                    top_k=paging.count,
+                                                    skip=paging.skip)
+    return await result_postprocessing(
+        SearchApiResponse(result=results, message=f"Successfully get {len(results)} results.", query_id=uuid4()))
+
+
+@search_router.post("/image", description="Search images by image")
+async def imageSearch(
+        image: Annotated[bytes, File(max_length=10 * 1024 * 1024, media_type="image/*",
+                                     description="The image you want to search.")],
+        filter_param: Annotated[FilterParams, Depends(FilterParams)],
+        paging: Annotated[SearchPagingParams, Depends(SearchPagingParams)]
+) -> SearchApiResponse:
+    fakefile = BytesIO(image)
+    img = Image.open(fakefile)
+    logger.info("Image search request received")
+    image_vector = services.transformers_service.get_image_vector(img)
+    results = await services.db_context.querySearch(image_vector,
+                                                    top_k=paging.count,
+                                                    skip=paging.skip,
+                                                    filter_param=filter_param)
+    return await result_postprocessing(
+        SearchApiResponse(result=results, message=f"Successfully get {len(results)} results.", query_id=uuid4()))
+
+
+@search_router.get("/similar/{image_id}",
+                   description="Search images similar to the image with given id. "
+                               "Won't include the given image itself in the result.")
+async def similarWith(
+        image_id: Annotated[UUID, Path(description="The id of the image you want to search.")],
+        basis: Annotated[SearchBasisParams, Depends(SearchBasisParams)],
+        filter_param: Annotated[FilterParams, Depends(FilterParams)],
+        paging: Annotated[SearchPagingParams, Depends(SearchPagingParams)]
+) -> SearchApiResponse:
+    logger.info("Similar search request received, id: {}", image_id)
+    results = await services.db_context.querySimilar(search_id=str(image_id),
+                                                     top_k=paging.count,
+                                                     skip=paging.skip,
+                                                     filter_param=filter_param,
+                                                     query_vector_name=services.db_context.vector_name_for_basis(
+                                                         basis.basis))
+    return await result_postprocessing(
+        SearchApiResponse(result=results, message=f"Successfully get {len(results)} results.", query_id=uuid4()))
+
+
+@search_router.post("/advanced", description="Search with multiple criteria")
+async def advancedSearch(
+        model: AdvancedSearchModel,
+        basis: Annotated[SearchBasisParams, Depends(SearchBasisParams)],
+        filter_param: Annotated[FilterParams, Depends(FilterParams)],
+        paging: Annotated[SearchPagingParams, Depends(SearchPagingParams)]) -> SearchApiResponse:
+    logger.info("Advanced search request received: {}", model)
+    result = await process_advanced_and_combined_search_query(model, basis, filter_param, paging)
+    return await result_postprocessing(
+        SearchApiResponse(result=result, message=f"Successfully get {len(result)} results.", query_id=uuid4()))
+
+
+@search_router.post("/combined", description="Search with combined criteria")
+async def combinedSearch(
+        model: CombinedSearchModel,
+        basis: Annotated[SearchBasisParams, Depends(SearchBasisParams)],
+        filter_param: Annotated[FilterParams, Depends(FilterParams)],
+        paging: Annotated[SearchPagingParams, Depends(SearchPagingParams)]) -> SearchApiResponse:
+    if not config.ocr_search.enable:
+        raise HTTPException(400, "You used combined search, but it needs OCR search which is not "
+                                 "enabled.")
+    logger.info("Combined search request received: {}", model)
+    result = await process_advanced_and_combined_search_query(model, basis, filter_param, paging, True)
+    calculate_and_sort_by_combined_scores(model, basis, result)
+    result = result[:paging.count] if len(result) > paging.count else result
+    return await result_postprocessing(
+        SearchApiResponse(result=result, message=f"Successfully get {len(result)} results.", query_id=uuid4()))
+
+
+@search_router.get("/random", description="Get random images")
+async def randomPick(
+        filter_param: Annotated[FilterParams, Depends(FilterParams)],
+        paging: Annotated[SearchPagingParams, Depends(SearchPagingParams)],
+        seed: Annotated[int | None, Query(
+            description="The seed for random pick. This is helpful for generating a reproducible random pick.")] = None,
+) -> SearchApiResponse:
+    logger.info("Random pick request received")
+    random_vector = services.transformers_service.get_random_vector(seed)
+    result = await services.db_context.querySearch(random_vector, top_k=paging.count, skip=paging.skip,
+                                                   filter_param=filter_param)
+    return await result_postprocessing(
+        SearchApiResponse(result=result, message=f"Successfully get {len(result)} results.", query_id=uuid4()))
+
+
+# @search_router.get("/recall/{query_id}", description="Recall the query with given queryId")
+# async def recallQuery(query_id: str):
+#     raise NotImplementedError()
+
+async def process_advanced_and_combined_search_query(model: AdvancedSearchModel,
+                                                     basis: SearchBasisParams,
+                                                     filter_param: FilterParams,
+                                                     paging: SearchPagingParams,
+                                                     is_combined_search=False) -> List[SearchResult]:
+    match basis.basis:
+        case SearchBasisEnum.ocr:
+            positive_vectors = [services.transformers_service.get_bert_vector(t) for t in model.criteria]
+            negative_vectors = [services.transformers_service.get_bert_vector(t) for t in model.negative_criteria]
+        case SearchBasisEnum.vision:
+            positive_vectors = [services.transformers_service.get_text_vector(t) for t in model.criteria]
+            negative_vectors = [services.transformers_service.get_text_vector(t) for t in model.negative_criteria]
+        case _:  # pragma: no cover
+            raise NotImplementedError()
+    # In order to ensure the query effect of the combined query, modify the actual top_k
+    _query_top_k = min(max(30, paging.count * 3), 100) if is_combined_search else paging.count
+    result = await services.db_context.querySimilar(
+        query_vector_name=services.db_context.vector_name_for_basis(basis.basis),
+        positive_vectors=positive_vectors,
+        negative_vectors=negative_vectors,
+        mode=model.mode,
+        filter_param=filter_param,
+        with_vectors=is_combined_search,
+        top_k=_query_top_k,
+        skip=paging.skip)
+    return result
+
+
+def calculate_and_sort_by_combined_scores(model: CombinedSearchModel,
+                                          basis: SearchBasisParams,
+                                          result: List[SearchResult]) -> None:
+    # Use a different method to calculate the extra prompt vector based on the basis
+    match basis.basis:
+        case SearchBasisEnum.ocr:
+            extra_prompt_vector = services.transformers_service.get_text_vector(model.extra_prompt)
+        case SearchBasisEnum.vision:
+            extra_prompt_vector = services.transformers_service.get_bert_vector(model.extra_prompt)
+        case _:  # pragma: no cover
+            raise NotImplementedError()
+    # Calculate combined_similar_score (original score * similar_score) and write to SearchResult.score
+    for itm in result:
+        match basis.basis:
+            case SearchBasisEnum.ocr:
+                extra_vector = itm.img.image_vector
+            case SearchBasisEnum.vision:
+                extra_vector = itm.img.text_contain_vector
+            case _:  # pragma: no cover
+                raise NotImplementedError()
+        if extra_vector is not None:
+            similar_score = calculate_vectors_cosine(extra_vector, extra_prompt_vector)
+            itm.score = (1 + similar_score) * itm.score
+    # Finally, sort the result by combined_similar_score
+    result.sort(key=lambda i: i.score, reverse=True)

app/Models/api_models/admin_api_model.py

@@ -0,0 +1,31 @@
+from typing import Optional, Annotated
+
+from pydantic import BaseModel, Field, StringConstraints
+
+
+class ImageOptUpdateModel(BaseModel):
+    starred: Optional[bool] = Field(None,
+                                    description="Whether the image is starred or not. Leave empty to keep the value "
+                                                "unchanged.")
+    categories: Optional[list[str]] = Field(None,
+                                            description="The categories of the image. Leave empty to keep the value "
+                                                        "unchanged.")
+    url: Optional[str] = Field(None,
+                               description="The url of the image. Leave empty to keep the value unchanged. Changing "
+                                           "the url of a local image is not allowed.")
+
+    thumbnail_url: Optional[str] = Field(None,
+                                         description="The url of the thumbnail. Leave empty to keep the value "
+                                                     "unchanged. Changing the thumbnail_url of an image with a local "
+                                                     "thumbnail is not allowed.")
+
+    def empty(self) -> bool:
+        return all([item is None for item in self.model_dump().values()])
+
+
+Sha1HashString = Annotated[
+    str, StringConstraints(min_length=40, max_length=40, pattern=r"[0-9a-f]+", to_lower=True, strip_whitespace=True)]
+
+
+class DuplicateValidationModel(BaseModel):
+    hashes: list[Sha1HashString] = Field(description="The SHA1 hash of the image.", min_length=1)

app/Models/api_models/admin_query_params.py

@@ -0,0 +1,48 @@
+from enum import Enum
+from typing import Optional
+
+from fastapi import Query, HTTPException
+
+
+class UploadImageThumbnailMode(str, Enum):
+    IF_NECESSARY = "if_necessary"
+    ALWAYS = "always"
+    NEVER = "never"
+
+
+class UploadImageModel:
+    def __init__(self,
+                 url: Optional[str] = Query(None,
+                                            description="The image's url. If the image is local, this field will be "
+                                                        "ignored. Otherwise it is required."),
+                 thumbnail_url: Optional[str] = Query(None,
+                                                      description="The image's thumbnail url. If the image is local "
+                                                                  "or local_thumbnail's value is always, "
+                                                                  "this field will be ignored. Currently setting a "
+                                                                  "external thumbnail for a local image is "
+                                                                  "unsupported due to compatibility issues."),
+                 categories: Optional[str] = Query(None,
+                                                   description="The categories of the image. The entries should be "
+                                                               "seperated by comma."),
+                 starred: bool = Query(False, description="If the image is starred."),
+                 local: bool = Query(False,
+                                     description="When set to true, the image will be uploaded to local storage. "
+                                                 "Otherwise, it will only be indexed in the database."),
+                 local_thumbnail: UploadImageThumbnailMode =
+                 Query(default=None,
+                       description="Whether to generate thumbnail locally. Possible values:\n"
+                                   "- `if_necessary`: Only generate thumbnail if the image is larger than 500KB. "
+                                   "This is the default value if `local=True`\n"
+                                   " - `always`: Always generate thumbnail.\n"
+                                   " - `never`: Never generate thumbnail. This is the default value if `local=False`."),
+                 skip_ocr: bool = Query(False, description="Whether to skip the OCR process.")):
+        self.url = url
+        self.thumbnail_url = thumbnail_url
+        self.categories = [t.strip() for t in categories.split(',') if t.strip()] if categories else None
+        self.starred = starred
+        self.local = local
+        self.skip_ocr = skip_ocr
+        self.local_thumbnail = local_thumbnail if (local_thumbnail is not None) else (
+            UploadImageThumbnailMode.IF_NECESSARY if local else UploadImageThumbnailMode.NEVER)
+        if not self.url and not self.local:
+            raise HTTPException(422, "A correspond url must be provided for a non-local image.")

app/Models/api_models/search_api_model.py

@@ -0,0 +1,30 @@
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class SearchBasisEnum(str, Enum):
+    vision = "vision"
+    ocr = "ocr"
+
+
+class SearchModelEnum(str, Enum):
+    average = "average"
+    best = "best"
+
+
+class AdvancedSearchModel(BaseModel):
+    criteria: list[str] = Field([],
+                                description="The positive criteria you want to search with",
+                                max_length=16,
+                                min_length=1)
+    negative_criteria: list[str] = Field([],
+                                         description="The negative criteria you want to search with",
+                                         max_length=16)
+    mode: SearchModelEnum = Field(SearchModelEnum.average,
+                                  description="The mode you want to use to combine the criteria.")
+
+
+class CombinedSearchModel(AdvancedSearchModel):
+    extra_prompt: str = Field(max_length=100,
+                              description="The secondary prompt used for filtering the image.")

app/Models/api_response/admin_api_response.py

@@ -0,0 +1,21 @@
+from uuid import UUID
+
+from pydantic import Field
+
+from .base import NekoProtocol
+
+
+class ServerInfoResponse(NekoProtocol):
+    image_count: int
+    index_queue_length: int
+
+
+class DuplicateValidationResponse(NekoProtocol):
+    entity_ids: list[UUID | None] = Field(
+        description="The image id for each hash. If the image does not exist in the server, the value will be null.")
+    exists: list[bool] = Field(
+        description="Whether the image exists in the server. True if the image exists, False otherwise.")
+
+
+class ImageUploadResponse(NekoProtocol):
+    image_id: UUID

app/Models/api_response/base.py

@@ -0,0 +1,25 @@
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class NekoProtocol(BaseModel):
+    message: str
+
+
+class WelcomeApiAuthenticationResponse(BaseModel):
+    required: bool
+    passed: bool
+
+
+class WelcomeApiAdminPortalAuthenticationResponse(BaseModel):
+    available: bool
+    passed: bool
+
+
+class WelcomeApiResponse(NekoProtocol):
+    server_time: datetime
+    wiki: dict[str, str]
+    authorization: WelcomeApiAuthenticationResponse
+    admin_api: WelcomeApiAdminPortalAuthenticationResponse
+    available_basis: list[str]

app/Models/api_response/images_api_response.py

@@ -0,0 +1,25 @@
+from enum import Enum
+
+from pydantic import Field
+
+from app.Models.api_response.base import NekoProtocol
+from app.Models.img_data import ImageData
+
+
+class ImageStatus(str, Enum):
+    MAPPED = "mapped"
+    IN_QUEUE = "in_queue"
+
+
+class QueryByIdApiResponse(NekoProtocol):
+    img_status: ImageStatus = Field(description="The status of the image.\n"
+                                                "Warning: If NekoImageGallery is deployed in a cluster, "
+                                                "the `in_queue` might not be accurate since the index queue "
+                                                "is independent of each service instance.")
+    img: ImageData | None = Field(description="The mapped image data. Only available when `img_status = mapped`.")
+
+
+class QueryImagesApiResponse(NekoProtocol):
+    images: list[ImageData] = Field(description="The list of images.")
+    next_page_offset: str | None = Field(description="The offset ID for the next page query. "
+                                                     "If there are no more images, this field will be null.")

app/Models/api_response/search_api_response.py

@@ -0,0 +1,8 @@
+from .base import NekoProtocol
+from ..search_result import SearchResult
+from uuid import UUID
+
+
+class SearchApiResponse(NekoProtocol):
+    query_id: UUID
+    result: list[SearchResult]

app/Models/errors.py

@@ -0,0 +1,10 @@
+from uuid import UUID
+
+
+class PointDuplicateError(ValueError):
+    def __init__(self, message: str, entity_id: UUID | None = None):
+        self.message = message
+        self.entity_id = entity_id
+        super().__init__(message)
+
+    pass

app/Models/img_data.py

@@ -0,0 +1,53 @@
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from numpy import ndarray
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class ImageData(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra='ignore')
+
+    id: UUID
+    url: Optional[str] = None
+    thumbnail_url: Optional[str] = None
+    ocr_text: Optional[str] = None
+    image_vector: Optional[ndarray] = Field(None, exclude=True)
+    text_contain_vector: Optional[ndarray] = Field(None, exclude=True)
+    index_date: datetime
+    width: Optional[int] = None
+    height: Optional[int] = None
+    aspect_ratio: Optional[float] = None
+    starred: Optional[bool] = False
+    categories: Optional[list[str]] = []
+    local: Optional[bool] = False
+    local_thumbnail: Optional[bool] = False
+    format: Optional[str] = None  # required for s3 local storage
+
+    @property
+    def ocr_text_lower(self) -> str | None:
+        if self.ocr_text is None:
+            return None
+        return self.ocr_text.lower()
+
+    @property
+    def payload(self):
+        result = self.model_dump(exclude={'id', 'index_date'})
+        # Qdrant database cannot accept datetime object, so we have to convert it to string
+        result['index_date'] = self.index_date.isoformat()
+        # Qdrant doesn't support case-insensitive search, so we need to store a lowercase version of the text
+        result['ocr_text_lower'] = self.ocr_text_lower
+        return result
+
+    @classmethod
+    def from_payload(cls, img_id: str, payload: dict,
+                     image_vector: Optional[ndarray] = None, text_contain_vector: Optional[ndarray] = None):
+        # Convert the datetime string back to datetime object
+        index_date = datetime.fromisoformat(payload['index_date'])
+        del payload['index_date']
+        return cls(id=UUID(img_id),
+                   index_date=index_date,
+                   **payload,
+                   image_vector=image_vector if image_vector is not None else None,
+                   text_contain_vector=text_contain_vector if text_contain_vector is not None else None)

app/Models/query_params.py

@@ -0,0 +1,56 @@
+from typing import Annotated
+
+from fastapi.params import Query
+
+
+class SearchPagingParams:
+    def __init__(
+            self,
+            count: Annotated[int, Query(ge=1, le=100, description="The number of results you want to get.")] = 10,
+            skip: Annotated[int, Query(ge=0, description="The number of results you want to skip.")] = 0
+    ):
+        self.count = count
+        self.skip = skip
+
+
+class FilterParams:
+    def __init__(
+            self,
+            preferred_ratio: Annotated[
+                float | None, Query(gt=0, description="The preferred aspect ratio of the image.")] = None,
+            ratio_tolerance: Annotated[
+                float, Query(gt=0, lt=1, description="The tolerance of the aspect ratio.")] = 0.1,
+            min_width: Annotated[int | None, Query(geq=0, description="The minimum width of the image.")] = None,
+            min_height: Annotated[int | None, Query(geq=0, description="The minimum height of the image.")] = None,
+            starred: Annotated[bool | None, Query(description="Whether the image is starred.")] = None,
+            categories: Annotated[str | None, Query(
+                description="The categories whitelist of the image. Image with **any of** the given categories will "
+                            "be included. The entries should be seperated by comma.",
+                examples=["stickers, cg"])] = None,
+            categories_negative: Annotated[
+                str | None, Query(
+                    description="The categories blacklist of the image. Image with **any of** the given categories "
+                                "will be ignored. The entries should be seperated by comma.",
+                    examples=["stickers, cg"])] = None,
+    ):
+        self.preferred_ratio = preferred_ratio
+        self.ratio_tolerance = ratio_tolerance
+        self.min_width = min_width
+        self.min_height = min_height
+        self.starred = starred
+        self.categories = [t.strip() for t in categories.split(',') if t.strip()] if categories else None
+        self.categories_negative = [t.strip() for t in categories_negative.split(',') if
+                                    t.strip()] if categories_negative else None
+        self.ocr_text = None  # For exact search
+
+    @property
+    def min_ratio(self) -> float | None:
+        if self.preferred_ratio is None:
+            return None
+        return self.preferred_ratio * (1 - self.ratio_tolerance)
+
+    @property
+    def max_ratio(self) -> float | None:
+        if self.preferred_ratio is None:
+            return None
+        return self.preferred_ratio * (1 + self.ratio_tolerance)

app/Models/search_result.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+from .img_data import ImageData
+
+
+class SearchResult(BaseModel):
+    img: ImageData
+    score: float

app/Services/authentication.py

@@ -0,0 +1,32 @@
+from typing import Annotated
+
+from fastapi import HTTPException
+from fastapi.params import Header, Depends
+
+from app.config import config
+
+
+def verify_access_token(token: str | None) -> bool:
+    return (not config.access_protected) or (token is not None and token == config.access_token)
+
+
+def permissive_access_token_verify(
+        x_access_token: Annotated[str | None, Header(
+            description="Access token set in configuration (if access_protected is enabled)")] = None) -> bool:
+    return verify_access_token(x_access_token)
+
+
+def force_access_token_verify(token_passed: Annotated[bool, Depends(permissive_access_token_verify)]):
+    if not token_passed:
+        raise HTTPException(status_code=401, detail="Access token is not present or invalid.")
+
+
+def permissive_admin_token_verify(
+        x_admin_token: Annotated[str | None, Header(
+            description="Admin token set in configuration (if admin_api_enable is enabled)")] = None) -> bool:
+    return config.admin_api_enable and x_admin_token == config.admin_token
+
+
+def force_admin_token_verify(token_passed: Annotated[bool, Depends(permissive_admin_token_verify)]):
+    if not token_passed:
+        raise HTTPException(status_code=401, detail="Admin token is not present or invalid.")

app/Services/index_service.py

@@ -0,0 +1,60 @@
+from PIL import Image
+from fastapi.concurrency import run_in_threadpool
+
+from app.Models.errors import PointDuplicateError
+from app.Models.img_data import ImageData
+from app.Services.lifespan_service import LifespanService
+from app.Services.ocr_services import OCRService
+from app.Services.transformers_service import TransformersService
+from app.Services.vector_db_context import VectorDbContext
+from app.config import config
+
+
+class IndexService(LifespanService):
+    def __init__(self, ocr_service: OCRService, transformers_service: TransformersService, db_context: VectorDbContext):
+        self._ocr_service = ocr_service
+        self._transformers_service = transformers_service
+        self._db_context = db_context
+
+    def _prepare_image(self, image: Image.Image, image_data: ImageData, skip_ocr=False):
+        image_data.width = image.width
+        image_data.height = image.height
+        image_data.aspect_ratio = float(image.width) / image.height
+
+        if image.mode != 'RGB':
+            image = image.convert('RGB')  # to reduce convert in next steps
+        else:
+            image = image.copy()
+        image_data.image_vector = self._transformers_service.get_image_vector(image)
+        if not skip_ocr and config.ocr_search.enable:
+            image_data.ocr_text = self._ocr_service.ocr_interface(image)
+            if image_data.ocr_text != "":
+                image_data.text_contain_vector = self._transformers_service.get_bert_vector(image_data.ocr_text)
+            else:
+                image_data.ocr_text = None
+
+    # currently, here only need just a simple check
+    async def _is_point_duplicate(self, image_data: list[ImageData]) -> bool:
+        image_id_list = [str(item.id) for item in image_data]
+        result = await self._db_context.validate_ids(image_id_list)
+        return len(result) != 0
+
+    async def index_image(self, image: Image.Image, image_data: ImageData, skip_ocr=False, skip_duplicate_check=False,
+                          background=False):
+        if not skip_duplicate_check and (await self._is_point_duplicate([image_data])):
+            raise PointDuplicateError("The uploaded points are contained in the database!", image_data.id)
+
+        if background:
+            await run_in_threadpool(self._prepare_image, image, image_data, skip_ocr)
+        else:
+            self._prepare_image(image, image_data, skip_ocr)
+
+        await self._db_context.insertItems([image_data])
+
+    async def index_image_batch(self, image: list[Image.Image], image_data: list[ImageData],
+                                skip_ocr=False, allow_overwrite=False):
+        if not allow_overwrite and (await self._is_point_duplicate(image_data)):
+            raise PointDuplicateError("The uploaded points are contained in the database!")
+        for img, img_data in zip(image, image_data):
+            self._prepare_image(img, img_data, skip_ocr)
+        await self._db_context.insertItems(image_data)

app/Services/lifespan_service.py

@@ -0,0 +1,6 @@
+class LifespanService:
+    async def on_load(self):
+        pass
+
+    async def on_exit(self):
+        pass

app/Services/ocr_services.py

@@ -0,0 +1,115 @@
+from time import time
+
+import numpy as np
+import torch
+from PIL import Image
+from loguru import logger
+
+from app.Services.lifespan_service import LifespanService
+from app.config import config
+
+
+class OCRService(LifespanService):
+    def __init__(self):
+        self._device = config.device
+        if self._device == "auto":
+            self._device = "cuda" if torch.cuda.is_available() else "cpu"
+
+    @staticmethod
+    def _image_preprocess(img: Image.Image) -> Image.Image:
+        if img.mode != 'RGB':
+            img = img.convert('RGB')
+        if img.size[0] > 1024 or img.size[1] > 1024:
+            img.thumbnail((1024, 1024), Image.Resampling.LANCZOS)
+        new_img = Image.new('RGB', (1024, 1024), (0, 0, 0))
+        new_img.paste(img, ((1024 - img.size[0]) // 2, (1024 - img.size[1]) // 2))
+        return new_img
+
+    def ocr_interface(self, img: Image.Image, need_preprocess=True) -> str:
+        pass
+
+
+class EasyPaddleOCRService(OCRService):
+    def __init__(self):
+        super().__init__()
+        from easypaddleocr import EasyPaddleOCR
+        self._paddle_ocr_module = EasyPaddleOCR(use_angle_cls=True,
+                                                needWarmUp=True,
+                                                devices=self._device,
+                                                warmup_size=(960, 960),
+                                                model_local_dir=config.model.easypaddleocr if
+                                                config.model.easypaddleocr else None)
+        logger.success("EasyPaddleOCR loaded successfully")
+
+    @staticmethod
+    def _image_preprocess(img: Image.Image) -> Image.Image:
+        # Optimized `easypaddleocr` doesn't require scaling preprocess
+        if img.mode != 'RGB':
+            img = img.convert('RGB')
+        return img
+
+    def _easy_paddleocr_process(self, img: Image.Image) -> str:
+        _, ocr_result, _ = self._paddle_ocr_module.ocr(np.array(img))
+        if ocr_result:
+            return "".join(itm[0] for itm in ocr_result if float(itm[1]) > config.ocr_search.ocr_min_confidence)
+        return ""
+
+    def ocr_interface(self, img: Image.Image, need_preprocess=True) -> str:
+        start_time = time()
+        logger.info("Processing text with EasyPaddleOCR...")
+        res = self._easy_paddleocr_process(self._image_preprocess(img) if need_preprocess else img)
+        logger.success("OCR processed done. Time elapsed: {:.2f}s", time() - start_time)
+        return res
+
+
+class EasyOCRService(OCRService):
+    def __init__(self):
+        super().__init__()
+        # noinspection PyPackageRequirements
+        import easyocr  # pylint: disable=import-error
+        self._easy_ocr_module = easyocr.Reader(config.ocr_search.ocr_language,
+                                               gpu=self._device == "cuda")
+        logger.success("easyOCR loaded successfully")
+
+    def _easyocr_process(self, img: Image.Image) -> str:
+        ocr_result = self._easy_ocr_module.readtext(np.array(img))
+        return " ".join(itm[1] for itm in ocr_result if itm[2] > config.ocr_search.ocr_min_confidence)
+
+    def ocr_interface(self, img: Image.Image, need_preprocess=True) -> str:
+        start_time = time()
+        logger.info("Processing text with easyOCR...")
+        res = self._easyocr_process(self._image_preprocess(img) if need_preprocess else img)
+        logger.success("OCR processed done. Time elapsed: {:.2f}s", time() - start_time)
+        return res
+
+
+class PaddleOCRService(OCRService):
+    def __init__(self):
+        super().__init__()
+        # noinspection PyPackageRequirements
+        import paddleocr  # pylint: disable=import-error
+        self._paddle_ocr_module = paddleocr.PaddleOCR(lang="ch", use_angle_cls=True,
+                                                      use_gpu=self._device == "cuda")
+        logger.success("PaddleOCR loaded successfully")
+
+    def _paddleocr_process(self, img: Image.Image) -> str:
+        ocr_result = self._paddle_ocr_module.ocr(np.array(img), cls=True)
+        if ocr_result[0]:
+            return "".join(itm[1][0] for itm in ocr_result[0] if itm[1][1] > config.ocr_search.ocr_min_confidence)
+        return ""
+
+    def ocr_interface(self, img: Image.Image, need_preprocess=True) -> str:
+        start_time = time()
+        logger.info("Processing text with PaddleOCR...")
+        res = self._paddleocr_process(self._image_preprocess(img) if need_preprocess else img)
+        logger.success("OCR processed done. Time elapsed: {:.2f}s", time() - start_time)
+        return res
+
+
+class DisabledOCRService(OCRService):
+    def __init__(self):
+        super().__init__()
+        logger.warning("OCR search is disabled. Skipping OCR model loading.")
+
+    def ocr_interface(self, img: Image.Image, need_preprocess=True) -> str:
+        raise NotImplementedError("OCR module is disabled. Consider enable it in config.")

app/Services/provider.py

@@ -0,0 +1,56 @@
+import asyncio
+from loguru import logger
+
+from .index_service import IndexService
+from .lifespan_service import LifespanService
+from .storage import StorageService
+from .transformers_service import TransformersService
+from .upload_service import UploadService
+from .vector_db_context import VectorDbContext
+from ..config import config, environment
+
+
+class ServiceProvider:
+    def __init__(self):
+        self.transformers_service = TransformersService()
+        self.db_context = VectorDbContext()
+        self.ocr_service = None
+
+        if config.ocr_search.enable and (environment.local_indexing or config.admin_api_enable):
+            match config.ocr_search.ocr_module:
+                case "easyocr":
+                    from .ocr_services import EasyOCRService
+
+                    self.ocr_service = EasyOCRService()
+                case "easypaddleocr":
+                    from .ocr_services import EasyPaddleOCRService
+
+                    self.ocr_service = EasyPaddleOCRService()
+                case "paddleocr":
+                    from .ocr_services import PaddleOCRService
+
+                    self.ocr_service = PaddleOCRService()
+                case _:
+                    raise NotImplementedError(f"OCR module {config.ocr_search.ocr_module} not implemented.")
+        else:
+            from .ocr_services import DisabledOCRService
+
+            self.ocr_service = DisabledOCRService()
+        logger.info(f"OCR service '{type(self.ocr_service).__name__}' initialized.")
+
+        self.index_service = IndexService(self.ocr_service, self.transformers_service, self.db_context)
+        self.storage_service = StorageService()
+        logger.info(f"Storage service '{type(self.storage_service.active_storage).__name__}' initialized.")
+
+        self.upload_service = UploadService(self.storage_service, self.db_context, self.index_service)
+        logger.info(f"Upload service '{type(self.upload_service).__name__}' initialized")
+
+    async def onload(self):
+        tasks = [service.on_load() for service_name in dir(self)
+                 if isinstance((service := getattr(self, service_name)), LifespanService)]
+        await asyncio.gather(*tasks)
+
+    async def onexit(self):
+        tasks = [service.on_exit() for service_name in dir(self)
+                 if isinstance((service := getattr(self, service_name)), LifespanService)]
+        await asyncio.gather(*tasks)

app/Services/storage/__init__.py

@@ -0,0 +1,27 @@
+from app.Services.lifespan_service import LifespanService
+from app.Services.storage.base import BaseStorage
+from app.Services.storage.disabled_storage import DisabledStorage
+from app.Services.storage.local_storage import LocalStorage
+from app.Services.storage.s3_compatible_storage import S3Storage
+from app.config import config, StorageMode
+
+
+class StorageService(LifespanService):
+    def __init__(self):
+        self.active_storage = None
+        match config.storage.method:
+            case StorageMode.LOCAL:
+                self.active_storage = LocalStorage()
+            case StorageMode.S3:
+                self.active_storage = S3Storage()
+            case StorageMode.DISABLED:
+                self.active_storage = DisabledStorage()
+            case _:
+                raise NotImplementedError(f"Storage method {config.storage.method} not implemented. "
+                                          f"Available methods: local, s3")
+
+    async def on_load(self):
+        await self.active_storage.on_load()
+
+    async def on_exit(self):
+        await self.active_storage.on_exit()

app/Services/storage/base.py

@@ -0,0 +1,146 @@
+import abc
+import os
+from typing import TypeVar, Generic, TypeAlias, Optional, AsyncGenerator
+
+from app.Services.lifespan_service import LifespanService
+
+FileMetaDataT = TypeVar('FileMetaDataT')
+
+PathLikeType: TypeAlias = str | os.PathLike
+LocalFilePathType: TypeAlias = PathLikeType | bytes
+RemoteFilePathType: TypeAlias = PathLikeType
+LocalFileMetaDataType: TypeAlias = FileMetaDataT
+RemoteFileMetaDataType: TypeAlias = FileMetaDataT
+
+
+class BaseStorage(LifespanService, abc.ABC, Generic[FileMetaDataT]):
+    def __init__(self):
+        self.static_dir: os.PathLike
+        self.thumbnails_dir: os.PathLike
+        self.deleted_dir: os.PathLike
+        self.file_metadata: FileMetaDataT
+
+    @abc.abstractmethod
+    async def is_exist(self,
+                       remote_file: RemoteFilePathType) -> bool:
+        """
+        Check if a remote_file exists.
+        :param remote_file: The file path relative to static_dir
+        :return: True if the file exists, False otherwise
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def size(self,
+                   remote_file: RemoteFilePathType) -> int:
+        """
+        Get the size of a file in static_dir
+        :param remote_file: The file path relative to static_dir
+        :return: file's size
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def url(self,
+                  remote_file: RemoteFilePathType) -> str:
+        """
+        Get the original URL of a file in static_dir.
+        This url will be placed in the payload field of the qdrant.
+        :param remote_file: The file path relative to static_dir
+        :return: file's "original URL"
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def presign_url(self,
+                          remote_file: RemoteFilePathType,
+                          expire_second: int = 3600) -> str:
+        """
+        Get the presign URL of a file in static_dir.
+        :param remote_file: The file path relative to static_dir
+        :param expire_second: Valid time for presign url
+        :return: file's "presign URL"
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def fetch(self,
+                    remote_file: RemoteFilePathType) -> bytes:
+        """
+        Fetch a file from static_dir
+        :param remote_file: The file path relative to static_dir
+        :return: file's content
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def upload(self,
+                     local_file: "LocalFilePathType",
+                     remote_file: RemoteFilePathType) -> None:
+        """
+        Move a local picture file to the static_dir.
+        :param local_file: The absolute path to the local file or bytes.
+        :param remote_file: The file path relative to static_dir
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def copy(self,
+                   old_remote_file: RemoteFilePathType,
+                   new_remote_file: RemoteFilePathType) -> None:
+        """
+        Copy a file in static_dir.
+        :param old_remote_file: The file path relative to static_dir
+        :param new_remote_file: The file path relative to static_dir
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def move(self,
+                   old_remote_file: RemoteFilePathType,
+                   new_remote_file: RemoteFilePathType) -> None:
+        """
+        Move a file in static_dir.
+        :param old_remote_file: The file path relative to static_dir
+        :param new_remote_file: The file path relative to static_dir
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def delete(self,
+                     remote_file: RemoteFilePathType) -> None:
+        """
+        Move a file in static_dir.
+        :param remote_file: The file path relative to static_dir
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def list_files(self,
+                         path: RemoteFilePathType,
+                         pattern: Optional[str] = "*",
+                         batch_max_files: Optional[int] = None,
+                         valid_extensions: Optional[set[str]] = None) \
+            -> AsyncGenerator[list[RemoteFilePathType], None]:
+        """
+        Asynchronously generates a list of files from a given base directory path that match a specified pattern and set
+         of file extensions.
+
+        :param path: The relative base directory path from which relative to static_dir to start listing files.
+        :param pattern: A glob pattern to filter files based on their names. Defaults to '*' which selects all files.
+        :param batch_max_files: The maximum number of files to return. If None, all matching files are returned.
+        :param valid_extensions: An extra set of file extensions to include (e.g., {".jpg", ".png"}).
+               If None, files are not filtered by extension.
+        :return: An asynchronous generator yielding lists of RemoteFilePathType objects representing the matching files.
+
+        Usage example:
+        async for batch in list_files(base_path=".", pattern="*", max_files=100, valid_extensions={".jpg", ".png"}):
+            print(f"Batch: {batch}")
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def update_metadata(self,
+                              local_file_metadata: LocalFileMetaDataType,
+                              remote_file_metadata: RemoteFileMetaDataType) -> None:
+        raise NotImplementedError

app/Services/storage/disabled_storage.py

@@ -0,0 +1,43 @@
+from typing import Optional, AsyncGenerator
+
+from app.Services.storage import BaseStorage
+from app.Services.storage.base import RemoteFilePathType, LocalFileMetaDataType, RemoteFileMetaDataType, \
+    LocalFilePathType
+
+
+class DisabledStorage(BaseStorage):  # pragma: no cover
+    async def size(self, remote_file: RemoteFilePathType) -> int:
+        raise NotImplementedError
+
+    async def url(self, remote_file: RemoteFilePathType) -> str:
+        raise NotImplementedError
+
+    async def presign_url(self, remote_file: RemoteFilePathType, expire_second: int = 3600) -> str:
+        raise NotImplementedError
+
+    async def fetch(self, remote_file: RemoteFilePathType) -> bytes:
+        raise NotImplementedError
+
+    async def upload(self, local_file: "LocalFilePathType", remote_file: RemoteFilePathType) -> None:
+        raise NotImplementedError
+
+    async def copy(self, old_remote_file: RemoteFilePathType, new_remote_file: RemoteFilePathType) -> None:
+        raise NotImplementedError
+
+    async def move(self, old_remote_file: RemoteFilePathType, new_remote_file: RemoteFilePathType) -> None:
+        raise NotImplementedError
+
+    async def delete(self, remote_file: RemoteFilePathType) -> None:
+        raise NotImplementedError
+
+    async def update_metadata(self, local_file_metadata: LocalFileMetaDataType,
+                              remote_file_metadata: RemoteFileMetaDataType) -> None:
+        raise NotImplementedError
+
+    async def list_files(self, path: RemoteFilePathType, pattern: Optional[str] = "*",
+                         batch_max_files: Optional[int] = None, valid_extensions: Optional[set[str]] = None) -> \
+            AsyncGenerator[list[RemoteFilePathType], None]:
+        raise NotImplementedError
+
+    async def is_exist(self, remote_file: RemoteFilePathType) -> bool:
+        raise NotImplementedError

app/Services/storage/exception.py

@@ -0,0 +1,30 @@
+class StorageExtension(Exception):
+    pass
+
+
+class LocalFileNotFoundError(StorageExtension):
+    pass
+
+
+class LocalFileExistsError(StorageExtension):
+    pass
+
+
+class LocalFilePermissionError(StorageExtension):
+    pass
+
+
+class RemoteFileNotFoundError(StorageExtension):
+    pass
+
+
+class RemoteFileExistsError(StorageExtension):
+    pass
+
+
+class RemoteFilePermissionError(StorageExtension):
+    pass
+
+
+class RemoteConnectError(StorageExtension):
+    pass

app/Services/storage/local_storage.py

@@ -0,0 +1,145 @@
+import os
+from asyncio import to_thread
+from pathlib import Path as syncPath
+from shutil import copy2, move
+from typing import Optional, AsyncGenerator
+
+import aiofiles
+from loguru import logger
+
+from app.Services.storage.base import BaseStorage, FileMetaDataT, RemoteFilePathType, LocalFilePathType
+from app.Services.storage.exception import RemoteFileNotFoundError, LocalFileNotFoundError, RemoteFilePermissionError, \
+    LocalFilePermissionError, LocalFileExistsError, RemoteFileExistsError
+from app.config import config
+from app.util.local_file_utility import glob_local_files
+
+
+def transform_exception(param: str):
+    file_not_found_exp_map = {"local": LocalFileNotFoundError, "remote": RemoteFileNotFoundError}
+    permission_exp_map = {"remote": RemoteFilePermissionError, "local": LocalFilePermissionError}
+    file_exist_map = {"local": LocalFileExistsError, "remote": RemoteFileExistsError}
+
+    def decorator(func):
+        async def wrapper(*args, **kwargs):
+            try:
+                return await func(*args, **kwargs)
+            except FileNotFoundError as ex:
+                raise file_not_found_exp_map[param] from ex
+            except PermissionError as ex:
+                raise permission_exp_map[param] from ex
+            except FileExistsError as ex:
+                raise file_exist_map[param] from ex
+
+        return wrapper
+
+    return decorator
+
+
+class LocalStorage(BaseStorage[FileMetaDataT: None]):
+    def __init__(self):
+        super().__init__()
+        self.static_dir = syncPath(os.path.abspath(config.storage.local.path))
+        self.thumbnails_dir = self.static_dir / "thumbnails"
+        self.deleted_dir = self.static_dir / "_deleted"
+        self.file_metadata = None
+        self.file_path_warp = lambda x: self.static_dir / syncPath(x)
+
+    def file_path_wrap(self, path: RemoteFilePathType) -> syncPath:
+        return self.static_dir / syncPath(path)
+
+    async def on_load(self):
+        if not self.static_dir.is_dir():
+            self.static_dir.mkdir(parents=True)
+            logger.warning(f"static_dir {self.static_dir} not found, created.")
+        if not self.thumbnails_dir.is_dir():
+            self.thumbnails_dir.mkdir(parents=True)
+            logger.warning(f"thumbnails_dir {self.thumbnails_dir} not found, created.")
+        if not self.deleted_dir.is_dir():
+            self.deleted_dir.mkdir(parents=True)
+            logger.warning(f"deleted_dir {self.deleted_dir} not found, created.")
+
+    async def is_exist(self,
+                       remote_file: "RemoteFilePathType") -> bool:
+        return self.file_path_warp(remote_file).exists()
+
+    @transform_exception("remote")
+    async def size(self,
+                   remote_file: "RemoteFilePathType") -> int:
+        _file = self.file_path_warp(remote_file)
+        return self.file_path_warp(remote_file).stat().st_size
+
+    # noinspection PyMethodMayBeStatic
+    async def url(self,
+                  remote_file: "RemoteFilePathType") -> str:
+        return f"/static/{str(remote_file)}"
+
+    async def presign_url(self,
+                          remote_file: "RemoteFilePathType",
+                          expire_second: int = 3600) -> str:
+        return f"/static/{str(remote_file)}"
+
+    @transform_exception("remote")
+    async def fetch(self,
+                    remote_file: "RemoteFilePathType") -> bytes:
+        remote_file = self.file_path_warp(remote_file)
+        async with aiofiles.open(str(remote_file), 'rb') as file:
+            return await file.read()
+
+    @transform_exception("local")
+    async def upload(self,
+                     local_file: "LocalFilePathType",
+                     remote_file: "RemoteFilePathType") -> None:
+        remote_file = self.file_path_warp(remote_file)
+        if isinstance(local_file, bytes):
+            async with aiofiles.open(str(remote_file), 'wb') as file:
+                await file.write(local_file)
+        else:
+            await to_thread(copy2, str(local_file), str(remote_file))
+        local_file = f"{len(local_file)} bytes" if isinstance(local_file, bytes) else local_file
+        logger.success(f"Successfully uploaded file {str(local_file)} to {str(remote_file)} via local_storage.")
+
+    @transform_exception("remote")
+    async def copy(self,
+                   old_remote_file: "RemoteFilePathType",
+                   new_remote_file: "RemoteFilePathType") -> None:
+        old_remote_file = self.file_path_warp(old_remote_file)
+        new_remote_file = self.file_path_warp(new_remote_file)
+        await to_thread(copy2, str(old_remote_file), str(new_remote_file))
+        logger.success(f"Successfully copied file {str(old_remote_file)} to {str(new_remote_file)} via local_storage.")
+
+    @transform_exception("remote")
+    async def move(self,
+                   old_remote_file: "RemoteFilePathType",
+                   new_remote_file: "RemoteFilePathType") -> None:
+        old_remote_file = self.file_path_warp(old_remote_file)
+        new_remote_file = self.file_path_warp(new_remote_file)
+        await to_thread(move, str(old_remote_file), str(new_remote_file), copy_function=copy2)
+        logger.success(f"Successfully moved file {str(old_remote_file)} to {str(new_remote_file)} via local_storage.")
+
+    @transform_exception("remote")
+    async def delete(self,
+                     remote_file: "RemoteFilePathType") -> None:
+        remote_file = self.file_path_warp(remote_file)
+        await to_thread(os.remove, str(remote_file))
+        logger.success(f"Successfully deleted file {str(remote_file)} via local_storage.")
+
+    async def list_files(self,
+                         path: RemoteFilePathType,
+                         pattern: Optional[str] = "*",
+                         batch_max_files: Optional[int] = None,
+                         valid_extensions: Optional[set[str]] = None) \
+            -> AsyncGenerator[list[RemoteFilePathType], None]:
+        local_path = self.file_path_warp(path)
+        files = []
+        for file in glob_local_files(local_path, pattern, valid_extensions):
+            files.append(file)
+            if batch_max_files is not None and len(files) == batch_max_files:
+                yield files
+                files = []
+        if files:
+            yield files
+
+    async def update_metadata(self,
+                              local_file_metadata: None,
+                              remote_file_metadata: None) -> None:
+        raise NotImplementedError

app/Services/storage/s3_compatible_storage.py

@@ -0,0 +1,173 @@
+# pylint now reporting `opendal` as a `no-name-in-module` error, so we need to disable it as a temporary workaround
+# Related issue: https://github.com/pylint-dev/pylint/issues/9185
+# Remove below `# pylint` once the issue is resolved
+# pylint: disable=import-error,no-name-in-module
+import os
+import urllib.parse
+from pathlib import PurePosixPath
+from typing import Optional, AsyncGenerator
+
+import aiofiles
+from loguru import logger
+from opendal import AsyncOperator
+from opendal.exceptions import NotFound, PermissionDenied, AlreadyExists
+from wcmatch import glob
+
+from app.Services.storage.base import BaseStorage, FileMetaDataT, RemoteFilePathType, LocalFilePathType, \
+    LocalFileMetaDataType, RemoteFileMetaDataType
+from app.Services.storage.exception import LocalFileNotFoundError, RemoteFileNotFoundError, RemoteFilePermissionError, \
+    RemoteFileExistsError
+from app.config import config
+from app.util.local_file_utility import VALID_IMAGE_EXTENSIONS
+
+
+def transform_exception(func):
+    async def wrapper(*args, **kwargs):
+        try:
+            return await func(*args, **kwargs)
+        except FileNotFoundError as ex:
+            raise LocalFileNotFoundError from ex
+        except NotFound as ex:
+            raise RemoteFileNotFoundError from ex
+        except PermissionDenied as ex:
+            raise RemoteFilePermissionError from ex
+        except AlreadyExists as ex:
+            raise RemoteFileExistsError from ex
+
+    return wrapper
+
+
+class S3Storage(BaseStorage[FileMetaDataT: None]):
+    def __init__(self):
+        super().__init__()
+
+        # Paths
+        self.static_dir = PurePosixPath(config.storage.s3.path)
+        self.thumbnails_dir = self.static_dir / "thumbnails"
+        self.deleted_dir = self.static_dir / "_deleted"
+
+        self.file_metadata = None
+        self.bucket = config.storage.s3.bucket
+        self.region = config.storage.s3.region
+        self.endpoint = config.storage.s3.endpoint_url
+
+        self.op = AsyncOperator("s3",
+                                root=str(self.static_dir),
+                                bucket=self.bucket,
+                                region=self.region,
+                                endpoint=self.endpoint,
+                                access_key_id=config.storage.s3.access_key_id,
+                                secret_access_key=config.storage.s3.secret_access_key)
+
+        self._file_path_str_warp = lambda x: str(PurePosixPath(x))
+
+    @staticmethod
+    def _file_path_str_wrap(p: RemoteFilePathType):
+        return str(PurePosixPath(p))
+
+    async def is_exist(self,
+                       remote_file: "RemoteFilePathType") -> bool:
+        try:
+            # the easiest way to confirm the existence of a file
+            await self.op.stat(self._file_path_str_warp(remote_file))
+            return True
+        except NotFound:
+            return False
+
+    @transform_exception
+    async def size(self,
+                   remote_file: "RemoteFilePathType") -> int:
+        _stat = await self.op.stat(self._file_path_str_warp(remote_file))
+        return _stat.content_length
+
+    @transform_exception
+    async def url(self,
+                  remote_file: "RemoteFilePathType") -> str:
+        return f"{self._res_endpoint}/{str(self.static_dir)}/{str(remote_file)}"
+
+    @transform_exception
+    async def presign_url(self,
+                          remote_file: "RemoteFilePathType",
+                          expire_second: int = 3600) -> str:
+        _presign = await self.op.presign_read(self._file_path_str_warp(remote_file), expire_second)
+        return _presign.url
+
+    @transform_exception
+    async def fetch(self,
+                    remote_file: "RemoteFilePathType") -> bytes:
+        with await self.op.read(self._file_path_str_warp(remote_file)) as f:
+            return bytes(f)
+
+    @transform_exception
+    async def upload(self,
+                     local_file: "LocalFilePathType",
+                     remote_file: "RemoteFilePathType") -> None:
+        if isinstance(local_file, bytes):
+            b = local_file
+        else:
+            async with aiofiles.open(local_file, "rb") as f:
+                b = await f.read()
+        await self.op.write(self._file_path_str_warp(remote_file), b)
+        local_file = f"{len(local_file)} bytes" if isinstance(local_file, bytes) else local_file
+        logger.success(f"Successfully uploaded file {str(local_file)} to {str(remote_file)} via s3_storage.")
+
+    @transform_exception
+    async def copy(self,
+                   old_remote_file: "RemoteFilePathType",
+                   new_remote_file: "RemoteFilePathType") -> None:
+        await self.op.copy(self._file_path_str_warp(old_remote_file), self._file_path_str_warp(new_remote_file))
+        logger.success(f"Successfully copied file {str(old_remote_file)} to {str(new_remote_file)} via s3_storage.")
+
+    @transform_exception
+    async def move(self,
+                   old_remote_file: "RemoteFilePathType",
+                   new_remote_file: "RemoteFilePathType") -> None:
+        await self.op.copy(self._file_path_str_warp(old_remote_file), self._file_path_str_warp(new_remote_file))
+        await self.op.delete(self._file_path_str_warp(old_remote_file))
+        logger.success(f"Successfully moved file {str(old_remote_file)} to {str(new_remote_file)} via s3_storage.")
+
+    @transform_exception
+    async def delete(self,
+                     remote_file: "RemoteFilePathType") -> None:
+        await self.op.delete(self._file_path_str_warp(remote_file))
+        logger.success(f"Successfully deleted file {str(remote_file)} via s3_storage.")
+
+    async def list_files(self,
+                         path: RemoteFilePathType,
+                         pattern: Optional[str] = "*",
+                         batch_max_files: Optional[int] = None,
+                         valid_extensions: Optional[set[str]] = None) \
+            -> AsyncGenerator[list[RemoteFilePathType], None]:
+        if valid_extensions is None:
+            valid_extensions = VALID_IMAGE_EXTENSIONS
+        files = []
+        # In opendal, current path should be "" instead of "."
+        _path = "" if self._file_path_str_warp(path) == "." else self._file_path_str_warp(path)
+        async for itm in await self.op.scan(_path):
+            if self._list_files_check(itm.path, pattern, valid_extensions):
+                files.append(PurePosixPath(itm.path))
+                if batch_max_files is not None and len(files) == batch_max_files:
+                    yield files
+                    files = []
+        if files:
+            yield files
+
+    async def update_metadata(self,
+                              local_file_metadata: "LocalFileMetaDataType",
+                              remote_file_metadata: "RemoteFileMetaDataType") -> None:
+        raise NotImplementedError
+
+    @staticmethod
+    def _list_files_check(x: str, pattern: str, valid_extensions: Optional[set[str]] = None) -> bool:
+        matches_pattern = glob.globmatch(x, pattern, flags=glob.GLOBSTAR)
+        has_valid_extension = os.path.splitext(x)[-1] in valid_extensions
+        is_not_directory = not x.endswith("/")
+        return matches_pattern and has_valid_extension and is_not_directory
+
+    @property
+    def _res_endpoint(self):
+        parsed_url = urllib.parse.urlparse(self.endpoint)
+        # If the endpoint is a subdomain of the bucket, then the endpoint is already resolved.
+        if self.bucket in parsed_url.netloc.split('.'):
+            return self.endpoint
+        return f"{self.endpoint}/{self.bucket}"

app/Services/transformers_service.py

@@ -0,0 +1,70 @@
+from time import time
+
+import numpy as np
+import torch
+from PIL import Image
+from loguru import logger
+from numpy import ndarray
+from torch import FloatTensor, no_grad
+from transformers import CLIPProcessor, CLIPModel, BertTokenizer, BertModel
+
+from app.Services.lifespan_service import LifespanService
+from app.config import config
+
+
+class TransformersService(LifespanService):
+    def __init__(self):
+        self.device = config.device
+        if self.device == "auto":
+            self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        logger.info("Using device: {}; CLIP Model: {}, BERT Model: {}",
+                    self.device, config.model.clip, config.model.bert)
+        self._clip_model = CLIPModel.from_pretrained(config.model.clip).to(self.device)
+        self._clip_processor = CLIPProcessor.from_pretrained(config.model.clip)
+        logger.success("CLIP Model loaded successfully")
+        if config.ocr_search.enable:
+            self._bert_model = BertModel.from_pretrained(config.model.bert).to(self.device)
+            self._bert_tokenizer = BertTokenizer.from_pretrained(config.model.bert)
+            logger.success("BERT Model loaded successfully")
+        else:
+            logger.info("OCR search is disabled. Skipping BERT model loading.")
+
+    @no_grad()
+    def get_image_vector(self, image: Image.Image) -> ndarray:
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+        logger.info("Processing image...")
+        start_time = time()
+        inputs = self._clip_processor(images=image, return_tensors="pt").to(self.device)
+        logger.success("Image processed, now Inferring with CLIP model...")
+        outputs: FloatTensor = self._clip_model.get_image_features(**inputs)
+        logger.success("Inference done. Time elapsed: {:.2f}s", time() - start_time)
+        outputs /= outputs.norm(dim=-1, keepdim=True)
+        return outputs.numpy(force=True).reshape(-1)
+
+    @no_grad()
+    def get_text_vector(self, text: str) -> ndarray:
+        logger.info("Processing text...")
+        start_time = time()
+        inputs = self._clip_processor(text=text, return_tensors="pt").to(self.device)
+        logger.success("Text processed, now Inferring with CLIP model...")
+        outputs: FloatTensor = self._clip_model.get_text_features(**inputs)
+        logger.success("Inference done. Time elapsed: {:.2f}s", time() - start_time)
+        outputs /= outputs.norm(dim=-1, keepdim=True)
+        return outputs.numpy(force=True).reshape(-1)
+
+    @no_grad()
+    def get_bert_vector(self, text: str) -> ndarray:
+        start_time = time()
+        logger.info("Inferring with BERT model...")
+        inputs = self._bert_tokenizer(text.strip().lower(), return_tensors="pt", truncation=True).to(self.device)
+        outputs = self._bert_model(**inputs)
+        vector = outputs.last_hidden_state.mean(dim=1).squeeze()
+        logger.success("BERT inference done. Time elapsed: {:.2f}s", time() - start_time)
+        return vector.cpu().numpy()
+
+    @staticmethod
+    def get_random_vector(seed: int | None = None) -> ndarray:
+        generator = np.random.default_rng(seed)
+        vec = generator.uniform(-1, 1, 768)
+        return vec

app/Services/upload_service.py

@@ -0,0 +1,108 @@
+import asyncio
+import gc
+import io
+import pathlib
+from io import BytesIO
+
+from PIL import Image
+from loguru import logger
+
+from app.Models.api_models.admin_query_params import UploadImageThumbnailMode
+from app.Models.errors import PointDuplicateError
+from app.Models.img_data import ImageData
+from app.Services.index_service import IndexService
+from app.Services.lifespan_service import LifespanService
+from app.Services.storage import StorageService
+from app.Services.vector_db_context import VectorDbContext
+from app.config import config
+from app.util.generate_uuid import generate_uuid
+
+
+class UploadService(LifespanService):
+    def __init__(self, storage_service: StorageService, db_context: VectorDbContext, index_service: IndexService):
+        self._storage_service = storage_service
+        self._db_context = db_context
+        self._index_service = index_service
+
+        self._queue = asyncio.Queue(config.admin_index_queue_max_length)
+        self._upload_worker_task = asyncio.create_task(self._upload_worker())
+
+        self.uploading_ids = set()
+        self._processed_count = 0
+
+    async def _upload_worker(self):
+        while True:
+            img_data, *args = await self._queue.get()
+            try:
+                await self._upload_task(img_data, *args)
+                logger.success("Image {} uploaded and indexed. Queue Length: {} [-1]", img_data.id, self._queue.qsize())
+            except Exception as ex:
+                logger.error("Error occurred while uploading image {}", img_data.id)
+                logger.exception(ex)
+            finally:
+                self._queue.task_done()
+                self.uploading_ids.remove(img_data.id)
+                self._processed_count += 1
+                if self._processed_count % 50 == 0:
+                    gc.collect()
+
+    async def _upload_task(self, img_data: ImageData, img_bytes: bytes, skip_ocr: bool,
+                           thumbnail_mode: UploadImageThumbnailMode):
+        img = Image.open(BytesIO(img_bytes))
+        logger.info('Start indexing image {}. Local: {}. Size: {}', img_data.id, img_data.local, len(img_bytes))
+        file_name = f"{img_data.id}.{img_data.format}"
+        thumb_path = f"thumbnails/{img_data.id}.webp"
+        gen_thumb = thumbnail_mode == UploadImageThumbnailMode.ALWAYS or (
+                thumbnail_mode == UploadImageThumbnailMode.IF_NECESSARY and len(img_bytes) > 1024 * 500)
+
+        if img_data.local:
+            img_data.url = await self._storage_service.active_storage.url(file_name)
+        if gen_thumb:
+            img_data.thumbnail_url = await self._storage_service.active_storage.url(
+                f"thumbnails/{img_data.id}.webp")
+            img_data.local_thumbnail = True
+
+        await self._index_service.index_image(img, img_data, skip_ocr=skip_ocr, background=True)
+        logger.success("Image {} indexed.", img_data.id)
+
+        if img_data.local:
+            logger.info("Start uploading image {} to local storage.", img_data.id)
+            await self._storage_service.active_storage.upload(img_bytes, file_name)
+            logger.success("Image {} uploaded to local storage.", img_data.id)
+        if gen_thumb:
+            logger.info("Start generate and upload thumbnail for {}.", img_data.id)
+            img.thumbnail((256, 256), resample=Image.Resampling.LANCZOS)
+            img_byte_arr = BytesIO()
+            img.save(img_byte_arr, 'WebP', save_all=True)
+            await self._storage_service.active_storage.upload(img_byte_arr.getvalue(), thumb_path)
+            logger.success("Thumbnail for {} generated and uploaded!", img_data.id)
+
+        img.close()
+
+    async def queue_upload_image(self, img_data: ImageData, img_bytes: bytes, skip_ocr: bool,
+                                 thumbnail_mode: UploadImageThumbnailMode):
+        self.uploading_ids.add(img_data.id)
+        await self._queue.put((img_data, img_bytes, skip_ocr, thumbnail_mode))
+        logger.success("Image {} added to upload queue. Queue Length: {} [+1]", img_data.id, self._queue.qsize())
+
+    async def assign_image_id(self, img_file: pathlib.Path | io.BytesIO | bytes):
+        img_id = generate_uuid(img_file)
+        # check for duplicate points
+        if img_id in self.uploading_ids or len(await self._db_context.validate_ids([str(img_id)])) != 0:
+            logger.warning("Duplicate upload request for image id: {}", img_id)
+            raise PointDuplicateError(f"The uploaded point is already contained in the database! entity id: {img_id}",
+                                      img_id)
+        return img_id
+
+    async def sync_upload_image(self, img_data: ImageData, img_bytes: bytes, skip_ocr: bool,
+                                thumbnail_mode: UploadImageThumbnailMode):
+        await self._upload_task(img_data, img_bytes, skip_ocr, thumbnail_mode)
+
+    def get_queue_size(self):
+        return self._queue.qsize()
+
+    async def on_exit(self):  # pragma: no cover  Hard to test in UT.
+        if self.get_queue_size() != 0:
+            logger.warning("There are still {} images in the upload queue. Waiting for upload process to be completed.",
+                           self.get_queue_size())
+        await self._queue.join()

app/Services/vector_db_context.py

@@ -0,0 +1,334 @@
+from typing import Optional
+
+import numpy
+from grpc.aio import AioRpcError
+from httpx import HTTPError
+from loguru import logger
+from qdrant_client import AsyncQdrantClient
+from qdrant_client.http import models
+from qdrant_client.models import RecommendStrategy
+
+from app.Models.api_models.search_api_model import SearchModelEnum, SearchBasisEnum
+from app.Models.img_data import ImageData
+from app.Models.query_params import FilterParams
+from app.Models.search_result import SearchResult
+from app.Services.lifespan_service import LifespanService
+from app.config import config, QdrantMode
+from app.util.retry_deco_async import wrap_object, retry_async
+
+
+class PointNotFoundError(ValueError):
+    def __init__(self, point_id: str):
+        self.point_id = point_id
+        super().__init__(f"Point {point_id} not found.")
+
+
+class VectorDbContext(LifespanService):
+    IMG_VECTOR = "image_vector"
+    TEXT_VECTOR = "text_contain_vector"
+    AVAILABLE_POINT_TYPES = models.Record | models.ScoredPoint | models.PointStruct
+
+    def __init__(self):
+        match config.qdrant.mode:
+            case QdrantMode.SERVER:
+                self._client = AsyncQdrantClient(host=config.qdrant.host, port=config.qdrant.port,
+                                                 grpc_port=config.qdrant.grpc_port, api_key=config.qdrant.api_key,
+                                                 prefer_grpc=config.qdrant.prefer_grpc)
+                wrap_object(self._client, retry_async((AioRpcError, HTTPError)))
+            case QdrantMode.LOCAL:
+                self._client = AsyncQdrantClient(path=config.qdrant.local_path)
+            case QdrantMode.MEMORY:
+                logger.warning("Using in-memory Qdrant client. Data will be lost after application restart. "
+                               "This should only be used for testing and debugging.")
+                self._client = AsyncQdrantClient(":memory:")
+            case _:
+                raise ValueError("Invalid Qdrant mode.")
+        self.collection_name = config.qdrant.coll
+
+    async def on_load(self):
+        if not await self.check_collection():
+            logger.warning("Collection not found. Initializing...")
+            await self.initialize_collection()
+
+    async def retrieve_by_id(self, image_id: str, with_vectors=False) -> ImageData:
+        """
+        Retrieve an item from database by id. Will raise PointNotFoundError if the given ID doesn't exist.
+        :param image_id: The ID to retrieve.
+        :param with_vectors: Whether to retrieve vectors.
+        :return: The retrieved item.
+        """
+        logger.info("Retrieving item {} from database...", image_id)
+        result = await self._client.retrieve(collection_name=self.collection_name,
+                                             ids=[image_id],
+                                             with_payload=True,
+                                             with_vectors=with_vectors)
+        if len(result) != 1:
+            logger.error("Point not exist.")
+            raise PointNotFoundError(image_id)
+        return self._get_img_data_from_point(result[0])
+
+    async def retrieve_by_ids(self, image_id: list[str], with_vectors=False) -> list[ImageData]:
+        """
+        Retrieve items from the database by IDs.
+        An exception is thrown if there are items in the IDs that do not exist in the database.
+        :param image_id: The list of IDs to retrieve.
+        :param with_vectors: Whether to retrieve vectors.
+        :return: The list of retrieved items.
+        """
+        logger.info("Retrieving {} items from database...", len(image_id))
+        result = await self._client.retrieve(collection_name=self.collection_name,
+                                             ids=image_id,
+                                             with_payload=True,
+                                             with_vectors=with_vectors)
+        result_point_ids = {t.id for t in result}
+        missing_point_ids = set(image_id) - result_point_ids
+        if len(missing_point_ids) > 0:
+            logger.error("{} points not exist.", len(missing_point_ids))
+            raise PointNotFoundError(str(missing_point_ids))
+        return self._get_img_data_from_points(result)
+
+    async def validate_ids(self, image_id: list[str]) -> list[str]:
+        """
+        Validate a list of IDs. Will return a list of valid IDs.
+        :param image_id: The list of IDs to validate.
+        :return: The list of valid IDs.
+        """
+        logger.info("Validating {} items from database...", len(image_id))
+        result = await self._client.retrieve(collection_name=self.collection_name,
+                                             ids=image_id,
+                                             with_payload=False,
+                                             with_vectors=False)
+        return [t.id for t in result]
+
+    async def querySearch(self, query_vector, query_vector_name: str = IMG_VECTOR,
+                          top_k=10, skip=0, filter_param: FilterParams | None = None) -> list[SearchResult]:
+        logger.info("Querying Qdrant... top_k = {}", top_k)
+        result = await self._client.search(collection_name=self.collection_name,
+                                           query_vector=(query_vector_name, query_vector),
+                                           query_filter=self._get_filters_by_filter_param(filter_param),
+                                           limit=top_k,
+                                           offset=skip,
+                                           with_payload=True)
+        logger.success("Query completed!")
+        return [self._get_search_result_from_scored_point(t) for t in result]
+
+    async def querySimilar(self,
+                           query_vector_name: str = IMG_VECTOR,
+                           search_id: Optional[str] = None,
+                           positive_vectors: Optional[list[numpy.ndarray]] = None,
+                           negative_vectors: Optional[list[numpy.ndarray]] = None,
+                           mode: Optional[SearchModelEnum] = None,
+                           with_vectors: bool = False,
+                           filter_param: FilterParams | None = None,
+                           top_k: int = 10,
+                           skip: int = 0) -> list[SearchResult]:
+        _positive_vectors = [t.tolist() for t in positive_vectors] if positive_vectors is not None else [search_id]
+        _negative_vectors = [t.tolist() for t in negative_vectors] if negative_vectors is not None else None
+        _strategy = None if mode is None else (RecommendStrategy.AVERAGE_VECTOR if
+                                               mode == SearchModelEnum.average else RecommendStrategy.BEST_SCORE)
+        # since only combined_search need return vectors, We can define _combined_search_need_vectors like below
+        _combined_search_need_vectors = [
+            self.IMG_VECTOR if query_vector_name == self.TEXT_VECTOR else self.TEXT_VECTOR] if with_vectors else None
+        logger.info("Querying Qdrant... top_k = {}", top_k)
+        result = await self._client.recommend(collection_name=self.collection_name,
+                                              using=query_vector_name,
+                                              positive=_positive_vectors,
+                                              negative=_negative_vectors,
+                                              strategy=_strategy,
+                                              with_vectors=_combined_search_need_vectors,
+                                              query_filter=self._get_filters_by_filter_param(filter_param),
+                                              limit=top_k,
+                                              offset=skip,
+                                              with_payload=True)
+        logger.success("Query completed!")
+
+        return [self._get_search_result_from_scored_point(t) for t in result]
+
+    async def insertItems(self, items: list[ImageData]):
+        logger.info("Inserting {} items into Qdrant...", len(items))
+
+        points = [self._get_point_from_img_data(t) for t in items]
+
+        response = await self._client.upsert(collection_name=self.collection_name,
+                                             wait=True,
+                                             points=points)
+        logger.success("Insert completed! Status: {}", response.status)
+
+    async def deleteItems(self, ids: list[str]):
+        logger.info("Deleting {} items from Qdrant...", len(ids))
+        response = await self._client.delete(collection_name=self.collection_name,
+                                             points_selector=models.PointIdsList(
+                                                 points=ids
+                                             ),
+                                             )
+        logger.success("Delete completed! Status: {}", response.status)
+
+    async def updatePayload(self, new_data: ImageData):
+        """
+        Update the payload of an existing item in the database.
+        Warning: This method will not update the vector of the item.
+        :param new_data: The new data to update.
+        """
+        response = await self._client.set_payload(collection_name=self.collection_name,
+                                                  payload=new_data.payload,
+                                                  points=[str(new_data.id)],
+                                                  wait=True)
+        logger.success("Update completed! Status: {}", response.status)
+
+    async def updateVectors(self, new_points: list[ImageData]):
+        resp = await self._client.update_vectors(collection_name=self.collection_name,
+                                                 points=[self._get_vector_from_img_data(t) for t in new_points],
+                                                 )
+        logger.success("Update vectors completed! Status: {}", resp.status)
+
+    async def scroll_points(self,
+                            from_id: str | None = None,
+                            count=50,
+                            with_vectors=False,
+                            filter_param: FilterParams | None = None,
+                            ) -> tuple[list[ImageData], str]:
+        resp, next_id = await self._client.scroll(collection_name=self.collection_name,
+                                                  limit=count,
+                                                  offset=from_id,
+                                                  with_vectors=with_vectors,
+                                                  scroll_filter=self._get_filters_by_filter_param(filter_param)
+                                                  )
+
+        return [self._get_img_data_from_point(t) for t in resp], next_id
+
+    async def get_counts(self, exact: bool) -> int:
+        resp = await self._client.count(collection_name=self.collection_name, exact=exact)
+        return resp.count
+
+    async def check_collection(self) -> bool:
+        resp = await self._client.get_collections()
+        resp = [t.name for t in resp.collections]
+        return self.collection_name in resp
+
+    async def initialize_collection(self):
+        if await self.check_collection():
+            logger.warning("Collection already exists. Skip initialization.")
+            return
+        logger.info("Initializing database, collection name: {}", self.collection_name)
+        vectors_config = {
+            self.IMG_VECTOR: models.VectorParams(size=768, distance=models.Distance.COSINE),
+            self.TEXT_VECTOR: models.VectorParams(size=768, distance=models.Distance.COSINE)
+        }
+        await self._client.create_collection(collection_name=self.collection_name,
+                                             vectors_config=vectors_config)
+        logger.success("Collection created!")
+
+    @classmethod
+    def _get_vector_from_img_data(cls, img_data: ImageData) -> models.PointVectors:
+        vector = {}
+        if img_data.image_vector is not None:
+            vector[cls.IMG_VECTOR] = img_data.image_vector.tolist()
+        if img_data.text_contain_vector is not None:
+            vector[cls.TEXT_VECTOR] = img_data.text_contain_vector.tolist()
+        return models.PointVectors(
+            id=str(img_data.id),
+            vector=vector
+        )
+
+    @classmethod
+    def _get_point_from_img_data(cls, img_data: ImageData) -> models.PointStruct:
+        return models.PointStruct(
+            id=str(img_data.id),
+            payload=img_data.payload,
+            vector=cls._get_vector_from_img_data(img_data).vector
+        )
+
+    def _get_img_data_from_point(self, point: AVAILABLE_POINT_TYPES) -> ImageData:
+        return (ImageData
+                .from_payload(point.id,
+                              point.payload,
+                              image_vector=numpy.array(point.vector[self.IMG_VECTOR], dtype=numpy.float32)
+                              if point.vector and self.IMG_VECTOR in point.vector else None,
+                              text_contain_vector=numpy.array(point.vector[self.TEXT_VECTOR], dtype=numpy.float32)
+                              if point.vector and self.TEXT_VECTOR in point.vector else None
+                              ))
+
+    def _get_img_data_from_points(self, points: list[AVAILABLE_POINT_TYPES]) -> list[ImageData]:
+        return [self._get_img_data_from_point(t) for t in points]
+
+    def _get_search_result_from_scored_point(self, point: models.ScoredPoint) -> SearchResult:
+        return SearchResult(img=self._get_img_data_from_point(point), score=point.score)
+
+    @classmethod
+    def vector_name_for_basis(cls, basis: SearchBasisEnum) -> str:
+        match basis:
+            case SearchBasisEnum.vision:
+                return cls.IMG_VECTOR
+            case SearchBasisEnum.ocr:
+                return cls.TEXT_VECTOR
+            case _:
+                raise ValueError("Invalid basis")
+
+    @staticmethod
+    def _get_filters_by_filter_param(filter_param: FilterParams | None) -> models.Filter | None:
+        if filter_param is None:
+            return None
+
+        filters = []
+        neg_filter = []
+        if filter_param.min_width is not None and filter_param.min_width > 0:
+            filters.append(models.FieldCondition(
+                key="width",
+                range=models.Range(
+                    gte=filter_param.min_width
+                )
+            ))
+
+        if filter_param.min_height is not None and filter_param.min_height > 0:
+            filters.append(models.FieldCondition(
+                key="height",
+                range=models.Range(
+                    gte=filter_param.min_height
+                )
+            ))
+
+        if filter_param.min_ratio is not None:
+            filters.append(models.FieldCondition(
+                key="aspect_ratio",
+                range=models.Range(
+                    gte=filter_param.min_ratio,
+                    lte=filter_param.max_ratio
+                )
+            ))
+
+        if filter_param.starred is not None:
+            filters.append(models.FieldCondition(
+                key="starred",
+                match=models.MatchValue(
+                    value=filter_param.starred
+                )
+            ))
+
+        if filter_param.ocr_text is not None:
+            filters.append(models.FieldCondition(
+                key="ocr_text_lower",
+                match=models.MatchText(
+                    text=filter_param.ocr_text.lower()
+                )
+            ))
+
+        if filter_param.categories is not None:
+            filters.append(models.FieldCondition(
+                key="categories",
+                match=models.MatchAny(
+                    any=filter_param.categories
+                )
+            ))
+
+        if filter_param.categories_negative is not None:
+            neg_filter.append(models.FieldCondition(
+                key="categories",
+                match=models.MatchAny(any=filter_param.categories_negative),
+            ))
+
+        if not filters and not neg_filter:
+            return None
+        return models.Filter(
+            must=filters,
+            must_not=neg_filter
+        )

app/__init__.py

@@ -0,0 +1,6 @@
+__title__ = 'NekoImageGallery'
+__description__ = 'An AI-powered natural language & reverse Image Search Engine powered by CLIP & qdrant.'
+__version__ = '1.2.0'
+__author__ = 'EdgeNeko; pk5ls20'
+__author_email__ = '[email protected]'
+__url__ = 'https://github.com/hv0905/NekoImageGallery'