CONTRIBUTING_JA.md
OpenVikingに興味をお持ちいただきありがとうございます！あらゆる種類のコントリビューションを歓迎します：
ov CLI もビルドされるため必須）build-essential の導入を推奨。環境によっては pkg-config も必要ですxcode-select --install）OpenVikingは以下の環境向けにプリコンパイル済みWheelパッケージを提供しています：
その他のプラットフォーム（例：FreeBSD）では、pipによるインストール時にソースから自動コンパイルされます。前提条件がインストールされていることを確認してください。
git clone https://github.com/YOUR_USERNAME/openviking.git
cd openviking
Python環境管理にはuvの使用を推奨します：
# uvのインストール（未インストールの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 依存関係の同期と仮想環境の作成
uv sync --all-extras
source .venv/bin/activate # Linux/macOS
# または .venv\Scripts\activate # Windows
OpenVikingはAGFSに対してデフォルトでbinding-clientモードを使用し、事前にビルドされたネイティブ成果物を利用します。AGFS（Go）コード、同梱のRust CLI、またはC++拡張を変更した場合や、プリビルド成果物が見つからない場合は、再コンパイルと再インストールが必要です。プロジェクトルートで以下のコマンドを実行してください：
uv pip install -e . --force-reinstall
このコマンドによりsetup.pyが再実行され、AGFS、同梱 ov CLI、C++コンポーネントの再ビルドがトリガーされます。
設定ファイル ~/.openviking/ov.conf を作成します：
{
"embedding": {
"dense": {
"provider": "volcengine",
"api_key": "your-api-key",
"model": "doubao-embedding-vision-251215",
"api_base": "https://ark.cn-beijing.volces.com/api/v3",
"dimension": 1024,
"input": "multimodal"
}
},
"vlm": {
"api_key": "your-api-key",
"model": "doubao-seed-2-0-pro-260215",
"api_base": "https://ark.cn-beijing.volces.com/api/v3"
}
}
環境変数を設定します：
export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
import asyncio
import openviking as ov
async def main():
client = ov.AsyncOpenViking(path="./test_data")
await client.initialize()
print("OpenViking initialized successfully!")
await client.close()
asyncio.run(main())
Rust CLI（ov）は、OpenViking Serverとやり取りするための高性能コマンドラインクライアントを提供します。
ov を直接使わない場合でも、OpenViking をソースからビルドするなら Rust ツールチェーンは必要です。パッケージング時に同梱 CLI バイナリも一緒にビルドされるためです。
前提条件: Rust >= 1.91.1
# ソースからビルドしてインストール
cargo install --path crates/ov_cli
# またはクイックインストールスクリプトを使用（プリビルドバイナリをダウンロード）
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash
インストール後、ov --helpを実行して利用可能なすべてのコマンドを確認できます。CLI接続設定は~/.openviking/ovcli.confに記述します。
openviking/
├── pyproject.toml # プロジェクト設定
├── Cargo.toml # Rustワークスペース設定
├── third_party/ # サードパーティ依存関係
│ └── agfs/ # AGFSファイルシステム
│
├── openviking/ # Python SDK
│ ├── async_client.py # AsyncOpenVikingクライアント
│ ├── sync_client.py # SyncOpenVikingクライアント
│ ├── client/ # ローカル / HTTP クライアント実装
│ ├── console/ # スタンドアロン console UI とプロキシサービス
│ ├── core/ # コアデータモデルとディレクトリ抽象
│ ├── message/ # セッションメッセージと part モデル
│ ├── models/ # Embedding / VLM バックエンド
│ ├── parse/ # リソースパーサーと検出器
│ ├── resource/ # リソース処理と watch 管理
│ ├── retrieve/ # 検索システム
│ ├── server/ # HTTPサーバー
│ ├── service/ # 共通 service レイヤー
│ ├── session/ # セッション管理と圧縮
│ ├── storage/ # ストレージレイヤー
│ ├── telemetry/ # オペレーション telemetry
│ ├── trace/ # trace とランタイム追跡補助
│ ├── utils/ # ユーティリティと設定補助
│ └── prompts/ # プロンプトテンプレート
│
├── crates/ # Rustコンポーネント
│ └── ov_cli/ # Rust CLIクライアント
│ ├── src/ # CLIソースコード
│ └── install.sh # クイックインストールスクリプト
│
├── src/ # C++拡張ソース（Python abi3）
│
├── tests/ # テストスイート
│ ├── client/ # クライアントテスト
│ ├── console/ # Console テスト
│ ├── core/ # コアロジックテスト
│ ├── parse/ # パーサーテスト
│ ├── resource/ # リソース処理テスト
│ ├── retrieve/ # 検索テスト
│ ├── server/ # サーバーテスト
│ ├── service/ # Service レイヤーテスト
│ ├── session/ # セッションテスト
│ ├── storage/ # ストレージテスト
│ ├── telemetry/ # Telemetry テスト
│ ├── vectordb/ # ベクトルデータベーステスト
│ └── integration/ # E2E テスト
│
└── docs/ # ドキュメント
├── en/ # 英語ドキュメント
└── zh/ # 中国語ドキュメント
コードの一貫性を維持するために以下のツールを使用しています：
| ツール | 目的 | 設定 |
|---|---|---|
| Ruff | リンティング、フォーマット、インポートソート | pyproject.toml |
| mypy | 型チェック | pyproject.toml |
pre-commitを使用して、コミット前にこれらのチェックを自動実行します。これにより、手動の作業なしでコードが常に基準を満たすことが保証されます。
pre-commitのインストール:
pip install pre-commit
gitフックのインストール:
pre-commit install
これで、git commit実行時にruff（チェックとフォーマット）が自動的に実行されます。チェックが失敗した場合、ファイルが自動修正されることがあります。変更をaddして再度コミットするだけです。
# コードのフォーマット
ruff format openviking/
# リント
ruff check openviking/
# 型チェック
mypy openviking/
# 全テストの実行
pytest
# 特定のテストモジュールの実行
pytest tests/client/ -v
pytest tests/server/ -v
pytest tests/parse/ -v
# 特定のテストファイルの実行
pytest tests/client/test_lifecycle.py
# 特定のテストの実行
pytest tests/client/test_lifecycle.py::TestClientInitialization::test_initialize_success
# キーワードで実行
pytest -k "search" -v
# カバレッジ付きで実行
pytest --cov=openviking --cov-report=term-missing
テストはtests/配下のサブディレクトリに整理されています。プロジェクトはasyncio_mode = "auto"を使用しているため、非同期テストに@pytest.mark.asyncioデコレーターは不要です：
# tests/client/test_example.py
from openviking import AsyncOpenViking
class TestAsyncOpenViking:
async def test_initialize(self, uninitialized_client: AsyncOpenViking):
await uninitialized_client.initialize()
assert uninitialized_client._service is not None
await uninitialized_client.close()
async def test_add_resource(self, client: AsyncOpenViking, sample_markdown_file):
result = await client.add_resource(
path=str(sample_markdown_file),
reason="test document"
)
assert "root_uri" in result
assert result["root_uri"].startswith("viking://")
共通フィクスチャはtests/conftest.pyに定義されており、client（初期化済みAsyncOpenViking）、uninitialized_client、temp_dir、sample_markdown_file などが含まれます。
git checkout main
git pull origin main
git checkout -b feature/your-feature-name
ブランチ命名規則：
feature/xxx - 新機能fix/xxx - バグ修正docs/xxx - ドキュメント更新refactor/xxx - コードリファクタリングgit add .
git commit -m "feat: add new parser for xlsx files"
git push origin feature/your-feature-name
その後、GitHubでプルリクエストを作成します。
Conventional Commitsに従います：
<type>(<scope>): <subject>
<body>
<footer>
| タイプ | 説明 |
|---|---|
feat | 新機能 |
fix | バグ修正 |
docs | ドキュメント |
style | コードスタイル（ロジック変更なし） |
refactor | コードリファクタリング |
perf | パフォーマンス改善 |
test | テスト |
chore | ビルド/ツーリング |
# 新機能
git commit -m "feat(parser): add support for xlsx files"
# バグ修正
git commit -m "fix(retrieval): fix score calculation in rerank"
# ドキュメント
git commit -m "docs: update quick start guide"
# リファクタリング
git commit -m "refactor(storage): simplify interface methods"
コミットメッセージと同じフォーマットを使用します。
## 概要
変更内容とその目的の簡単な説明。
## 変更の種類
- [ ] 新機能（feat）
- [ ] バグ修正（fix）
- [ ] ドキュメント（docs）
- [ ] リファクタリング（refactor）
- [ ] その他
## テスト
これらの変更のテスト方法を記述してください：
- [ ] ユニットテストが通過する
- [ ] 手動テストが完了している
## 関連Issue
- Fixes #123
- Related to #456
## チェックリスト
- [ ] コードがプロジェクトのスタイルガイドラインに従っている
- [ ] 新機能にテストが追加されている
- [ ] ドキュメントが更新されている（必要な場合）
- [ ] すべてのテストが通過する
継続的インテグレーションとデプロイメントにGitHub Actionsを使用しています。ワークフローはモジュール化され、段階的に設計されています。
| イベント | ワークフロー | 説明 |
|---|---|---|
| プルリクエスト | pr.yml | Lint（Ruff、Mypy）とTest Lite（Linux + Python 3.10での統合テスト）を実行。コントリビューターに迅速なフィードバックを提供。（01. Pull Request Checksとして表示） |
| mainへのプッシュ | ci.yml | Test Full（全OS：Linux/Win/Mac、全Pyバージョン：3.10-3.14）とCodeQL（セキュリティスキャン）を実行。mainブランチの安定性を保証。（02. Main Branch Checksとして表示） |
| リリース公開 | release.yml | GitHubでリリースを作成すると発動。自動的にソースディストリビューションとwheelをビルドし、Gitタグからバージョンを判定してPyPIに公開。（03. Releaseとして表示） |
| 週次Cron | schedule.yml | 毎週日曜日にCodeQLセキュリティスキャンを実行。（04. Weekly Security Scanとして表示） |
このほか、PR review の自動化、Docker イメージのビルド、Rust CLI のパッケージング用ワークフローも用意されています。
メンテナーは「Actions」タブから以下のワークフローを手動でトリガーして、特定のタスクを実行したり問題をデバッグしたりできます。
11. _Lint Checks)コードスタイルチェック（Ruff）と型チェック（Mypy）を実行。引数は不要です。
ヒント: コミット前にこれらのチェックを自動的に実行するため、ローカルにpre-commitをインストールすることを推奨します（上記の自動チェックセクションを参照）。
12. _Test Suite (Lite))高速統合テストを実行し、カスタムマトリックス設定をサポートします。
os_json: 実行するOSのJSON文字列配列（例：["ubuntu-24.04"]）。python_json: Pythonバージョンの JSON文字列配列（例：["3.10"]）。13. _Test Suite (Full))サポートされているすべてのプラットフォーム（Linux/Mac/Win）とPythonバージョン（3.10-3.14）で完全なテストスイートを実行。手動トリガー時にカスタムマトリックス設定をサポートします。
os_json: 実行するOSのリスト（デフォルト：["ubuntu-24.04", "macos-14", "windows-latest"]）。python_json: Pythonバージョンのリスト（デフォルト：["3.10", "3.11", "3.12", "3.13", "3.14"]）。14. _CodeQL Scan)CodeQLセキュリティ分析を実行。引数は不要です。
15. _Build Distribution)Pythonのwheelパッケージのみをビルドし、公開はしません。
os_json: ビルドするOSのリスト（デフォルト：["ubuntu-24.04", "ubuntu-24.04-arm", "macos-14", "macos-15-intel", "windows-latest"]）。python_json: Pythonバージョンのリスト（デフォルト：["3.10", "3.11", "3.12", "3.13", "3.14"]）。build_sdist: ソースディストリビューションをビルドするか（デフォルト：true）。build_wheels: wheelディストリビューションをビルドするか（デフォルト：true）。16. _Publish Distribution)ビルド済みパッケージをPyPIに公開（ビルドRun IDが必要）。
target: 公開先を選択（testpypi、pypi、both）。build_run_id: ビルドワークフローのRun ID（必須、ビルド実行URLから取得）。03. Release)ワンストップのビルドと公開（ビルドと公開ステップを含む）。
バージョン番号とタグ規約: このプロジェクトは
setuptools_scmを使用してGitタグからバージョン番号を自動抽出します。
- タグ命名規約:
vX.Y.Z形式に従う必要があります（例：v0.1.0、v1.2.3）。タグはセマンティックバージョニングに準拠する必要があります。- リリースビルド: リリースイベントがトリガーされると、バージョン番号はGitタグに直接対応します（例：
v0.1.0->0.1.0）。- 手動/非タグビルド: バージョン番号には最後のタグからのコミット数が含まれます（例：
0.1.1.dev3）。- バージョン確認: 公開ジョブ完了後、ワークフローSummaryページ上部のNotificationsエリアで公開バージョンを直接確認できます（例：
Successfully published to PyPI with version: 0.1.8）。ログまたはArtifactsのファイル名でも確認できます。
target: 公開先を選択。
none: アーティファクトのビルドのみ（公開なし）。ビルド機能の検証に使用。testpypi: TestPyPIに公開。ベータテストに使用。pypi: 公式PyPIに公開。both: 両方に公開。os_json: ビルドプラットフォーム（デフォルトはすべて含む）。python_json: Pythonバージョン（デフォルトはすべて含む）。build_sdist: ソースディストリビューションをビルドするか（デフォルト：true）。build_wheels: wheelディストリビューションをビルドするか（デフォルト：true）。公開に関する注意事項:
- 先にテスト: 公式PyPIに公開する前に、TestPyPIで検証することを強く推奨します。PyPIとTestPyPIは完全に独立した環境であり、アカウントやパッケージデータは共有されません。
- 上書き不可: PyPIもTestPyPIも、同じ名前とバージョンの既存パッケージの上書きを許可しません。再公開が必要な場合は、バージョン番号をアップグレードする必要があります（例：新しいバージョンをタグ付けするか、新しいdevバージョンを生成）。既存のバージョンを公開しようとすると、ワークフローが失敗します。
以下を提供してください：
環境
再現手順
期待される動作と実際の動作
エラーログ（ある場合）
以下を記述してください：
ドキュメントはdocs/配下にMarkdown形式で管理されています：
docs/en/ - 英語ドキュメントdocs/zh/ - 中国語ドキュメントこのプロジェクトに参加することで、以下に同意するものとします：
質問がある場合：
コントリビューションありがとうございます！