[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-filipradenovic--cnnimageretrieval-pytorch":3,"similar-filipradenovic--cnnimageretrieval-pytorch":106},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":15,"owner_avatar_url":16,"owner_bio":17,"owner_company":18,"owner_location":19,"owner_email":19,"owner_twitter":14,"owner_website":20,"owner_url":21,"languages":22,"stars":27,"forks":28,"last_commit_at":29,"license":30,"difficulty_score":31,"env_os":32,"env_gpu":33,"env_ram":34,"env_deps":35,"category_tags":41,"github_topics":45,"view_count":51,"oss_zip_url":19,"oss_zip_packed_at":19,"status":52,"created_at":53,"updated_at":54,"faqs":55,"releases":90},3696,"filipradenovic\u002Fcnnimageretrieval-pytorch","cnnimageretrieval-pytorch","CNN Image Retrieval in PyTorch: Training and evaluating CNNs for Image Retrieval in PyTorch","cnnimageretrieval-pytorch 是一个基于 PyTorch 框架的开源工具箱，专注于卷积神经网络（CNN）在图像检索领域的训练与评估。它主要解决了如何高效微调预训练 CNN 模型，使其从通用的图像分类任务转化为高精度的图像搜索任务这一核心问题，特别是在缺乏人工标注数据的情况下，也能通过无监督学习实现性能提升。\n\n这款工具非常适合计算机视觉研究人员、AI 开发者以及需要构建自定义图像搜索引擎的技术团队使用。其独特的技术亮点在于完整复现了多篇顶级会议论文的核心算法，支持“无监督微调”和“困难样本挖掘”策略，能够自动从数据中学习特征。此外，它还集成了监督白化（Supervised Whitening）作为后处理步骤，显著优化了全局图像描述符的区分度。用户可以直接利用内置脚本，在牛津和巴黎等标准数据集上快速复现前沿成果，或基于自己的数据进行模型训练与测试，是探索深度学习图像检索技术的实用利器。","## CNN Image Retrieval in PyTorch: Training and evaluating CNNs for Image Retrieval in PyTorch\n\nThis is a Python toolbox that implements the training and testing of the approach described in our papers:\n\n\n**Fine-tuning CNN Image Retrieval with No Human Annotation**,  \nRadenović F., Tolias G., Chum O., \nTPAMI 2018 [[arXiv](https:\u002F\u002Farxiv.org\u002Fabs\u002F1711.02512)]\n\n**CNN Image Retrieval Learns from BoW: Unsupervised Fine-Tuning with Hard Examples**,  \nRadenović F., Tolias G., Chum O., \nECCV 2016 [[arXiv](http:\u002F\u002Farxiv.org\u002Fabs\u002F1604.02426)]\n\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffilipradenovic_cnnimageretrieval-pytorch_readme_61f1d92edb8c.png\" width=\\textwidth\u002F>\n\n---\n\n### What is it?\n\nThis code implements:\n\n1. Training (fine-tuning) CNN for image retrieval\n1. Learning supervised whitening, as post-processing, for global image descriptors\n1. Testing CNN image retrieval on Oxford and Paris datasets\n\n---\n\n### Prerequisites\n\nIn order to run this toolbox you will need:\n\n1. Python3 (tested with Python 3.7.0 on Debian 8.1)\n1. PyTorch deep learning framework (tested with version 1.0.0)\n1. All the rest (data + networks) is automatically downloaded with our scripts\n\n---\n\n### Usage\n\nNavigate (```cd```) to the root of the toolbox ```[YOUR_CIRTORCH_ROOT]```. \nYou can install package with `pip3 install .` if you need. \nMake sure to have desired PyTorch and torchvision packages installed.  \n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Training\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n  \n  Example training script is located in ```YOUR_CIRTORCH_ROOT\u002Fcirtorch\u002Fexamples\u002Ftrain.py```\n  ```\n  python3 -m cirtorch.examples.train [-h] [--training-dataset DATASET] [--no-val]\n                  [--test-datasets DATASETS] [--test-whiten DATASET]\n                  [--test-freq N] [--arch ARCH] [--pool POOL]\n                  [--local-whitening] [--regional] [--whitening]\n                  [--not-pretrained] [--loss LOSS] [--loss-margin LM]\n                  [--image-size N] [--neg-num N] [--query-size N]\n                  [--pool-size N] [--gpu-id N] [--workers N] [--epochs N]\n                  [--batch-size N] [--optimizer OPTIMIZER] [--lr LR]\n                  [--momentum M] [--weight-decay W] [--print-freq N]\n                  [--resume FILENAME]\n                  EXPORT_DIR\n  ```\n\n  For detailed explanation of the options run:\n  ```\n  python3 -m cirtorch.examples.train -h\n  ```\n\n  > **Note**: Data and networks used for training and testing are automatically downloaded when using the example script.\n  \n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Testing\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  Example testing script is located in ```YOUR_CIRTORCH_ROOT\u002Fcirtorch\u002Fexamples\u002Ftest.py```\n  ```\n  python3 -m cirtorch.examples.test [-h] (--network-path NETWORK | --network-offtheshelf NETWORK)\n                 [--datasets DATASETS] [--image-size N]\n                 [--multiscale MULTISCALE] [--whitening WHITENING] [--gpu-id N]\n  ```\n\n  For detailed explanation of the options run:\n  ```\n  python3 -m cirtorch.examples.test -h\n  ```\n\n  > **Note**: Data used for testing are automatically downloaded when using the example script.\n\n\u003C\u002Fdetails>\n\n---\n\n###  Papers implementation\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Training\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  For example, to train our best network described in the TPAMI 2018 paper run the following command. \n  After each epoch, the fine-tuned network will be tested on the revisited Oxford and Paris benchmarks:\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --test-datasets 'roxford5k,rparis6k' --arch 'resnet101' --pool 'gem' --loss 'contrastive' \n              --loss-margin 0.85 --optimizer 'adam' --lr 5e-7 --neg-num 5 --query-size=2000 \n              --pool-size=22000 --batch-size 5 --image-size 362\n  ```\n\n  Networks can be evaluated with learned whitening after each epoch (whitening is estimated at the end of the epoch). To achieve this run the following command. \n  Note that this will significantly slow down the entire training procedure, and you can evaluate networks with learned whitening later on using the example test script.\n\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --test-datasets 'roxford5k,rparis6k' --test-whiten 'retrieval-SfM-30k' \n              --arch 'resnet101' --pool 'gem' --loss 'contrastive' --loss-margin 0.85 \n              --optimizer 'adam' --lr 5e-7 --neg-num 5 --query-size=2000 --pool-size=22000 \n              --batch-size 5 --image-size 362\n  ```\n\n  > **Note**: Adjusted (lower) learning rate is set to achieve similar performance as with [MatConvNet](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval) and [PyTorch-0.3.0](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fv1.0) implementation of the training.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Testing our pretrained networks\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  Pretrained networks trained using the same parameters as in our TPAMI 2018 paper are provided, with precomputed post-processing whitening step. \n  To evaluate them run:\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-path 'retrievalSfM120k-resnet101-gem' \n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k' \n                  --whitening 'retrieval-SfM-120k'\n                  --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n  ```\n  or\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-path 'retrievalSfM120k-vgg16-gem' \n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k' \n                  --whitening 'retrieval-SfM-120k'\n                  --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n  ```\n  The table below shows the performance comparison of networks trained with this framework and the networks used in the paper which were trained with our [CNN Image Retrieval in MatConvNet](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval):\n\n  | Model | Oxford | Paris | ROxf (M) | RPar (M) | ROxf (H) | RPar (H) |\n  |:------|:------:|:------:|:------:|:------:|:------:|:------:|\n  | VGG16-GeM (MatConvNet) | 87.9 | 87.7 | 61.9 | 69.3 | 33.7 | 44.3 |\n  | VGG16-GeM (PyTorch) | 87.3 | 87.8 | 60.9 | 69.3 | 32.9 | 44.2 |\n  | ResNet101-GeM (MatConvNet) | 87.8 | 92.7 | 64.7 | 77.2 | 38.5 | 56.3 |\n  | ResNet101-GeM (PyTorch) | 88.2 | 92.5 | 65.4 | 76.7 | 40.1 | 55.2 |\n  \n  > **Note** (June 2022): We updated download files for [Oxford 5k](https:\u002F\u002Fwww.robots.ox.ac.uk\u002F~vgg\u002Fdata\u002Foxbuildings\u002F) and [Paris 6k](https:\u002F\u002Fwww.robots.ox.ac.uk\u002F~vgg\u002Fdata\u002Fparisbuildings\u002F) images to use images with blurred faces as suggested by the original dataset owners. Bear in mind, \"experiments have shown that one can use the face-blurred version for benchmarking image retrieval with negligible loss of accuracy\".\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Testing your trained networks\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  To evaluate your trained network using single scale and without learning whitening:\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-path YOUR_NETWORK_PATH \n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k'\n  ```\n\n  To evaluate trained network using multi scale evaluation and with learned whitening as post-processing:\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-path YOUR_NETWORK_PATH \n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k'\n                  --whitening 'retrieval-SfM-120k' \n                  --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n  ```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Testing off-the-shelf networks\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  Off-the-shelf networks can be evaluated as well, for example:\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-offtheshelf 'resnet101-gem'\n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k'\n                  --whitening 'retrieval-SfM-120k' \n                  --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n  ```\n  \n\u003C\u002Fdetails>\n\n---\n\n### Networks with projection (FC) layer after global pooling\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Training\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n  \n  An alternative architecture includes a learnable FC (projection) layer after the global pooling. It is important to initialize the parameters of this layer with the result of learned whitening. \n  To train such a setup you should run the following commands (the performance will be evaluated every 5 epochs on `roxford5k` and `rparis6k`):\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --loss 'triplet' --loss-margin 0.5 --optimizer 'adam' --lr 1e-6 \n              --arch 'resnet50' --pool 'gem' --whitening \n              --neg-num 5 --query-size=2000 --pool-size=20000 \n              --batch-size 5 --image-size 1024 --epochs 100 \n              --test-datasets 'roxford5k,rparis6k' --test-freq 5 \n  ```\n  or\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --loss 'triplet' --loss-margin 0.5 --optimizer 'adam' --lr 5e-7 \n              --arch 'resnet101' --pool 'gem' --whitening \n              --neg-num 4 --query-size=2000 --pool-size=20000 \n              --batch-size 5 --image-size 1024 --epochs 100 \n              --test-datasets 'roxford5k,rparis6k' --test-freq 5 \n  ```\n  or\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --loss 'triplet' --loss-margin 0.5 --optimizer 'adam' --lr 5e-7 \n              --arch 'resnet152' --pool 'gem' --whitening \n              --neg-num 3 --query-size=2000 --pool-size=20000 \n              --batch-size 5 --image-size 900 --epochs 100 \n              --test-datasets 'roxford5k,rparis6k' --test-freq 5 \n  ```\n  for `ResNet50`, `ResNet101`, or `ResNet152`, respectively. \n  \n  Implementation details:\n  \n  - The FC layer is initialized with the result of whitening learned in a supervised manner using our training data and off-the-shelf features.\n  - The whitening for this FC layer is precomputed for popular architectures and pooling methods, see [imageretrievalnet.py#L50](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fblob\u002F474b1fe61ff0e8a6f076ef58f7334cf33d7a3773\u002Fcirtorch\u002Fnetworks\u002Fimageretrievalnet.py#L50) for the full list of precomputed FC layers.\n  - When this FC layer is added in the fine-tuning procedure, the performance is highest if the images are with a similar high-resolution at train and test time. \n  - When this FC layer is added, the distribution of pairwise distances changes significantly, so roughly twice larger margin should be used for contrastive loss. In this scenario, triplet loss performs slightly better. \n  - Additional tunning of hyper-parameters can be performed to achieve higher performance or faster training. Note that, in this example, `--neg-num` and `--image-size` hyper-parameters are chosen such that the training can be performed on a single GPU with `16 GB` of memory. \n    \n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Testing our pretrained networks with projection layer\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  Pretrained networks with projection layer are provided, trained both on `retrieval-SfM-120k (rSfM120k)` and [`google-landmarks-2018 (gl18)`](https:\u002F\u002Fwww.kaggle.com\u002Fgoogle\u002Fgoogle-landmarks-dataset) train datasets.\n  For this architecture, there is no need to compute whitening as post-processing step (typically the performance boost is insignificant), although one can do that, as well.\n  For example, multi-scale evaluation of ResNet101 with GeM with projection layer trained on `google-landmarks-2018 (gl18)` dataset using high-resolution images and a triplet loss, is performed with the following script:\n  ```\n  python3 -m cirtorch.examples.test_e2e --gpu-id '0' --network 'gl18-tl-resnet101-gem-w' \n              --datasets 'roxford5k,rparis6k' --multiscale '[1, 2**(1\u002F2), 1\u002F2**(1\u002F2)]'\n  ```\n\n  Multi-scale performance of all available pre-trained networks is given in the following table:\n\n  | Model | ROxf (M) | RPar (M) | ROxf (H) | RPar (H) |\n  |:------|:------:|:------:|:------:|:------:|\n  | [rSfM120k-tl-resnet50-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fretrieval-SfM-120k\u002FrSfM120k-tl-resnet50-gem-w-97bf910.pth)  | 64.7 | 76.3 | 39.0 | 54.9 |\n  | [rSfM120k-tl-resnet101-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fretrieval-SfM-120k\u002FrSfM120k-tl-resnet101-gem-w-a155e54.pth) | 67.8 | 77.6 | 41.7 | 56.3 |\n  | [rSfM120k-tl-resnet152-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fretrieval-SfM-120k\u002FrSfM120k-tl-resnet152-gem-w-f39cada.pth) | 68.8 | 78.0 | 41.3 | 57.2 |\n  | [gl18-tl-resnet50-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fgl18\u002Fgl18-tl-resnet50-gem-w-83fdc30.pth)  | 63.6 | 78.0 | 40.9 | 57.5 |\n  | [gl18-tl-resnet101-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fgl18\u002Fgl18-tl-resnet101-gem-w-a4d43db.pth) | 67.3 | 80.6 | 44.3 | 61.5 |\n  | [gl18-tl-resnet152-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fgl18\u002Fgl18-tl-resnet152-gem-w-21278d5.pth) | 68.7 | 79.7 | 44.2 | 60.3 |\n  \n  > **Note** (June 2022): We updated download files for [Oxford 5k](https:\u002F\u002Fwww.robots.ox.ac.uk\u002F~vgg\u002Fdata\u002Foxbuildings\u002F) and [Paris 6k](https:\u002F\u002Fwww.robots.ox.ac.uk\u002F~vgg\u002Fdata\u002Fparisbuildings\u002F) images to use images with blurred faces as suggested by the original dataset owners. Bear in mind, \"experiments have shown that one can use the face-blurred version for benchmarking image retrieval with negligible loss of accuracy\".\n  \n\u003C\u002Fdetails>\n\n---\n\n### Related publications\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Training (fine-tuning) convolutional neural networks\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  ```\n  @article{RTC18,\n   title = {Fine-tuning {CNN} Image Retrieval with No Human Annotation},\n   author = {Radenovi{\\'c}, F. and Tolias, G. and Chum, O.}\n   journal = {TPAMI},\n   year = {2018}\n  }\n  ```\n  ```\n  @inproceedings{RTC16,\n   title = {{CNN} Image Retrieval Learns from {BoW}: Unsupervised Fine-Tuning with Hard Examples},\n   author = {Radenovi{\\'c}, F. and Tolias, G. and Chum, O.},\n   booktitle = {ECCV},\n   year = {2016}\n  }\n  ```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Revisited benchmarks for Oxford and Paris ('roxford5k' and 'rparis6k')\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  ```\n  @inproceedings{RITAC18,\n   author = {Radenovi{\\'c}, F. and Iscen, A. and Tolias, G. and Avrithis, Y. and Chum, O.},\n   title = {Revisiting Oxford and Paris: Large-Scale Image Retrieval Benchmarking},\n   booktitle = {CVPR},\n   year = {2018}\n  }\n  ```\n  \n\u003C\u002Fdetails>\n\n---\n\n### Versions\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>master (devolopment)\u003C\u002Fb>\u003C\u002Fsummary>\n  \n  #### [master](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fmaster) (development)\n  \n  - Merged pull request [#78](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fpull\u002F78) that fixes broken download links\n  - Merged pull request [#56](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fpull\u002F56) that adds setup file\n\u003C\u002Fdetails>\n  \n\u003Cdetails>\n  \u003Csummary>\u003Cb>v1.2 (07 Dec 2020)\u003C\u002Fb>\u003C\u002Fsummary>\n  \n  #### [v1.2](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fv1.2) (07 Dec 2020)\n  \n  - Added example script for descriptor extraction with different publicly available models\n  - Added the [MIT license](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fblob\u002Fmaster\u002FLICENSE)\n  - Added mutli-scale performance on `roxford5k` and `rparis6k` for new pre-trained networks with projection, trained on both `retrieval-SfM-120` and `google-landmarks-2018` train datasets\n  - Added a new example test script without post-processing, for networks that include projection layer\n  - Added few things in train example: GeMmp pooling, triplet loss, small trick to handle really large batches\n  - Added more pre-computed whitening options in imageretrievalnet\n  - Added triplet loss \n  - Added GeM pooling with multiple parameters (one p per channel\u002Fdimensionality)\n  - Added script to enable download on Windows 10 as explained in Issue [#39](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F39), courtesy of [SongZRui](https:\u002F\u002Fgithub.com\u002FSongZRui)\n  - Fixed cropping of down-sampled query image\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>v1.1 (12 Jun 2019)\u003C\u002Fb>\u003C\u002Fsummary>\n  \n  #### [v1.1](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fv1.1) (12 Jun 2019)\n  \n  - Migrated code to PyTorch 1.0.0, removed Variable, added torch.no_grad for more speed and less memory at evaluation\n  - Added rigid grid regional pooling that can be combined with any global pooling method (R-MAC, R-SPoC, R-GeM)\n  - Added PowerLaw normalization layer\n  - Added multi-scale testing with any given set of scales, in example test script\n  - Fix related to precision errors of covariance matrix estimation during whitening learning\n  - Fixed minor bugs\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>v1.0 (09 Jul 2018)\u003C\u002Fb>\u003C\u002Fsummary>\n  \n  #### [v1.0](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fv1.0) (09 Jul 2018)\n  \n  - First public version\n  - Compatible with PyTorch 0.3.0\n\u003C\u002Fdetails>\n","## PyTorch中的CNN图像检索：在PyTorch中训练和评估用于图像检索的CNN\n\n这是一个Python工具箱，实现了我们论文中所描述方法的训练与测试：\n\n\n**无需人工标注的CNN图像检索微调**，  \nRadenović F., Tolias G., Chum O.，  \nTPAMI 2018 [[arXiv](https:\u002F\u002Farxiv.org\u002Fabs\u002F1711.02512)]\n\n**CNN图像检索从BoW中学习：基于难例的无监督微调**，  \nRadenović F., Tolias G., Chum O.，  \nECCV 2016 [[arXiv](http:\u002F\u002Farxiv.org\u002Fabs\u002F1604.02426)]\n\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffilipradenovic_cnnimageretrieval-pytorch_readme_61f1d92edb8c.png\" width=\\textwidth\u002F>\n\n---\n\n### 是什么？\n\n该代码实现了：\n\n1. 用于图像检索的CNN训练（微调）\n1. 作为后处理步骤，学习有监督的白化方法，以生成全局图像描述子\n1. 在牛津和巴黎数据集上测试CNN图像检索性能\n\n---\n\n### 先决条件\n\n为了运行此工具箱，您需要：\n\n1. Python3（已在Debian 8.1上使用Python 3.7.0进行测试）\n1. PyTorch深度学习框架（已使用1.0.0版本进行测试）\n1. 其余所有内容（数据和网络）均可通过我们的脚本自动下载\n\n---\n\n### 使用方法\n\n导航（```cd```) 到工具箱的根目录 ```[YOUR_CIRTORCH_ROOT]```。  \n如果您需要，可以使用 `pip3 install .` 安装该包。  \n请确保已安装所需的PyTorch和torchvision库。\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>训练\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n  \n  示例训练脚本位于 ```YOUR_CIRTORCH_ROOT\u002Fcirtorch\u002Fexamples\u002Ftrain.py```  \n  ```\n  python3 -m cirtorch.examples.train [-h] [--training-dataset DATASET] [--no-val]\n                  [--test-datasets DATASETS] [--test-whiten DATASET]\n                  [--test-freq N] [--arch ARCH] [--pool POOL]\n                  [--local-whitening] [--regional] [--whitening]\n                  [--not-pretrained] [--loss LOSS] [--loss-margin LM]\n                  [--image-size N] [--neg-num N] [--query-size N]\n                  [--pool-size N] [--gpu-id N] [--workers N] [--epochs N]\n                  [--batch-size N] [--optimizer OPTIMIZER] [--lr LR]\n                  [--momentum M] [--weight-decay W] [--print-freq N]\n                  [--resume FILENAME]\n                  EXPORT_DIR\n  ```\n\n  如需详细说明选项，请运行：\n  ```\n  python3 -m cirtorch.examples.train -h\n  ```\n\n  > **注意**：使用示例脚本时，训练和测试所需的数据及网络将自动下载。\n  \n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>测试\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  示例测试脚本位于 ```YOUR_CIRTORCH_ROOT\u002Fcirtorch\u002Fexamples\u002Ftest.py```  \n  ```\n  python3 -m cirtorch.examples.test [-h] (--network-path NETWORK | --network-offtheshelf NETWORK)\n                 [--datasets DATASETS] [--image-size N]\n                 [--multiscale MULTISCALE] [--whitening WHITENING] [--gpu-id N]\n  ```\n\n  如需详细说明选项，请运行：\n  ```\n  python3 -m cirtorch.examples.test -h\n  ```\n\n  > **注意**：使用示例脚本时，测试所需的数据将自动下载。\n\n\u003C\u002Fdetails>\n\n---\n\n### 论文实现\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>训练\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  例如，要训练我们在 TPAMI 2018 论文中描述的最佳网络，请运行以下命令。每个 epoch 结束后，微调后的网络将在重新访问的 Oxford 和 Paris 基准测试集上进行测试：\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --test-datasets 'roxford5k,rparis6k' --arch 'resnet101' --pool 'gem' --loss 'contrastive' \n              --loss-margin 0.85 --optimizer 'adam' --lr 5e-7 --neg-num 5 --query-size=2000 \n              --pool-size=22000 --batch-size 5 --image-size 362\n  ```\n\n  每个 epoch 结束后，可以使用学习到的白化对网络进行评估（白化在 epoch 结尾时估计）。为此，请运行以下命令。请注意，这会显著减慢整个训练过程，您也可以稍后使用示例测试脚本对已学习白化的网络进行评估。\n\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --test-datasets 'roxford5k,rparis6k' --test-whiten 'retrieval-SfM-30k' \n              --arch 'resnet101' --pool 'gem' --loss 'contrastive' --loss-margin 0.85 \n              --optimizer 'adam' --lr 5e-7 --neg-num 5 --query-size=2000 --pool-size=22000 \n              --batch-size 5 --image-size 362\n  ```\n\n  > **注意**：调整后的（较低的）学习率是为了使性能与使用 [MatConvNet](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval) 和 [PyTorch-0.3.0](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fv1.0) 实现的训练结果相近。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>测试我们的预训练网络\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  我们提供了使用与 TPAMI 2018 论文相同参数训练的预训练网络，并预先计算了后处理白化步骤。要评估这些网络，请运行：\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-path 'retrievalSfM120k-resnet101-gem' \n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k' \n                  --whitening 'retrieval-SfM-120k'\n                  --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n  ```\n  或\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-path 'retrievalSfM120k-vgg16-gem' \n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k' \n                  --whitening 'retrieval-SfM-120k'\n                  --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n  ```\n  下表展示了使用本框架训练的网络与论文中使用的、基于我们的 [CNN Image Retrieval in MatConvNet](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval) 训练的网络之间的性能对比：\n\n  | 模型 | Oxford | Paris | ROxf (M) | RPar (M) | ROxf (H) | RPar (H) |\n  |:------|:------:|:------:|:------:|:------:|:------:|:------:|\n  | VGG16-GeM (MatConvNet) | 87.9 | 87.7 | 61.9 | 69.3 | 33.7 | 44.3 |\n  | VGG16-GeM (PyTorch) | 87.3 | 87.8 | 60.9 | 69.3 | 32.9 | 44.2 |\n  | ResNet101-GeM (MatConvNet) | 87.8 | 92.7 | 64.7 | 77.2 | 38.5 | 56.3 |\n  | ResNet101-GeM (PyTorch) | 88.2 | 92.5 | 65.4 | 76.7 | 40.1 | 55.2 |\n  \n  > **注**（2022年6月）：我们更新了 [Oxford 5k](https:\u002F\u002Fwww.robots.ox.ac.uk\u002F~vgg\u002Fdata\u002Foxbuildings\u002F) 和 [Paris 6k](https:\u002F\u002Fwww.robots.ox.ac.uk\u002F~vgg\u002Fdata\u002Fparisbuildings\u002F) 图像的下载文件，以使用原始数据集提供者建议的面部模糊版本。请注意，“实验表明，使用面部模糊版本进行图像检索基准测试，精度损失可忽略不计”。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>测试您训练的网络\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  要使用单尺度且不进行白化学习来评估您训练的网络：\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-path YOUR_NETWORK_PATH \n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k'\n  ```\n\n  要使用多尺度评估并结合后处理学习到的白化来评估训练好的网络：\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-path YOUR_NETWORK_PATH \n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k'\n                  --whitening 'retrieval-SfM-120k' \n                  --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n  ```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>测试现成的网络\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  现成的网络也可以进行评估，例如：\n  ```\n  python3 -m cirtorch.examples.test --gpu-id '0' --network-offtheshelf 'resnet101-gem'\n                  --datasets 'oxford5k,paris6k,roxford5k,rparis6k'\n                  --whitening 'retrieval-SfM-120k' \n                  --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n  ```\n  \n\u003C\u002Fdetails>\n\n---\n\n### 全局池化后带有投影（FC）层的网络\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>训练\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n  \n  另一种架构是在全局池化之后加入一个可学习的 FC（投影）层。重要的是，该层的参数应使用学习到的白化结果进行初始化。  \n  要训练这样的设置，可以运行以下命令（性能将每 5 个 epoch 在 `roxford5k` 和 `rparis6k` 上评估）：\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --loss 'triplet' --loss-margin 0.5 --optimizer 'adam' --lr 1e-6 \n              --arch 'resnet50' --pool 'gem' --whitening \n              --neg-num 5 --query-size=2000 --pool-size=20000 \n              --batch-size 5 --image-size 1024 --epochs 100 \n              --test-datasets 'roxford5k,rparis6k' --test-freq 5 \n  ```\n  或\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --loss 'triplet' --loss-margin 0.5 --optimizer 'adam' --lr 5e-7 \n              --arch 'resnet101' --pool 'gem' --whitening \n              --neg-num 4 --query-size=2000 --pool-size=20000 \n              --batch-size 5 --image-size 1024 --epochs 100 \n              --test-datasets 'roxford5k,rparis6k' --test-freq 5 \n  ```\n  或\n  ```\n  python3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \n              --loss 'triplet' --loss-margin 0.5 --optimizer 'adam' --lr 5e-7 \n              --arch 'resnet152' --pool 'gem' --whitening \n              --neg-num 3 --query-size=2000 --pool-size=20000 \n              --batch-size 5 --image-size 900 --epochs 100 \n              --test-datasets 'roxford5k,rparis6k' --test-freq 5 \n  ```\n  分别对应 `ResNet50`、`ResNet101` 或 `ResNet152`。\n\n  实现细节：\n  \n  - FC 层使用监督方式在我们的训练数据和现成特征上学习到的白化结果进行初始化。\n  - 对于这些 FC 层，我们已经为流行的架构和池化方法预计算了白化参数，完整列表请参见 [imageretrievalnet.py#L50](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fblob\u002F474b1fe61ff0e8a6f076ef58f7334cf33d7a3773\u002Fcirtorch\u002Fnetworks\u002Fimageretrievalnet.py#L50)。\n  - 当在微调过程中添加此 FC 层时，如果训练和测试时使用的图像具有相似的高分辨率，则性能最佳。\n  - 添加此 FC 层后，成对距离的分布会发生显著变化，因此对比损失应使用大约两倍大的 margin。在这种情况下，三元组损失的表现略好一些。\n  - 还可以通过进一步调整超参数来获得更高的性能或更快的训练速度。请注意，在本示例中，`--neg-num` 和 `--image-size` 等超参数的选择是为了确保可以在单块拥有 `16 GB` 显存的 GPU 上进行训练。\n    \n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>测试我们预训练的带投影层的网络\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  我们提供了在 `retrieval-SfM-120k (rSfM120k)` 和 [`google-landmarks-2018 (gl18)`](https:\u002F\u002Fwww.kaggle.com\u002Fgoogle\u002Fgoogle-landmarks-dataset) 训练数据集上训练的带投影层的预训练网络。  \n  对于这种架构，无需再进行白化作为后处理步骤（通常性能提升不明显），尽管也可以选择这样做。  \n  例如，使用高分辨率图像和三元组损失，在 `google-landmarks-2018 (gl18)` 数据集上训练的带有 GeM 和投影层的 ResNet101 的多尺度评估，可以通过以下脚本完成：\n  ```\n  python3 -m cirtorch.examples.test_e2e --gpu-id '0' --network 'gl18-tl-resnet101-gem-w' \n              --datasets 'roxford5k,rparis6k' --multiscale '[1, 2**(1\u002F2), 1\u002F2**(1\u002F2)]'\n  ```\n\n  下表给出了所有可用预训练网络的多尺度性能：\n\n  | 模型 | ROxf (M) | RPar (M) | ROxf (H) | RPar (H) |\n  |:------|:------:|:------:|:------:|:------:|\n  | [rSfM120k-tl-resnet50-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fretrieval-SfM-120k\u002FrSfM120k-tl-resnet50-gem-w-97bf910.pth)  | 64.7 | 76.3 | 39.0 | 54.9 |\n  | [rSfM120k-tl-resnet101-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fretrieval-SfM-120k\u002FrSfM120k-tl-resnet101-gem-w-a155e54.pth) | 67.8 | 77.6 | 41.7 | 56.3 |\n  | [rSfM120k-tl-resnet152-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fretrieval-SfM-120k\u002FrSfM120k-tl-resnet152-gem-w-f39cada.pth) | 68.8 | 78.0 | 41.3 | 57.2 |\n  | [gl18-tl-resnet50-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fgl18\u002Fgl18-tl-resnet50-gem-w-83fdc30.pth)  | 63.6 | 78.0 | 40.9 | 57.5 |\n  | [gl18-tl-resnet101-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fgl18\u002Fgl18-tl-resnet101-gem-w-a4d43db.pth) | 67.3 | 80.6 | 44.3 | 61.5 |\n  | [gl18-tl-resnet152-gem-w](http:\u002F\u002Fcmp.felk.cvut.cz\u002Fcnnimageretrieval\u002Fdata\u002Fnetworks\u002Fgl18\u002Fgl18-tl-resnet152-gem-w-21278d5.pth) | 68.7 | 79.7 | 44.2 | 60.3 |\n  \n  > **注**（2022 年 6 月）：我们已更新了用于 [Oxford 5k](https:\u002F\u002Fwww.robots.ox.ac.uk\u002F~vgg\u002Fdata\u002Foxbuildings\u002F) 和 [Paris 6k](https:\u002F\u002Fwww.robots.ox.ac.uk\u002F~vgg\u002Fdata\u002Fparisbuildings\u002F) 图像的下载文件，以使用原始数据集提供者建议的面部模糊版本。请注意，“实验表明，使用面部模糊版本进行图像检索基准测试，精度损失可以忽略不计”。\n  \n\u003C\u002Fdetails>\n\n---\n\n### 相关出版物\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>卷积神经网络的训练（微调）\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  ```\n  @article{RTC18,\n   title = {Fine-tuning {CNN} Image Retrieval with No Human Annotation},\n   author = {Radenovi{\\'c}, F. and Tolias, G. and Chum, O.}\n   journal = {TPAMI},\n   year = {2018}\n  }\n  ```\n  ```\n  @inproceedings{RTC16,\n   title = {{CNN} Image Retrieval Learns from {BoW}: Unsupervised Fine-Tuning with Hard Examples},\n   author = {Radenovi{\\'c}, F. and Tolias, G. and Chum, O.},\n   booktitle = {ECCV},\n   year = {2016}\n  }\n  ```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>Oxford 和 Paris 基准的重新审视（‘roxford5k’ 和 ‘rparis6k’）\u003C\u002Fb>\u003C\u002Fsummary>\u003Cbr\u002F>\n\n  ```\n  @inproceedings{RITAC18,\n   author = {Radenovi{\\'c}, F. and Iscen, A. and Tolias, G. and Avrithis, Y. and Chum, O.},\n   title = {Revisiting Oxford and Paris: Large-Scale Image Retrieval Benchmarking},\n   booktitle = {CVPR},\n   year = {2018}\n  }\n  ```\n  \n\u003C\u002Fdetails>\n\n---\n\n### 版本\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>master（开发中）\u003C\u002Fb>\u003C\u002Fsummary>\n  \n  #### [master](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fmaster)（开发中）\n  \n  - 合并了拉取请求 [#78](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fpull\u002F78)，修复了损坏的下载链接\n  - 合并了拉取请求 [#56](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fpull\u002F56)，添加了 setup 文件\n\u003C\u002Fdetails>\n  \n\u003Cdetails>\n  \u003Csummary>\u003Cb>v1.2（2020年12月7日）\u003C\u002Fb>\u003C\u002Fsummary>\n  \n  #### [v1.2](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fv1.2)（2020年12月7日）\n  \n  - 添加了使用不同公开可用模型提取描述符的示例脚本\n  - 添加了 [MIT 许可证](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fblob\u002Fmaster\u002FLICENSE)\n  - 为新的带有投影层的预训练网络，在 `roxford5k` 和 `rparis6k` 数据集上增加了多尺度性能评估，这些网络同时在 `retrieval-SfM-120` 和 `google-landmarks-2018` 训练数据集上进行过训练\n  - 添加了一个新的无后处理的示例测试脚本，适用于包含投影层的网络\n  - 在训练示例中增加了一些内容：GeMmp 池化、三元组损失，以及一个用于处理超大批次的小技巧\n  - 在 imageretrievalnet 中增加了更多预计算的白化选项\n  - 添加了三元组损失\n  - 添加了具有多个参数的 GeM 池化（每个通道\u002F维度对应一个 p 值）\n  - 添加了脚本，以支持在 Windows 10 上下载，具体说明见议题 [#39](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F39)，感谢 [SongZRui](https:\u002F\u002Fgithub.com\u002FSongZRui) 的贡献\n  - 修复了下采样查询图像的裁剪问题\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>v1.1（2019年6月12日）\u003C\u002Fb>\u003C\u002Fsummary>\n  \n  #### [v1.1](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fv1.1)（2019年6月12日）\n  \n  - 代码迁移到 PyTorch 1.0.0，移除了 Variable，并在评估时添加了 torch.no_grad，以提高速度并减少内存占用\n  - 添加了刚性网格区域池化，可与任何全局池化方法（R-MAC、R-SPoC、R-GeM）结合使用\n  - 添加了幂律归一化层\n  - 在示例测试脚本中增加了使用任意尺度集合进行多尺度测试的功能\n  - 修复了白化学习过程中协方差矩阵估计的精度误差相关问题\n  - 修复了一些小 bug\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n  \u003Csummary>\u003Cb>v1.0（2018年7月9日）\u003C\u002Fb>\u003C\u002Fsummary>\n  \n  #### [v1.0](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Ftree\u002Fv1.0)（2018年7月9日）\n  \n  - 首个公开版本\n  - 兼容 PyTorch 0.3.0\n\u003C\u002Fdetails>","# cnnimageretrieval-pytorch 快速上手指南\n\n本工具是基于 PyTorch 的 CNN 图像检索工具箱，支持图像检索网络的训练（微调）、监督白化学习以及在 Oxford 和 Paris 数据集上的评估。\n\n## 环境准备\n\n在运行本工具箱前，请确保满足以下系统要求和依赖：\n\n*   **操作系统**: Linux (推荐 Debian 8.1 或更高版本)\n*   **Python 版本**: Python 3 (测试环境为 Python 3.7.0)\n*   **深度学习框架**: PyTorch (测试环境为 1.0.0) 及 torchvision\n*   **硬件要求**: 支持 CUDA 的 GPU (用于加速训练和测试)\n\n> **注意**：训练和测试所需的数据集及预训练网络模型将在首次运行脚本时自动下载。\n\n## 安装步骤\n\n1.  克隆仓库或下载源码后，进入工具箱根目录 `[YOUR_CIRTORCH_ROOT]`。\n2.  确保已安装对应版本的 `torch` 和 `torchvision`。\n3.  使用 pip 安装本工具包：\n\n```bash\npip3 install .\n```\n\n## 基本使用\n\n### 1. 训练网络 (Training)\n\n以下命令演示了如何复现 TPAMI 2018 论文中的最佳网络配置。该脚本会使用 `retrieval-SfM-120k` 数据集进行微调，并在每个 epoch 结束后在 Oxford 5k 和 Paris 6k (revisited 版本) 上进行测试。\n\n```bash\npython3 -m cirtorch.examples.train YOUR_EXPORT_DIR --gpu-id '0' --training-dataset 'retrieval-SfM-120k' \\\n            --test-datasets 'roxford5k,rparis6k' --arch 'resnet101' --pool 'gem' --loss 'contrastive' \\\n            --loss-margin 0.85 --optimizer 'adam' --lr 5e-7 --neg-num 5 --query-size=2000 \\\n            --pool-size=22000 --batch-size 5 --image-size 362\n```\n\n*   `YOUR_EXPORT_DIR`: 替换为你想要保存训练结果（模型权重、日志等）的目录路径。\n*   如需查看完整参数说明，可运行：`python3 -m cirtorch.examples.train -h`\n\n### 2. 测试预训练网络 (Testing Pretrained Networks)\n\n以下命令用于评估官方提供的预训练模型（基于 ResNet101-GeM），包含多尺度评估和白化后处理步骤。\n\n```bash\npython3 -m cirtorch.examples.test --gpu-id '0' --network-path 'retrievalSfM120k-resnet101-gem' \\\n                --datasets 'oxford5k,paris6k,roxford5k,rparis6k' \\\n                --whitening 'retrieval-SfM-120k' \\\n                --multiscale '[1, 1\u002F2**(1\u002F2), 1\u002F2]'\n```\n\n*   `--network-path`: 指定预训练模型名称或本地路径。\n*   `--datasets`: 指定要测试的数据集列表。\n*   `--whitening`: 指定用于白化后处理的数据集。\n*   `--multiscale`: 指定多尺度评估的比例因子。\n\n### 3. 测试自定义训练的网络\n\n如果你使用了上述训练步骤得到了自己的模型，可以使用以下命令进行评估（以单尺度、无白化为例）：\n\n```bash\npython3 -m cirtorch.examples.test --gpu-id '0' --network-path YOUR_NETWORK_PATH \\\n                --datasets 'oxford5k,paris6k,roxford5k,rparis6k'\n```\n\n将 `YOUR_NETWORK_PATH` 替换为你训练输出的模型路径即可。若需启用白化和多尺度评估，参考上一节的参数添加 `--whitening` 和 `--multiscale` 选项。","某电商平台的视觉搜索团队正致力于优化“以图搜图”功能，希望让用户上传商品照片后能精准找到库中相似款式的货物。\n\n### 没有 cnnimageretrieval-pytorch 时\n- **检索精度低**：直接使用预训练的通用分类模型提取特征，无法区分细微的纹理或款式差异，导致搜出的结果往往只是“类别相同”而非“视觉相似”。\n- **标注成本高昂**：为了提升效果需要大量人工标注“相似图片对”来微调模型，面对百万级商品库，人力和时间成本难以承受。\n- **缺乏专业后处理**：缺少针对图像检索特征的去相关处理（如白化），特征向量中存在冗余信息，影响了最终排序的准确性。\n- **复现论文困难**：团队需从零复现复杂的度量学习损失函数和硬样本挖掘策略，开发周期长且容易出错。\n\n### 使用 cnnimageretrieval-pytorch 后\n- **无需人工标注即可微调**：利用其支持的无监督细调技术（基于硬样本挖掘），直接从未标注的商品库中学习，显著提升了模型对特定领域特征的敏感度。\n- **检索相关性大幅提升**：通过集成对比损失训练和学到的白化后处理，系统能精准捕捉局部细节，返回结果在视觉风格上高度一致。\n- **快速落地前沿算法**：内置了 TPAMI 和 ECCV 获奖论文的标准实现，团队只需几条命令即可完成从训练到在 Oxford\u002FParis 基准测试的全过程。\n- **灵活适配业务数据**：支持自定义训练数据集和多种骨干网络（如 ResNet101+GeM 池化），可轻松迁移到特定的服装或家居商品场景。\n\ncnnimageretrieval-pytorch 通过无监督微调和专业特征后处理，以极低的标注成本实现了工业级的高精度图像检索能力。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffilipradenovic_cnnimageretrieval-pytorch_2c224695.png","filipradenovic","Filip Radenovic","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ffilipradenovic_35de9861.jpg","Research Scientist at Meta AI","FAIR",null,"filipradenovic.github.io","https:\u002F\u002Fgithub.com\u002Ffilipradenovic",[23],{"name":24,"color":25,"percentage":26},"Python","#3572A5",100,1494,319,"2026-03-31T11:07:11","MIT",3,"Linux","需要 NVIDIA GPU（通过 --gpu-id 参数指定），显存建议 16GB+（用于训练带投影层的大模型或高分辨率图像），CUDA 版本未说明（需匹配已安装的 PyTorch 版本）","未说明",{"notes":36,"python":37,"dependencies":38},"该工具在 Debian 8.1 和 Python 3.7.0、PyTorch 1.0.0 环境下经过测试。训练和测试所需的数据集及网络模型会通过脚本自动下载。若训练带有全连接投影层（FC layer）的架构，建议使用单卡显存至少 16GB 的设备。支持通过 pip3 install . 安装为包。","3.7+",[39,40],"torch>=1.0.0","torchvision",[42,43,44],"开发框架","图像","其他",[46,47,48,49,50],"image-retrieval","convolutional-neural-networks","cnn","python","pytorch",2,"ready","2026-03-27T02:49:30.150509","2026-04-06T07:14:55.653430",[56,61,66,71,76,81,86],{"id":57,"question_zh":58,"answer_zh":59,"source_url":60},16933,"如何复现论文中报告的预训练模型性能（特别是使用多尺度测试时）？","请查阅 README 中\"Testing our pretrained networks with whitening learned end-to-end\"部分（该部分是可展开的）。要获得与论文一致的结果，必须使用特定的多尺度参数运行测试命令。示例命令如下：\npython3 -m cirtorch.examples.test_e2e --gpu-id '0' --network 'gl18-tl-resnet101-gem-w' --datasets 'roxford5k,rparis6k' --multiscale '[1, 2**(1\u002F2), 1\u002F2**(1\u002F2)]'\n注意：确保 multiscale 参数设置为 '[1, 2**(1\u002F2), 1\u002F2**(1\u002F2)]'，这是复现结果的关键。","https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F67",{"id":62,"question_zh":63,"answer_zh":64,"source_url":65},16934,"白化层（Whitening layer）的初始化权重是如何计算的？如果我想从头训练网络该怎么办？","白化层的初始化取决于你的训练策略：\n1. 如果使用现成的网络（如在 ImageNet 上预训练的权重）开始训练，应使用该现成网络的输出来学习并初始化白化层（预计算的白化权重就是这样生成的）。\n2. 如果你想从头开始训练网络（随机初始化权重），那么白化层也应该随机初始化。\n注意：虽然在测试时会基于当前网络输出学习一个新的白化层，但在初始化网络阶段，需要根据上述规则提供初始权重以避免“鸡生蛋”的问题。","https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F8",{"id":67,"question_zh":68,"answer_zh":69,"source_url":70},16935,"如何准备自定义数据集用于训练？有脚本可以生成数据集吗？","目前没有专门的脚本来自动生成数据集，但数据集结构非常简单。你可以参考相关 Issue（如 #27）了解细节。任何能够保存\u002F加载为训练所需数据库格式的数据集都可以用于训练。你需要自行创建数据库文件，然后修改代码以适配你的新数据集。","https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F43",{"id":72,"question_zh":73,"answer_zh":74,"source_url":75},16936,"无法下载数据集或预训练权重，链接失效或速度极慢怎么办？","所有数据仍然托管在相同的 URL 地址上。如果遇到下载失败或速度极慢的情况，通常是由于托管服务器的网络问题引起的，而非链接失效。维护者会定期修复这些问题。建议稍后重试，或者检查是否有临时的网络波动。如果问题持续，可以关注仓库的最新公告以获取替代下载方案。","https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F36",{"id":77,"question_zh":78,"answer_zh":79,"source_url":80},16937,"使用 'rmac'  pooling 方法时出现 TypeError 错误，如何解决？","这通常是由 PyTorch 版本不兼容引起的。原始代码是在 PyTorch 0.3.0 下测试的，而在较新版本（如 0.4.1 或 1.0+）中可能会报错。解决方法是更新代码库到最新版本，维护者已经更新了代码以支持 PyTorch 1.0.0 及更高版本。请确保你拉取了最新的代码，而不是使用旧的提交版本。","https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F11",{"id":82,"question_zh":83,"answer_zh":84,"source_url":85},16938,"如果我想在自己的数据集上测试代码，如何构建 groundtruth 文件（.pkl）？","虽然代码库默认只提供 retrieval-SfM-120k 用于训练，但你可以通过创建符合要求的数据库格式来使用任何数据集。对于测试集，你需要构建一个包含查询图像和对应正样本图像索引的文件。虽然具体构建 .pkl 文件的脚本未直接提供，但逻辑是简单的：创建一个字典或列表，映射每个查询图像到其在地标数据库中的相关图像 ID。你可以参考现有的数据集加载代码（如 testdataset.py）来理解所需的数据结构，并编写简单的脚本将你的标注转换为该格式。","https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F3",{"id":87,"question_zh":88,"answer_zh":89,"source_url":85},16939,"是否可以使用 Oxford5k 或 Paris6k 数据集从头开始训练网络，而不是仅用于微调？","理论上可以，但不推荐这样做。因为 Oxford5k 和 Paris6k 是小型评估数据集，如果使用它们的真值（ground truth）进行训练，会导致过拟合，使得评估结果失去意义（即用测试数据训练）。这些数据集应专门用于评估。如果要从头训练（不使用 ImageNet 初始化），建议使用大规模数据集（如 retrieval-SfM-120k）。如果坚持要从头训练，可以在运行训练脚本时添加 `--not-pretrained` 标志，但请务必使用独立的、大规模的训练数据，而非评估数据集。",[91,96,101],{"id":92,"version":93,"summary_zh":94,"released_at":95},99203,"v1.1","- 代码迁移至 PyTorch 1.0.0，移除了 Variable，并在评估时使用 torch.no_grad 以提升速度、降低内存占用。\n- 新增刚性网格区域池化层，可与任何全局池化方法（R-MAC、R-SPoC、R-GeM）结合使用。\n- 新增幂律归一化层。\n- 在示例测试脚本中添加了基于任意尺度集的多尺度测试功能。\n- 修复白化学习过程中协方差矩阵估计的精度误差问题。\n- 修复了一些小 bug。","2019-06-12T17:40:32",{"id":97,"version":98,"summary_zh":99,"released_at":100},99204,"v1.0","- 首个公开版本\r\n- 兼容 PyTorch 0.3.0","2018-07-09T19:41:20",{"id":102,"version":103,"summary_zh":104,"released_at":105},99202,"v1.2","- 新增了使用不同公开可用模型进行描述符提取的示例脚本\n- 添加了 [MIT 许可证](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fblob\u002Fmaster\u002FLICENSE)\n- 为新的端到端白化预训练网络，在 `roxford5k` 和 `rparis6k` 数据集上增加了多尺度性能评估，这些网络分别在 `retrieval-SfM-120` 和 `google-landmarks-2018` 训练数据集上进行训练\n- 新增了一个不带后处理的示例测试脚本，适用于以完全端到端方式训练、并在训练过程中学习作为全连接层的白化网络\n- 在训练示例中添加了几项内容：GeMmp 池化、三元组损失，以及一个用于处理超大批次的小技巧\n- 在 imageretrievalnet 中增加了更多预计算的白化选项\n- 新增了三元组损失\n- 新增了具有多种参数的 GeM 池化（每个通道\u002F维度可指定不同的 p 值）\n- 根据 [#39](https:\u002F\u002Fgithub.com\u002Ffilipradenovic\u002Fcnnimageretrieval-pytorch\u002Fissues\u002F39) 问题中的说明，新增了可在 Windows 10 上下载的脚本，感谢 [SongZRui](https:\u002F\u002Fgithub.com\u002FSongZRui) 的贡献\n- 修复了对下采样查询图像的裁剪问题","2020-12-07T21:59:41",[107,116,125,133,141,153],{"id":108,"name":109,"github_repo":110,"description_zh":111,"stars":112,"difficulty_score":31,"last_commit_at":113,"category_tags":114,"status":52},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[42,43,115],"Agent",{"id":117,"name":118,"github_repo":119,"description_zh":120,"stars":121,"difficulty_score":51,"last_commit_at":122,"category_tags":123,"status":52},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,"2026-04-05T11:33:21",[42,115,124],"语言模型",{"id":126,"name":127,"github_repo":128,"description_zh":129,"stars":130,"difficulty_score":51,"last_commit_at":131,"category_tags":132,"status":52},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[42,43,115],{"id":134,"name":135,"github_repo":136,"description_zh":137,"stars":138,"difficulty_score":51,"last_commit_at":139,"category_tags":140,"status":52},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[42,124],{"id":142,"name":143,"github_repo":144,"description_zh":145,"stars":146,"difficulty_score":51,"last_commit_at":147,"category_tags":148,"status":52},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[43,149,150,151,115,44,124,42,152],"数据工具","视频","插件","音频",{"id":154,"name":155,"github_repo":156,"description_zh":157,"stars":158,"difficulty_score":31,"last_commit_at":159,"category_tags":160,"status":52},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[115,43,42,124,44]]