CyberAgent AI Lab 研修【研究コード公開 基礎編】GitHubでの実験・分析コード公開

研究コード公開 基礎編 GitHubでの実験・分析コード公開 CyberAgent AI Lab 研修 20240620 Kazuhiro Ota 1

論文に加えて研究コードを公開する流れがありますね > Our code, data and trained models are available at this http URL. 研究コードがGitHubで公開されてる！ 2

• https://github.com/tech-srl/code2seq

なぜ研究コードを公開するの？ メリットたくさん！ プロダクト所属のエンジニアと連携しや すくなり、AI Lab発の技術を事業に繋げ やすくなるといったところも 研究者流コーディングの極意 from 言語処理学会第19回年次大会 3

• https://www.chokkan.org/publication/coding-for-researchers.pdf

とはいえ、ただ単にコードを公開するだけではダメ… GitHubにあがっている研究コード使ってみようとして困ったことないですか？ ● ● ● ● ● ● ● ● ● 論文タイトルとアブストラクトだけ書かれたREADMEでどう使えば？ requirements.txtの依存ライブラリなんか不足してない？ データセットはどこからダウンロードすれば？ 学習済みモデルはどこから（略） ハードコードされた個人マシンのホームディレクトリパス READMEに従ってもエラー出るんですが… Python 3.5までバージョンダウンしたらやっとエラー消えた CIUのML Platformでしか動かないの？ 推論コードだけ？学習コードはないの？ コード公開にもやはりある程度のお作法があります… 4

この研修資料で目指す状態 ● ● 研究で書いたコードを外に出しても恥ずかしくない状態でGitHub公開できる ようになる コードだけでなくその成果物によって適切な公開手段を選択し、必要であれ ばリサーチエンジニアと連携して公開できるようになる 論文同様、コードも他人が利用する・読むものであることを意識して、受け手に とって優しい状態でのコード提供ができるようになりましょう 5

対象者 コード公開について自信がないAI Labリサーチサイエンティスト GitHubでの実験・分析コード公開（本編） ● ● ● 研究コード書いたのは良いけど、そのまま公開して良いのかどうか迷っている 公開といってもJupyterNotebookの分析コードだけなんですが セキュリティとか大丈夫なんだっけ？ ソフトウェア化と成果物の公開（発展編） ● ● ● 皆に pip install して使ってもらいたい 手軽にモデルを試すことのできるデモアプリも作ったんだけど 最近よく聞くHugging Faceって？ 6

• https://www.docswell.com/s/ciela/57R676-2025-03-13-152708

前提知識 ● Python ○ ○ ● 今回の資料で対象とする言語ですが、概念自体は他の言語にも応用可能です 何でも良いのでデータに対する処理を書いた経験があれば問題ないと思います Git / GitHub ○ ○ 入門資料がネット上にたくさんありますので、まったく触れたことがなければ一度それらの チュートリアルをこなしてみてください ソースコードのバージョン管理についての概念と、コミット、リポジトリ、ブランチ、プル リクエスト&マージなどの用語についてなんとなく想像がつく状態であればOKです 7

目次 ● ● ● ● ● GitHubで公開するとは READMEの書き方 コードリファクタリング 不要情報の削除 公開前チェック・レビュー 8

GitHubで公開するとは 9

GitHub https://github.com/ 10

• https://github.com/

GitHub https://github.com/ 本来はソフトウェア開発のための共同作業用 プラットフォームだが、研究コードを外部提 供する上でも問題なく利用可能 11

• https://github.com/

AI Labでの研究コード置き場 AI Labでは下記Organization（リポジトリの組織的集合体）を保有しています https://github.com/CyberAgentAILab/ 皆様の研究コードもこちらでリポジトリ管理することでチームメンバーや共著者 間での連携を取りやすくする狙いがあります 12

• https://github.com/CyberAgentAILab/

GitHub (CyberAgentAILab org.) でコードを公開するとは リポジトリの可視状態を Public に変更すること これでAI Labメンバーのみ閲覧・利用可能だったリポジトリが外部にも公開されます Internal or Private (非公開状態) Public (公開状態) 意図しない情報漏洩防止の為、会社のポリシーでリポジトリの初期可視状態はInternalもしくはPrivateとなります AI Labでは公開対象のリポジトリについて最終的にリサーチエンジニアでチェックし、セキュリティ・コンプライア ンスの面で問題なく公開可能なことを確認してからPublicに変更する運用としています 13

Publicになるとどうなるか、何ができるようになるのか ● ● 自分の書いたコードを外部の方に見て・使ってもらえるようになる IssueやPull Requestを通して、問い合わせ・指摘・コード改変案を受け付けられる ようになり、外部の方とコミュニケーションを取りつつコードを改善・発展してい くことができるようになる コードだけでなく論文に関する質問が来ることも…研究自体のコミュニケーションツールとしても使われること があるみたいです 有意義なテーマで議論するためにも、コードの状態を最初からなるべく良いものにしておきたいですね 14

READMEの書き方 15

README GitHubリポジトリにアクセスした際、コードリ ストの下部に表示されるドキュメント コード利用者向けの情報をファーストビューに 掲載できる、リポジトリの顔ともいうべき重要 なファイルです（このドキュメントぐらいしか まともに読まれないこともザラです） 16

一般的なREADMEの内容 特にフォーマットはありませんが、ライブラリ・フレームワークを提供するソフトウェア開発 上では可能な限り下記のような情報を含めることが一般的 ● ● ● ● ● ● リポジトリ名と一行説明 ○ コード公開を行うGitリポジトリの名前と、何のコードであるかを短く説明します 詳細な説明 ○ 目的、主な機能、使用する技術など、より詳細な情報を図なども用いながら記します インストール手順 ○ ユーザーがコードを自分のシステムにインストールするための手順 ○ 対象OS、依存関係や必要なツール、インストールコマンドなど 使用方法 ○ コードの基本的な使用方法 ○ 可能なら、具体的なコード例やスクリーンショットも 貢献方法 ○ 他の開発者がプロジェクトに貢献するためのガイドライン ○ バグレポートや機能リクエストの送り方、プルリクエストの作成方法など ライセンス ○ 他の人がリポジトリをどのように使用して良いかを明記します ○ 主要なOSSライセンスについて調べておきましょう 17

研究コードの場合 研究で書いた実験・分析コードの場合、前述した一般的な項目に加えて下記につ いても言及することが望ましいです ● ● ● ● ● ● ● ● 論文タイトル・著者名 アブストラクト アーキテクチャ図・実験結果図 Bibtex コードの意図と内容 入出力データの概要 実験環境と再現性 データセット・事前学習済みモデルの設置とダウンロード方法 18

研究コードの場合 研究で書いた実験・分析コードの場合、前述した一般的な項目に加えて下記につ いても言及することが望ましいです ● ● ● ● ● ● ● ● 論文タイトル・著者名 アブストラクト ココらへんは論文情報をほぼその まま掲載すればいいだけですが… アーキテクチャ図・実験結果図 Bibtex コードの意図と内容 入出力データの概要 実験環境と再現性 データセット・事前学習済みモデルの設置とダウンロード方法 19

研究コードの場合 研究で書いた実験・分析コードの場合、前述した一般的な項目に加えて下記につ いても言及することが望ましいです ● ● ● ● ● ● ● ● 論文タイトル・著者名 アブストラクト アーキテクチャ図・実験結果図 ココらへんに触れられていないリ Bibtex ポジトリを時々目にします… コードの意図と内容 公開コードという観点では大事な ことだらけ 入出力データの概要 実験環境と再現性 データセット・事前学習済みモデルの設置とダウンロード方法 20

コードの意図・内容 実験・分析コードと一口にいっても、Jupyter Notebookでのデータ分析フローや PyTorchでの新規モデル実装など、その実態は意図や用途によって様々なはずです 書いたコードが何のためのものなのか、何も知らないユーザがどのように実行でき、 さらに実行結果として何が得られるのかを書きましょう これさえクリアになっていれば、ユーザのコードに対する心理的な障壁がぐっと下が ります ● ● ● 何を分析・集計するコード？ 何を可視化するコード？ 対応する論文の箇所はどこ？ 21

入出力データの概要 コードが機械学習モデルやバッチスクリプトを含む場合、それらが処理する入力データと出力 データについても記載しましょう もちろん論文にモデル図があればそれを貼り付けて掲載するのも手です ユーザがコードのメンタルモデル（動作や結果への理解）を掴むのに役立ちます Segment Anythingリポジトリのモデル概要図 22

• https://github.com/facebookresearch/segment-anything

実験環境と再現性 マシン要件など、コードを動作させるための環境について記載しましょう ライブラリなどの外部リソースにて、プロプライエタリだったり有料ライセンス が必要なものがあればそれも明記しましょう ● ● ● ● ● ● ● OSとバージョン 言語とバージョン 主要なフレームワーク・ライブラリとバージョン カメラ・マイクなど外部デバイスの利用有無 GPUの利用有無と利用している場合はCUDAバージョン 利用したクラウド（AWS/GCP）とその中のサービス Web API 23

実験環境と再現性 前ページで挙げた項目について、社内に閉じているために社外での調達が不可能 で、ユーザ側で同じ実験環境の再現が難しい場合があるかもしれません AI Labでありそうなのは下記のようなケース ● ● 社内独自の実験環境でコードを動かしていた 社内開発の非公開ライブラリを使用してコードを書いた 下記のような対応が考えられますが、もし難しい場合はリサーチエンジニアに相 談してください ● ● 同様の仕組み（例えば、SageMaker/VertexAI、似たAPIを有する公開ライブ ラリ）を用いてコードを再実装する 社内事情に非依存な部分のみを抽出して公開する 24

データセット・事前学習済みモデルの設置とDL方法 コードの実行に必要な研究用データセットや事前学習済みモデルなど、関連ファ イルを事前に取得してもらう必要がある場合は、その方法についても記載しま しょう ● ファイルを配置するオンラインストレージを決めて事前に公開しておく ○ ○ ○ ○ ● ファイルの規模・種類によって適切なアップロード先を検討・選定する GitHubの場合、ファイルにつき100MBまであればリポジトリに直接含められます 100MB以上の場合はGit LFSやGitHub Releaseの利用を検討しましょう、数GBまでいけます ストレージの種類については発展編で詳しく触れたいと思います 独自データセットの場合は中身についても記載する ○ ○ ○ どんなデータなのかをファイル形式とともに具体的に テーブルデータのCSVファイルなのか、画像・テキストなどのメディアデータセットなのか データセットの場合サンプルが提示できるなら数サンプル程度掲載しておくと良いでしょう 25

データセット・事前学習済みモデルの設置とDL方法 できればコマンド一発で必要なファイル群がダウンロードできるようにしておくとベス トです 適宜シェルスクリプトなりMakeコマンドなりにまとめ、実行方法を記載しておきましょ う ちなみにスクリプト化した際には実行権限を付与しておくと、実行可能ファイルである ことが明確化され、ユーザからも実行しやすくなって便利です 26

コードリファクタリング 27

公開コードは自分だけのものではない…のはわかってるけど ここからはコードの中身についてのお話をしていきます 研究している間、実験・分析コードはほぼ1人で書いていたと思いますが（あっ ても共著者が読んで手直しするぐらい？）、公開した場合、当たり前ですが不特 定多数の人に読まれるようになります なるべく汚いコードは公開 しないようにしよう、とい うのはわかるけど、何をど うやってどのぐらいキレイ にすればよいの？ 28

よく見る光景 リーダブルコード読んでおいてね 29

• https://www.oreilly.co.jp/books/9784873115658/

よく見る光景 読んだけど「さて何をどうすれば…？」となりがち コードレビューなどで実際に他者とやりとりしないと実感がわきづらい 実験・分析コードにはtoo muchな内容も 書いたのJupyter Notebookだけなんだけどどうすれば？ もちろん研究内容をソフトウェア化したり、共著者間でチーム開発する となった場合には重要な内容ばかりです ● コードを公開する段階ではなく書いているときに読むもの ● ● ● ● 実験・分析コードの公開であれば、コード体裁 を整えるための最低限を抑えておきましょう 30

最低限のコード体裁とは 下記を行いましょう どれもコードをツールにかけたり、事務的な変更削除対応を施すだけで完結するた め、ある程度コスパよくリファクタリングできます ● ● ● ● コードフォーマット 静的解析（Linter）対応 不要なコメントアウトの除去 コードカバレッジ率の向上 それぞれで紹介するツールに関する詳細は省きますが、 これもネット上に情報はたくさんありますので 少し調べると使い方がすぐわかると思います 31

コードフォーマット ソースコードの書き方についてのスタイルや規約の話 ● ● ● ● ● インデントの空白数、種類（スペース or タブ） クラス・関数間の改行数 最大行長 行の改行タイミング 文字列のデフォルトクォーテーション 既に独自のフォーマットで実験・分析コードを書いていた、というのであれば飛 ばしてもらって構いませんが、そうでない方が多いと思われます 32

コードフォーマット 多くのプログラミング言語ではコードフォーマットを自動化するツールが提供されており、Pythonだと Blackやisortを共用するのが一般的でしょうか（Rust製のruffなんてツールも最近よく聞きます） 共著者と取り決めがなければツールの設定をカスタマイズする必要はないので、直接コードベースに対し てフォーマットを施してしまいましょう 33

• https://github.com/psf/black
• https://pycqa.github.io/isort/
• https://github.com/astral-sh/ruff

静的解析（Linter） コードがコーディング規約やセキュリティに則って記述されているかのチェックです 自分はだいたいflake8とbanditを使って検出結果になるべく対応しています デフォルトで出力されるもの全て対応するのもそれはそれで難しいとは思うので、必要に応じて 無視するエラーについての設定を入れたり検出を無視するメタコメントを付与しましょう 34

• https://github.com/pycqa/flake8/
• https://github.com/PyCQA/bandit

不要なコメントアウトの除去 使わないコードを後でやっぱり使うかもと、とりあえず コメントアウトにしておきたくなる気持ちはわかります …が、GitHubで公開する上では不要です ここのif文使って ないのはなぜ？ 強い気持ちでコメントアウトはどんどん消していきま しょう（コード公開をしない場合でもGit管理する以 上、コメントアウトを残す必要性はあまりありません） もしどうしても残す場合は、コメントアウトしている箇 所がなぜコメントアウトして残してあるかを明記してお くようにしましょう 35

コードカバレッジ率の向上 現状使っていない機能・関数も削除した状態での公開を心がけてください Coverage.pyなどのカバレッジツールを使うことでコードの実行に伴う通過率を計 測し、使用していない関数や未通過のif文などを可視化することができますので そういった部分の削除について検討しましょう 未使用コードが示 されますので参考 にしましょう 36

• https://github.com/nedbat/coveragepy/

不要情報の削除 37

GitHubで公開してはいけない情報 下記のような情報をGitHubにうっかり公開しないようにしなければいけません これらの情報をそもそもリポジトリにコミットしたりソースコードに書いたりす ることがないように気をつけてください ● ● ● ● パスワード Web APIトークン SSH秘密鍵 クラウドクレデンシャル ○ ○ ● GCP Service Account AWS IAM Access Key / Access Secret データソースへの接続情報 38

うっかりコミットしてしまっていた場合 とはいえ、研究コードを書いている最中は試行錯誤が発生しやすく、既に前ペー ジに挙げた情報を意図せずコミットしてしまっているかもしれません その場合は、下記の記事を参考にして削除対応を行ってください Removing sensitive data from a repository - GitHub Docs 39

• https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository#using-the-bfg

絶対パスの相対パス化 Jupyterで分析コードを書いていると、ファイル読み込みなどの際にローカルマ シンの絶対パスをつい指定してしまっているようなケースがあるかと思います ユーザ環境上での動作可能性がないものとなりますので、リポジトリにおける作 業ディレクトリからの相対パスへと書き換えましょう 40

不要ファイルのコミット対象からの除外 公開する上でGitバージョン管理から除外すべきファイル・ディレクトリはまだ あります ● ● ● ● ● ● OSシステムファイル Pythonコンパイル結果（__pycache__ ディレクトリ） 中規模（100MB）以上のデータセット コードによる中間出力 バージョン管理が不要な実験結果ファイル 仮想環境（venvなど）ディレクトリ これらは .gitignore というファイルにファイルパスパターンを指定することでコ ミット対象から除外することが可能です 41

.gitignoreの配置と除外ファイルパターン追加 GitHubよりPython向けの.gitignoreファイルテンプレートが提案されていますの でまずはこちらを.gitignoreとしてリポジトリに設置しましょう Python.gitignore Pythonで一般的なIDE/ライブラリ用の設定ファイルなどを一括でコミットの対象 から外すことができ、意図しないGit管理化を防ぐことができます 加えて実験・分析で出力されていた独自の実験結果ファイルなど、コミット非対 象ファイルのパスパターンを.gitignoreに追記していってください 42

• https://github.com/github/gitignore/blob/main/Python.gitignore

公開前チェック・レビュー 43

リポジトリ名 リポジトリ名はなるべくキャッチーなものにしましょう 短く留めつつも、その内容や目的を明確に表現するものであるべきです ⭕ ● ● 提案技術・モデルの名称 論文タイトル略称 ❌ ● ● 論文タイトルそのまま “ex01”など、実験・分析のノートブック・フォルダ名 44

About欄 GitHubのリポジトリ画面右上にあるAbout欄も埋めておきましょう 論文のリンクやキーワードも付与しておくとよいでしょう ⭕ ❌ 45

リンクの確認 READMEにリンクを記載した場合、リンク切れや疎通不能な社内専用サイトへの URLがないか確認しておきましょう 公開前に一度ブラウザのプライベートブラウズ機能でざっと閲覧しておきましょ う 46

公開前にやりとりしていたIssue/PR 公開前にGitHub Issue/PRでやりとりを行っていた場合、その情報は公開後も 残ったままとなってしまいます（Closed Issue/PRとして扱われる） 社外秘情報を扱っておらず外部公開しても構わないやりとりのみ行っていたのな ら構いませんが、なるべくなら公開前にIssueやPRの活用は控えたいところです もし、Issue/PRを空にした状態で公開を行いたい場合は、新しく公開用リポジト リを作成し、そこにコード内容を一括コピーして公開する方法をとりましょう 47

最後に共著者にレビューしてもらおう 共著者・チームメンバーにリポジトリを全体的にチェックしてもらいましょう ● 明確さ ○ ● 完全性 ○ ○ ● 分野外の研究者やエンジニアも対象としている場合、専門用語やジャーゴンを避け、で きるだけ一般的な言葉で説明することが理想的です フォーマットとスタイル ○ ● READMEが必要な情報を過不足無く含んでいるかどうか インストール手順、使用方法、依存ライブラリ 理解しやすさ ○ ● 研究コードの目的、機能、使用方法などが明確かどうか 必要に応じて図、見出し、リスト、ボールド、イタリックなどのMarkdown機能を使用 して情報が整理・強調されているか 動作可能性 ○ 共著者に実際にインストール手順を試してもらい、実行に問題がないか確認してもらい ましょう 48

最後に共著者にレビューしてもらおう 特にコードの動作可能性については、外部のユーザの環境を想定した新しい作業環 境を用意してもらい、その上でリポジトリClone→コード実行の流れを踏襲できる かを確かめてもらってください お手軽にまっさらなOS環境を用意できる手段としては下記のようなものがあります ● GCP Cloud Shell ○ ○ ● 無料でLinux環境を利用可能 ストレージも5GB ローカル内仮想マシン ○ ○ multipassというツールで手軽にUbuntu環境を用意できます Ubuntu以外のOSを利用するにはVirtualBoxというツールも 49

• https://cloud.google.com/shell
• https://multipass.run/
• https://www.virtualbox.org/

まとめ 実験・分析コードをGitHub上で公開していく上で、最低限のリポジトリマナーについて解 説しました 共著者間での動作検証を確実に行うという前提のもと、コードのリファクタリングにはあま り深く触れませんでしたが、もし可能であればコード内容についても共著者に意見を伺って フィードバックを取り入れてみてください（リーダブルコードなどの書籍やウェブ上の記事 を参考にしてみるのも良いと思います） 50

参考 ● ● ● ● ● ● ● ● 研究者流コーディングの極意 研究で開発したコードの公開 研究のプログラミングにおける悲劇を無くすためのGitとテスト - Kesinの知 見置き場 【GitHub】シンプルなREADME.mdの書き方 -コピペで使えるテンプレート 付き-｜はやぶさの技術ノート Pythonのリンター・フォーマッターをしっかりと理解する（Flake8, Black, isort, mypy） Bandit を使って Python コードのセキュリティをチェックしよう！ - サー バーワークスエンジニアブログ 【Coverage.py】Pythonでカバレッジを取得する Removing sensitive data from a repository - GitHub Docs 51

• https://www.chokkan.org/publication/coding-for-researchers.pdf
• https://www.tkl.iis.u-tokyo.ac.jp/~ynaga/papers/ynaga-nlp2013tutorial.pdf
• https://kesin.hatenablog.com/entry/2014/02/27/研究のプログラミングにおける悲劇を無くすため
• https://cpp-learning.com/readme/
• https://zenn.dev/tanny/articles/cdb555d6124a2a
• https://blog.serverworks.co.jp/python-bandit
• https://zenn.dev/msh0x01/articles/0bb52d73f2f089
• https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository