發(fā)布研究論文代碼的小技巧

↑ 點(diǎn)擊藍(lán)字?關(guān)注極市平臺(tái)

譯者丨白小魚

來(lái)源丨h(huán)ttps://zhuanlan.zhihu.com/p/263069345

編輯丨極市平臺(tái)

極市導(dǎo)讀

?

在分析了200多個(gè)優(yōu)質(zhì)機(jī)器學(xué)習(xí)項(xiàng)目代碼庫(kù)后，本文總結(jié)出了一份NeurlPS 2020會(huì)議代碼提交的模板，現(xiàn)已成為大會(huì)官方指南，快來(lái)看看吧。>>加入極市CV技術(shù)交流群，走在計(jì)算機(jī)視覺的最前沿

整理了最受歡迎的ML研究論文代碼庫(kù)中的最佳做法，現(xiàn)在這已是 NeurIPS 2020 會(huì)議的官方指南！

為了促進(jìn)項(xiàng)目的可重復(fù)性，基于對(duì) 200 多個(gè)機(jī)器學(xué)習(xí)項(xiàng)目代碼庫(kù)的分析 和 GitHub Stars 數(shù)目 ，我們總結(jié)了如下建議。

有關(guān)更多詳細(xì)信息，請(qǐng)參見：

https://medium.com/paperswithcode/ml-code-completeness-checklist-e9127b168501

對(duì)于 NeurIPS 2020 會(huì)議的代碼提交，建議（但不是強(qiáng)制性的）使用“用前須知.md”模板，并根據(jù) ML代碼完整性清單（如下所述）核對(duì)所有項(xiàng)目。

用前須知.md 模板

我們提供了一個(gè)模板，可用于發(fā)布 ML 研究項(xiàng)目代碼庫(kù)。

模板鏈接：https://github.com/datawhalechina/releasing-research-code/blob/master/templates/README.md

模板中的各節(jié)是通過查看在社區(qū)中最受歡迎的代碼庫(kù)，然后查看與受歡迎程度相關(guān)聯(lián)的共同組件而得出的。

ML代碼完整性檢查清單

我們通過查看最受歡迎的 ML 研究項(xiàng)目代碼庫(kù)的共同點(diǎn)來(lái)編制此清單。此外，我們優(yōu)先考慮了可重復(fù)性高的項(xiàng)目，使得其他項(xiàng)目更容易基于此研究代碼庫(kù)構(gòu)建。

ML代碼完整性檢查清單包含五個(gè)要素：

1. 依賴說(shuō)明
2. 訓(xùn)練代碼
3. 評(píng)估代碼
4. 預(yù)訓(xùn)練模型
5. 自述文件，包括結(jié)果表格以及運(yùn)行/產(chǎn)生這些結(jié)果的精確命令代碼

我們驗(yàn)證了滿足檢查清單中更多要素的代碼庫(kù)，也傾向于擁有更多的 GitHub Stars。通過分析官方 NeurIPS 2019 代碼庫(kù)已驗(yàn)證了這一點(diǎn)。我們還提供數(shù)據(jù)和筆記，以從帖子中復(fù)現(xiàn)此分析。

進(jìn)一步的，滿足所有這五個(gè)要素的 NeurIPS 2019 代碼庫(kù)，具有最高數(shù)量的 GitHub Stars（中位數(shù)196星，平均2664星）。

我們會(huì)針對(duì)檢查清單上的每個(gè)要素進(jìn)行詳細(xì)說(shuō)明。

1. 依賴說(shuō)明

如果您使用的是Python，則意味著需要提供 requirements.txt文件（如果使用 pip 和 virtualenv ），或者提供 environment.yml 文件（如果使用 anaconda ），或者提供 setup.py（如果您使用代碼是一個(gè)庫(kù)）。

優(yōu)秀的做法是在 用前須知.md 中安排一個(gè)小節(jié)，說(shuō)明如何安裝這些依賴項(xiàng)。假定用戶需要掌握最少的背景知識(shí)，并且要清楚而全面了解項(xiàng)目——如果用戶無(wú)法設(shè)置您的依賴項(xiàng)，那么他們很可能也會(huì)放棄其余的代碼。

如果您希望提供整個(gè)可復(fù)現(xiàn)模型的環(huán)境，則可能要考慮使用 Docker 并將您環(huán)境的 Docker映像 上載到 Dockerhub 。

2. 訓(xùn)練代碼

您的代碼應(yīng)當(dāng)包含一個(gè)訓(xùn)練腳本，該腳本可用于獲取本文所述的主要結(jié)果。這意味著腳本中應(yīng)該包括模型超參數(shù)以及在獲取結(jié)果的過程中使用的所有技巧。為了最大程度地發(fā)揮作用，在編寫此代碼時(shí)，最好考慮到可擴(kuò)展性：如果您的用戶希望在自己的數(shù)據(jù)集上使用相同的訓(xùn)練腳本，該怎么辦？

您可以提供打包好的文檔化的命令行程序（例如 train.py ）作為用戶的使用入口。

3. 評(píng)估代碼

模型評(píng)估和實(shí)驗(yàn)通常取決于細(xì)微的細(xì)節(jié)，而這些細(xì)微的細(xì)節(jié)并不總是能在論文中得到解釋。這就是為什么包含用于評(píng)估或運(yùn)行實(shí)驗(yàn)的精確代碼，將有助于對(duì)實(shí)驗(yàn)過程進(jìn)行完整描述的原因。反過來(lái)，這可以幫助用戶信任和理解您的研究工作，并以您的研究為基礎(chǔ)。

您可以提供打包好的文檔化的命令行程序（例如 eval.py ）作為用戶的使用入口。

4. 預(yù)訓(xùn)練模型

從頭開始訓(xùn)練模型可能既耗時(shí)又昂貴。一種增加對(duì)結(jié)果的可信度的方法是提供預(yù)訓(xùn)練模型，從而讓社區(qū)可以使用該模型獲得最終結(jié)果并進(jìn)行評(píng)估。這意味著用戶無(wú)需重新模型訓(xùn)練，就可以看到可信的結(jié)果。

另一個(gè)常見使用場(chǎng)景是對(duì)下游任務(wù)進(jìn)行微調(diào)，在此情況下，發(fā)布預(yù)訓(xùn)練模型非常有用，以便其他人可以在其基礎(chǔ)上構(gòu)建模型以應(yīng)用于自己的數(shù)據(jù)集。

最后，一些用戶可能想嘗試一下您的模型，看看它是否適用于某些示例數(shù)據(jù)。提供預(yù)訓(xùn)練模型可以使您的用戶隨心所欲地玩轉(zhuǎn)您的工作，并有助于理解您相關(guān)研究論文的成就。

5. 自述文件，包括結(jié)果表格以及運(yùn)行/產(chǎn)生這些結(jié)果的精確命令代碼

在 用前須知.md 中添加結(jié)果表格，可讓您的用戶快速了解代碼庫(kù)中的內(nèi)容（有關(guān)示例，請(qǐng)參見模板）。有關(guān)如何復(fù)現(xiàn)這些結(jié)果的說(shuō)明（帶有任何相關(guān)腳本的鏈接，預(yù)訓(xùn)練的模型等）可以為用戶提供另一個(gè)使用入口，并直接促進(jìn)復(fù)現(xiàn)性。在某些情況下，一篇論文的主要結(jié)果是一個(gè)圖表，但對(duì)于用戶而言，如果不閱讀該論文，可能會(huì)難以理解該結(jié)果。

您可以進(jìn)一步的鏈接到包含其他論文的最新結(jié)果的完整指標(biāo)排行榜，從而進(jìn)一步幫助用戶理解您的結(jié)果并將其關(guān)聯(lián)起來(lái)，有多個(gè)排行榜服務(wù)可以存儲(chǔ)該信息。

用于發(fā)布研究論文代碼的其他優(yōu)質(zhì)資源

注：尚未根據(jù)國(guó)內(nèi)情況推薦相關(guān)工具。

托管預(yù)訓(xùn)練模型文件

1. Zenodo - 支持版本管理，50GB，帶寬免費(fèi)，DOI，可長(zhǎng)期保存
2. GitHub Releases - 支持版本管理，2GB 文件大小限制，帶寬免費(fèi)
3. OneDrive - 支持版本管理，2GB（免費(fèi) ）/ 1TB （需要Office 365套裝），帶寬免費(fèi)
4. Google Drive - 支持版本管理，15GB，帶寬免費(fèi)
5. Dropbox - 支持版本管理，2GB（付費(fèi)無(wú)限容量），帶寬免費(fèi)
6. AWS S3 - 支持版本管理，僅付費(fèi)使用，帶寬需付費(fèi)

管理模型文檔

1. RClone - 針對(duì)眾多不同的云存儲(chǔ)提供商，提供統(tǒng)一訪問方案

標(biāo)準(zhǔn)化模型接口

1. PyTorch Hub
2. Tensorflow Hub
3. Hugging Face NLP models
4. ONNX

指標(biāo)排行榜

1. Papers with Code leaderboards - with 2500+ leaderboards
2. CodaLab - with 450+ leaderboards
3. NLP Progress - with 90+ leaderboards
4. EvalAI - with 50+ leaderboards
5. Collective Knowledge - with 40+ leaderboards
6. Weights & Biases - Benchmarks - with 9+ leaderboards

制作項(xiàng)目頁(yè)面

1. GitHub pages
2. Fastpages

制作示例和指南

1. Google Colab
2. Binder
3. Streamlit

貢獻(xiàn)

如果您想做出貢獻(xiàn)或?qū)@些指南有任何建議，可以通過 [email protected] 與本中文界面維護(hù)者取得聯(lián)系（或者通過 [email protected] 與 Paper with Code 聯(lián)系 ），亦可在此 GitHub 項(xiàng)目中提出問題（open an issue）。

任何貢獻(xiàn)都是受到歡迎的！此項(xiàng)目中的所有內(nèi)容均遵照 MIT許可 進(jìn)行許可授權(quán)。

內(nèi)容出處：

datawhalechina/releasing-research-code

接下來(lái)需要做的事情：

將該文章內(nèi)涉及的工具添加中國(guó)化的內(nèi)容。

推薦閱讀

• 強(qiáng)強(qiáng)聯(lián)合！Papers with Code攜手arXiv，上傳論文、提交代碼一步到位

• 從因果關(guān)系來(lái)看小樣本學(xué)習(xí)丨NeurIPS 2020
  

• 三步搞定機(jī)器學(xué)習(xí)核心：矩陣求導(dǎo)
  

?ACCV 2020國(guó)際細(xì)粒度網(wǎng)絡(luò)圖像識(shí)別競(jìng)賽正式開賽！

添加極市小助手微信（ID : cvmart2），備注：姓名-學(xué)校/公司-研究方向-城市（如：小極-北大-目標(biāo)檢測(cè)-深圳），即可申請(qǐng)加入極市目標(biāo)檢測(cè)/圖像分割/工業(yè)檢測(cè)/人臉/醫(yī)學(xué)影像/3D/SLAM/自動(dòng)駕駛/超分辨率/姿態(tài)估計(jì)/ReID/GAN/圖像增強(qiáng)/OCR/視頻理解等技術(shù)交流群：每月大咖直播分享、真實(shí)項(xiàng)目需求對(duì)接、求職內(nèi)推、算法競(jìng)賽、干貨資訊匯總、與?10000+來(lái)自港科大、北大、清華、中科院、CMU、騰訊、百度等名校名企視覺開發(fā)者互動(dòng)交流~

△長(zhǎng)按添加極市小助手

△長(zhǎng)按關(guān)注極市平臺(tái)，獲取最新CV干貨

覺得有用麻煩給個(gè)在看啦~??