Skip to content

Commit

Permalink
docs: Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
hv0905 committed Dec 24, 2023
1 parent 83af853 commit 7fcfdb4
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 23 deletions.
82 changes: 61 additions & 21 deletions readme.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
# NekoImageGallery

An online AI image search engine based on the Clip model and Qdrant vector database. Supports keyword search and similar image search.
An online AI image search engine based on the Clip model and Qdrant vector database. Supports keyword search and similar
image search.

[中文文档](readme_cn.md)

## ✨ Features

- Use the Clip model to generate 768-dimensional vectors for each image as the basis for search. No need for manual annotation or classification, unlimited classification categories.
- Use the Clip model to generate 768-dimensional vectors for each image as the basis for search. No need for manual
annotation or classification, unlimited classification categories.
- OCR Text search is supported, use PaddleOCR to extract text from images and use BERT to generate text vectors for
search.
- Use Qdrant vector database for efficient vector search.

## 📷Screenshots
Expand All @@ -16,68 +20,88 @@ An online AI image search engine based on the Clip model and Qdrant vector datab
![Screenshot3](web/screenshots/3.png)
![Screenshot4](web/screenshots/4.png)

> The above screenshots may contain copyrighted images from different artists, please do not use them for other purposes.
> The above screenshots may contain copyrighted images from different artists, please do not use them for other
> purposes.
## ✈️ Deployment

### Local Deployment

#### Deploy Qdrant Database

Please deploy the Qdrant database according to the [Qdrant documentation](https://qdrant.tech/documentation/quick-start/). It is recommended to use Docker for deployment.
Please deploy the Qdrant database according to
the [Qdrant documentation](https://qdrant.tech/documentation/quick-start/). It is recommended to use Docker for
deployment.

If you don't want to deploy Qdrant yourself, you can use the [online service provided by Qdrant](https://qdrant.tech/documentation/cloud/).
If you don't want to deploy Qdrant yourself, you can use
the [online service provided by Qdrant](https://qdrant.tech/documentation/cloud/).

#### Deploy NekoImageGallery

1. Clone the project directory to your own PC or server.
2. It is highly recommended to install the dependencies required for this project in a Python venv virtual environment. Run the following command:
2. It is highly recommended to install the dependencies required for this project in a Python venv virtual environment.
Run the following command:
```shell
python -m venv .venv
. .venv/bin/activate
```
3. Install PyTorch. Follow the [PyTorch documentation](https://pytorch.org/get-started/locally/) to install the torch version suitable for your system using pip.
> If you want to use CUDA acceleration for inference, be sure to install a CUDA-supported PyTorch version in this step. After installation, you can use `torch.cuda.is_available()` to confirm whether CUDA is available.
3. Install PyTorch. Follow the [PyTorch documentation](https://pytorch.org/get-started/locally/) to install the torch
version suitable for your system using pip.
> If you want to use CUDA acceleration for inference, be sure to install a CUDA-supported PyTorch version in this
step. After installation, you can use `torch.cuda.is_available()` to confirm whether CUDA is available.
4. Install other dependencies required for this project:
```shell
pip install -r requirements.txt
```
5. Modify the project configuration file inside `config/`, you can edit `default.env` directly, but it's recommended to create a new file named `local.env` and override the configuration in `default.env`.
5. Modify the project configuration file inside `config/`, you can edit `default.env` directly, but it's recommended to
create a new file named `local.env` and override the configuration in `default.env`.
6. Initialize the Qdrant database by running the following command:
```shell
python main.py --init-database
```
This operation will create a collection in the Qdrant database with the same name as `config.QDRANT_COLL` to store image vectors.
7. (Optional) In development deployment and small-scale deployment, you can use the built-in static file indexing and service functions of this application. Use the following command to index your local image directory:
This operation will create a collection in the Qdrant database with the same name as `config.QDRANT_COLL` to store
image vectors.
7. (Optional) In development deployment and small-scale deployment, you can use the built-in static file indexing and
service functions of this application. Use the following command to index your local image directory:
```shell
python main.py --local-index <path-to-your-image-directory>
```
This operation will copy all image files in the `<path-to-your-image-directory>` directory to the `config.STATIC_FILE_PATH` directory (default is `./static`) and write the image information to the Qdrant database.
This operation will copy all image files in the `<path-to-your-image-directory>` directory to
the `config.STATIC_FILE_PATH` directory (default is `./static`) and write the image information to the Qdrant
database.
Then run the following command to generate thumbnails for all images in the static directory:
```shell
python main.py --local-create-thumbnail
```
If you want to deploy on a large scale, you can use OSS storage services like `MinIO` to store image files in OSS and then write the image information to the Qdrant database.
If you want to deploy on a large scale, you can use OSS storage services like `MinIO` to store image files in OSS and
then write the image information to the Qdrant database.
8. Run this application:
```shell
python main.py
```
You can use `--host` to specify the IP address you want to bind to (default is 0.0.0.0) and `--port` to specify the port you want to bind to (default is 8000).
9. (Optional) Deploy the front-end application: [NekoImageGallery.App](https://github.com/hv0905/NekoImageGallery.App) is a simple web front-end application for this project. If you want to deploy it, please refer to its [deployment documentation](https://github.com/hv0905/NekoImageGallery.App).
You can use `--host` to specify the IP address you want to bind to (default is 0.0.0.0) and `--port` to specify the
port you want to bind to (default is 8000).
9. (Optional) Deploy the front-end application: [NekoImageGallery.App](https://github.com/hv0905/NekoImageGallery.App)
is a simple web front-end application for this project. If you want to deploy it, please refer to
its [deployment documentation](https://github.com/hv0905/NekoImageGallery.App).
### Docker Compose Containerized Deployment
> [!WARNING]
> Docker compose support is in an alpha state, and may not work for everyone(especially CUDA acceleration).
> Please make sure you are familiar with [Docker documentation](https://docs.docker.com/) before using this deployment method.
> Please make sure you are familiar with [Docker documentation](https://docs.docker.com/) before using this deployment
> method.
> If you encounter any problems during deployment, please submit an issue.
#### Prepare `nvidia-container-runtime`
If you want to use CUDA acceleration, you need to install `nvidia-container-runtime` on your system. Please refer to the [official documentation](https://docs.docker.com/config/containers/resource_constraints/#gpu) for installation.
If you want to use CUDA acceleration, you need to install `nvidia-container-runtime` on your system. Please refer to
the [official documentation](https://docs.docker.com/config/containers/resource_constraints/#gpu) for installation.
> Related Document:
> Related Document:
> 1. https://docs.docker.com/config/containers/resource_constraints/#gpu
> 2. https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker
> 3. https://nvidia.github.io/nvidia-container-runtime/
Expand All @@ -88,11 +112,27 @@ If you want to use CUDA acceleration, you need to install `nvidia-container-runt
2. Run the following command to start the server:
```shell
# start in foreground
docker-compose up
docker compose up
# start in background(detached mode)
docker-compose up -d
docker compose up -d
```
## 📊 Repository Summary
![Alt](https://repobeats.axiom.co/api/embed/ac080afa0d2d8af0345f6818b9b7c35bf8de1d31.svg "Repobeats analytics image")
## ♥ Contributing
There are many ways to contribute to the project: logging bugs, submitting pull requests, reporting issues, and creating
suggestions.
Even if you with push access on the repository, you should create a personal feature branches when you need them.
This keeps the main repository clean and your workflow cruft out of sight.
We're also interested in your feedback on the future of this project. You can submit a suggestion or feature request
through the issue tracker. To make this process more effective, we're asking that these include more information to help
define them more clearly.
## Copyright
Copyright 2023 EdgeNeko
Expand Down
17 changes: 15 additions & 2 deletions readme_cn.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
## ✨特性

- 使用Clip模型为每张图片生成768维向量作为搜索依据。无需人工标注或分类,无限分类类别。
- 支持OCR文本搜索,使用PaddleOCR提取图片文本并使用BERT模型生成文本特征向量。
- 使用Qdrant向量数据库进行高效的向量搜索。

## 📷截图
Expand Down Expand Up @@ -88,11 +89,23 @@
2. 运行下面命令启动docker-compose
```shell
# start in foreground
docker-compose up
docker compose up
# start in background(detached mode)
docker-compose up -d
docker compose up -d
```

## 📊仓库信息

![Alt](https://repobeats.axiom.co/api/embed/ac080afa0d2d8af0345f6818b9b7c35bf8de1d31.svg "Repobeats analytics image")

## ❤️贡献指南

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

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

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

## Copyright

Expand Down

0 comments on commit 7fcfdb4

Please sign in to comment.