Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: add Japanese documents (#755)
Ikko Eltociear Ashimine393ef8fdbac5
diff --git a/CONTRIBUTING_JA.md b/CONTRIBUTING_JA.mdnew file mode 100644index 000000000..6f550f168--- /dev/null+++ b/CONTRIBUTING_JA.md@@ -0,0 +1,564 @@+# コントリビューションガイド++OpenVikingに興味をお持ちいただきありがとうございます!あらゆる種類のコントリビューションを歓迎します:++- バグレポート+- 機能リクエスト+- ドキュメントの改善+- コードのコントリビューション++---++## 開発環境のセットアップ++### 前提条件++- **Python**: 3.10以上+- **Go**: 1.22以上(AGFSコンポーネントのソースビルドに必要)+- **C++コンパイラ**: GCC 9以上 または Clang 11以上(コア拡張のビルドに必要、C++17サポートが必須)+- **CMake**: 3.12以上++#### サポートされているプラットフォーム(プリコンパイル済みWheel)++OpenVikingは以下の環境向けにプリコンパイル済み**Wheel**パッケージを提供しています:++- **Windows**: x86_64+- **macOS**: x86_64、arm64(Apple Silicon)+- **Linux**: x86_64(manylinux)++その他のプラットフォーム(例:Linux ARM64、FreeBSD)では、`pip`によるインストール時にソースから自動コンパイルされます。[前提条件](#前提条件)がインストールされていることを確認してください。++### 1. フォークとクローン++```bash+git clone https://github.com/YOUR_USERNAME/openviking.git+cd openviking+```++### 2. 依存関係のインストール++Python環境管理には`uv`の使用を推奨します:++```bash+# uvのインストール(未インストールの場合)+curl -LsSf https://astral.sh/uv/install.sh | sh++# 依存関係の同期と仮想環境の作成+uv sync --all-extras+source .venv/bin/activate # Linux/macOS+# または .venv\Scripts\activate # Windows+```++#### ローカル開発とAGFSコンパイル++OpenVikingはAGFSに対してデフォルトで`binding-client`モードを使用し、プリビルドされた共有ライブラリが必要です。**AGFS(Go)**コードや**C++拡張**を変更した場合、またはプリビルドライブラリが見つからない場合は、再コンパイルと再インストールが必要です。プロジェクトルートで以下のコマンドを実行してください:++```bash+uv pip install -e . --force-reinstall+```++このコマンドにより`setup.py`が再実行され、AGFSおよびC++コンポーネントのコンパイルがトリガーされます。++### 3. 環境設定++設定ファイル `~/.openviking/ov.conf` を作成します:++```json+{+ "embedding": {+ "dense": {+ "provider": "volcengine",+ "api_key": "your-api-key",+ "model": "doubao-embedding-vision-250615",+ "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"+ }+}+```++環境変数を設定します:++```bash+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf+```++### 4. インストールの確認++```python+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())+```++### 5. Rust CLIのビルド(オプション)++Rust CLI(`ov`)は、OpenViking Serverとやり取りするための高性能コマンドラインクライアントを提供します。++**前提条件**: Rust >= 1.88++```bash+# ソースからビルドしてインストール+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クライアント+│ │+│ ├── core/ # コアデータモデル+│ │ ├── context.py # Contextベースクラス+│ │ └── directories.py # ディレクトリ定義+│ │+│ ├── parse/ # リソースパーサー+│ │ ├── parsers/ # パーサー実装+│ │ ├── tree_builder.py+│ │ └── registry.py+│ │+│ ├── retrieve/ # 検索システム+│ │ ├── retriever.py # メインリトリーバー+│ │ ├── reranker.py # リランキング+│ │ └── intent_analyzer.py+│ │+│ ├── session/ # セッション管理+│ │ ├── session.py # セッションコア+│ │ └── compressor.py # 圧縮+│ │+│ ├── server/ # HTTPサーバー+│ │ ├── app.py # FastAPIアプリファクトリ+│ │ ├── bootstrap.py # エントリポイント(openviking-server)+│ │ └── routers/ # APIルーター+│ │+│ ├── storage/ # ストレージレイヤー+│ │ ├── viking_fs.py # VikingFS+│ │ └── vectordb/ # ベクトルデータベース+│ │+│ ├── utils/ # ユーティリティ+│ │ └── config/ # 設定+│ │+│ └── prompts/ # プロンプトテンプレート+│+├── crates/ # Rustコンポーネント+│ └── ov_cli/ # Rust CLIクライアント+│ ├── src/ # CLIソースコード+│ └── install.sh # クイックインストールスクリプト+│+├── src/ # C++拡張(pybind11)+│+├── tests/ # テストスイート+│ ├── client/ # クライアントテスト+│ ├── server/ # サーバーテスト+│ ├── session/ # セッションテスト+│ ├── parse/ # パーサーテスト+│ ├── vectordb/ # ベクトルデータベーステスト+│ └── integration/ # 統合テスト+│+└── docs/ # ドキュメント+ ├── en/ # 英語ドキュメント+ └── zh/ # 中国語ドキュメント+```++---++## コードスタイル++コードの一貫性を維持するために以下のツールを使用しています:++| ツール | 目的 | 設定 |+|------|---------|--------|+| **Ruff** | リンティング、フォーマット、インポートソート | `pyproject.toml` |+| **mypy** | 型チェック | `pyproject.toml` |++### 自動チェック(推奨)++[pre-commit](https://pre-commit.com/)を使用して、コミット前にこれらのチェックを自動実行します。これにより、手動の作業なしでコードが常に基準を満たすことが保証されます。++1. **pre-commitのインストール**:+ ```bash+ pip install pre-commit+ ```++2. **gitフックのインストール**:+ ```bash+ pre-commit install+ ```++これで、`git commit`実行時に`ruff`(チェックとフォーマット)が自動的に実行されます。チェックが失敗した場合、ファイルが自動修正されることがあります。変更をaddして再度コミットするだけです。++### チェックの実行++```bash+# コードのフォーマット+ruff format openviking/++# リント+ruff check openviking/++# 型チェック+mypy openviking/+```++### スタイルガイドライン++1. **行幅**: 100文字+2. **インデント**: スペース4つ+3. **文字列**: ダブルクォートを推奨+4. **型ヒント**: 推奨(必須ではない)+5. **Docstring**: パブリックAPIには必須(最大1〜2行)++---++## テスト++### テストの実行++```bash+# 全テストの実行+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`デコレーターは**不要**です:++```python+# 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):+ result = await client.add_resource(+ "./test.md",+ reason="test document"+ )+ assert result["status"] == "success"+ assert "root_uri" in result+```++共通フィクスチャは`tests/conftest.py`に定義されており、`client`(初期化済み`AsyncOpenViking`)、`uninitialized_client`、`temp_dir`などが含まれます。++---++## コントリビューションワークフロー++### 1. ブランチの作成++```bash+git checkout main+git pull origin main+git checkout -b feature/your-feature-name+```++ブランチ命名規則:+- `feature/xxx` - 新機能+- `fix/xxx` - バグ修正+- `docs/xxx` - ドキュメント更新+- `refactor/xxx` - コードリファクタリング++### 2. 変更の実施++- コードスタイルガイドラインに従う+- 新機能にはテストを追加する+- 必要に応じてドキュメントを更新する++### 3. 変更のコミット++```bash+git add .+git commit -m "feat: add new parser for xlsx files"+```++### 4. プッシュとPRの作成++```bash+git push origin feature/your-feature-name+```++その後、GitHubでプルリクエストを作成します。++---++## コミット規約++[Conventional Commits](https://www.conventionalcommits.org/)に従います:++```+<type>(<scope>): <subject>++<body>++<footer>+```++### タイプ++| タイプ | 説明 |+|------|-------------|+| `feat` | 新機能 |+| `fix` | バグ修正 |+| `docs` | ドキュメント |+| `style` | コードスタイル(ロジック変更なし) |+| `refactor` | コードリファクタリング |+| `perf` | パフォーマンス改善 |+| `test` | テスト |+| `chore` | ビルド/ツーリング |++### 例++```bash+# 新機能+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"+```++---++## プルリクエストガイドライン++### PRタイトル++コミットメッセージと同じフォーマットを使用します。++### PR説明テンプレート++```markdown+## 概要++変更内容とその目的の簡単な説明。++## 変更の種類++- [ ] 新機能(feat)+- [ ] バグ修正(fix)+- [ ] ドキュメント(docs)+- [ ] リファクタリング(refactor)+- [ ] その他++## テスト++これらの変更のテスト方法を記述してください:+- [ ] ユニットテストが通過する+- [ ] 手動テストが完了している++## 関連Issue++- Fixes #123+- Related to #456++## チェックリスト++- [ ] コードがプロジェクトのスタイルガイドラインに従っている+- [ ] 新機能にテストが追加されている+- [ ] ドキュメントが更新されている(必要な場合)+- [ ] すべてのテストが通過する+```++---++## CI/CDワークフロー++継続的インテグレーションとデプロイメントに**GitHub Actions**を使用しています。ワークフローはモジュール化され、段階的に設計されています。++### 1. 自動ワークフロー++| イベント | ワークフロー | 説明 |+|-------|----------|-------------|+| **プルリクエスト** | `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.13)と**CodeQL**(セキュリティスキャン)を実行。mainブランチの安定性を保証。(**02. Main Branch Checks**として表示) |+| **リリース公開** | `release.yml` | GitHubでリリースを作成すると発動。自動的にソースディストリビューションとwheelをビルドし、Gitタグからバージョンを判定して**PyPI**に公開。(**03. Release**として表示) |+| **週次Cron** | `schedule.yml` | 毎週日曜日に**CodeQL**セキュリティスキャンを実行。(**04. Weekly Security Scan**として表示) |++### 2. 手動トリガーワークフロー++メンテナーは「Actions」タブから以下のワークフローを手動でトリガーして、特定のタスクを実行したり問題をデバッグしたりできます。++#### A. Lintチェック (`11. _Lint Checks`)+コードスタイルチェック(Ruff)と型チェック(Mypy)を実行。引数は不要です。++> **ヒント**: コミット前にこれらのチェックを自動的に実行するため、ローカルに[pre-commit](https://pre-commit.com/)をインストールすることを推奨します(上記の[自動チェック](#自動チェック推奨)セクションを参照)。++#### B. テストスイート(Lite)(`12. _Test Suite (Lite)`)+高速統合テストを実行し、カスタムマトリックス設定をサポートします。++* **入力**:+ * `os_json`: 実行するOSのJSON文字列配列(例:`["ubuntu-24.04"]`)。+ * `python_json`: Pythonバージョンの JSON文字列配列(例:`["3.10"]`)。++#### C. テストスイート(Full)(`13. _Test Suite (Full)`)+サポートされているすべてのプラットフォーム(Linux/Mac/Win)とPythonバージョン(3.10-3.13)で完全なテストスイートを実行。手動トリガー時にカスタムマトリックス設定をサポートします。++* **入力**:+ * `os_json`: 実行するOSのリスト(デフォルト:`["ubuntu-24.04", "macos-14", "windows-latest"]`)。+ * `python_json`: Pythonバージョンのリスト(デフォルト:`["3.10", "3.11", "3.12", "3.13"]`)。++#### D. セキュリティスキャン (`14. _CodeQL Scan`)+CodeQLセキュリティ分析を実行。引数は不要です。++#### E. ディストリビューションビルド (`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"]`)。+ * `build_sdist`: ソースディストリビューションをビルドするか(デフォルト:`true`)。+ * `build_wheels`: wheelディストリビューションをビルドするか(デフォルト:`true`)。++#### F. ディストリビューション公開 (`16. _Publish Distribution`)+ビルド済みパッケージをPyPIに公開(ビルドRun IDが必要)。++* **入力**:+ * `target`: 公開先を選択(`testpypi`、`pypi`、`both`)。+ * `build_run_id`: ビルドワークフローのRun ID(必須、ビルド実行URLから取得)。++#### G. 手動リリース (`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バージョンを生成)。既存のバージョンを公開しようとすると、ワークフローが失敗します。++---++## Issueガイドライン++### バグレポート++以下を提供してください:++1. **環境**+ - Pythonバージョン+ - OpenVikingバージョン+ - オペレーティングシステム++2. **再現手順**+ - 詳細な手順+ - コードスニペット++3. **期待される動作と実際の動作**++4. **エラーログ**(ある場合)++### 機能リクエスト++以下を記述してください:++1. **問題**: どのような問題を解決しようとしていますか?+2. **解決策**: どのような解決策を提案しますか?+3. **代替案**: 他のアプローチを検討しましたか?++---++## ドキュメント++ドキュメントは`docs/`配下にMarkdown形式で管理されています:++- `docs/en/` - 英語ドキュメント+- `docs/zh/` - 中国語ドキュメント++### ドキュメントガイドライン++1. コード例は実行可能であること+2. ドキュメントとコードの同期を維持すること+3. 明確で簡潔な言葉を使用すること++---++## 行動規範++このプロジェクトに参加することで、以下に同意するものとします:++1. **敬意を持つ**: 友好的でプロフェッショナルな態度を維持する+2. **包括的である**: あらゆるバックグラウンドのコントリビューターを歓迎する+3. **建設的である**: 有益なフィードバックを提供する+4. **集中する**: 議論を技術的な内容に保つ++---++## ヘルプ++質問がある場合:++- [GitHub Issues](https://github.com/volcengine/openviking/issues)+- [Discussions](https://github.com/volcengine/openviking/discussions)++---++コントリビューションありがとうございます!diff --git a/README.md b/README.mdindex 3841d60b1..28b37f7ad 100644--- a/README.md+++ b/README.md@@ -6,7 +6,7 @@### OpenViking: The Context Database for AI Agents-English / [中文](README_CN.md)+English / [中文](README_CN.md) / [日本語](README_JA.md)<a href="https://www.openviking.ai">Website</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">Issues</a> · <a href="https://www.openviking.ai/docs">Docs</a>diff --git a/README_CN.md b/README_CN.mdindex 8f33242d4..7bb979af5 100644--- a/README_CN.md+++ b/README_CN.md@@ -5,7 +5,7 @@### OpenViking:AI 智能体的上下文数据库-[English](README.md) / 中文+[English](README.md) / 中文 / [日本語](README_JA.md)<a href="https://www.openviking.ai">官网</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">问题反馈</a> · <a href="https://www.openviking.ai/docs">文档</a>diff --git a/README_JA.md b/README_JA.mdnew file mode 100644index 000000000..63b19d0ad--- /dev/null+++ b/README_JA.md@@ -0,0 +1,634 @@+<div align="center">++<picture>+ <img alt="OpenViking" src="docs/images/banner.jpg" width="100%" height="auto">+</picture>++### OpenViking: AIエージェントのためのコンテキストデータベース++[English](README.md) / [中文](README_CN.md) / 日本語++<a href="https://www.openviking.ai">Webサイト</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">Issues</a> · <a href="https://www.openviking.ai/docs">ドキュメント</a>++[![][release-shield]][release-link]+[![][github-stars-shield]][github-stars-link]+[![][github-issues-shield]][github-issues-shield-link]+[![][github-contributors-shield]][github-contributors-link]+[![][license-shield]][license-shield-link]+[![][last-commit-shield]][last-commit-shield-link]++👋 コミュニティに参加しよう++📱 <a href="./docs/en/about/01-about-us.md#lark-group">Larkグループ</a> · <a href="./docs/en/about/01-about-us.md#wechat-group">WeChat</a> · <a href="https://discord.com/invite/eHvx8E9XF3">Discord</a> · <a href="https://x.com/openvikingai">X</a>++<a href="https://trendshift.io/repositories/19668" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19668" alt="volcengine%2FOpenViking | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>++</div>++---++## 概要++### エージェント開発における課題++AI時代において、データは豊富ですが、高品質なコンテキストは得がたいものです。AIエージェントを構築する際、開発者はしばしば以下の課題に直面します:++- **断片化されたコンテキスト**: メモリはコードに、リソースはベクトルデータベースに、スキルは散在しており、統一的な管理が困難です。+- **急増するコンテキスト需要**: エージェントの長時間タスクは実行のたびにコンテキストを生成します。単純な切り詰めや圧縮は情報の損失につながります。+- **検索効果の低さ**: 従来のRAGはフラットなストレージを使用し、グローバルな視点が欠けているため、情報の全体的なコンテキストを理解することが困難です。+- **観察不能なコンテキスト**: 従来のRAGの暗黙的な検索チェーンはブラックボックスのようで、エラー発生時のデバッグが困難です。+- **限定的なメモリの反復**: 現在のメモリはユーザーとのやり取りの記録に過ぎず、エージェント関連のタスクメモリが不足しています。++### OpenVikingのソリューション++**OpenViking**は、AIエージェント専用に設計されたオープンソースの**コンテキストデータベース**です。++私たちは、エージェントのためのミニマリストなコンテキストインタラクションパラダイムを定義し、開発者がコンテキスト管理の煩雑さから完全に解放されることを目指しています。OpenVikingは従来のRAGの断片化されたベクトルストレージモデルを捨て、革新的に**「ファイルシステムパラダイム」**を採用して、エージェントに必要なメモリ、リソース、スキルの構造化された組織を統一します。++OpenVikingを使えば、開発者はローカルファイルを管理するようにエージェントの頭脳を構築できます:++- **ファイルシステム管理パラダイム** → **断片化を解決**: ファイルシステムパラダイムに基づく、メモリ、リソース、スキルの統一的なコンテキスト管理。+- **階層型コンテキストローディング** → **トークン消費を削減**: L0/L1/L2の3層構造、オンデマンドでロードし、コストを大幅に削減。+- **ディレクトリ再帰検索** → **検索効果を向上**: ネイティブのファイルシステム検索手法をサポートし、ディレクトリ位置決めとセマンティック検索を組み合わせて、再帰的で精密なコンテキスト取得を実現。+- **可視化された検索軌跡** → **観察可能なコンテキスト**: ディレクトリ検索軌跡の可視化をサポートし、ユーザーが問題の根本原因を明確に観察し、検索ロジックの最適化を導くことを可能に。+- **自動セッション管理** → **コンテキストの自己反復**: 会話中のコンテンツ、リソース参照、ツール呼び出しなどを自動的に圧縮し、長期メモリを抽出して、使うほどエージェントを賢く。++---++## クイックスタート++### 前提条件++OpenVikingを始める前に、環境が以下の要件を満たしていることを確認してください:++- **Pythonバージョン**: 3.10以上+- **Goバージョン**: 1.22以上(AGFSコンポーネントのビルドに必要)+- **C++コンパイラ**: GCC 9以上 または Clang 11以上(コア拡張のビルドに必要)+- **オペレーティングシステム**: Linux、macOS、Windows+- **ネットワーク接続**: 安定したネットワーク接続が必要(依存関係のダウンロードとモデルサービスへのアクセスのため)++### 1. インストール++#### Pythonパッケージ++```bash+pip install openviking --upgrade --force-reinstall+```++#### Rust CLI(オプション)++```bash+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash+```++またはソースからビルド:++```bash+cargo install --git https://github.com/volcengine/OpenViking ov_cli+```++### 2. モデルの準備++OpenVikingには以下のモデル機能が必要です:+- **VLMモデル**: 画像とコンテンツの理解用+- **Embeddingモデル**: ベクトル化とセマンティック検索用++#### サポートされているVLMプロバイダー++OpenVikingは3つのVLMプロバイダーをサポートしています:++| プロバイダー | 説明 | APIキーの取得 |+|----------|-------------|-------------|+| `volcengine` | Volcengine Doubaoモデル | [Volcengineコンソール](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new&utm_content=OpenViking&utm_medium=devrel&utm_source=OWO&utm_term=OpenViking) |+| `openai` | OpenAI公式API | [OpenAIプラットフォーム](https://platform.openai.com) |+| `litellm` | 様々なサードパーティモデルへの統合アクセス(Anthropic、DeepSeek、Gemini、vLLM、Ollamaなど) | [LiteLLMプロバイダー](https://docs.litellm.ai/docs/providers)を参照 |++> 💡 **ヒント**:+> - `litellm`は様々なモデルへの統合アクセスをサポートしています。`model`フィールドは[LiteLLMフォーマット仕様](https://docs.litellm.ai/docs/providers)に従う必要があります+> - システムは一般的なモデル(例:`claude-*`、`deepseek-*`、`gemini-*`、`hosted_vllm/*`、`ollama/*`など)を自動検出します。その他のモデルについては、LiteLLMフォーマットに従ったフルプレフィックスを使用してください++#### プロバイダー固有の注意事項++<details>+<summary><b>Volcengine(Doubao)</b></summary>++Volcengineはモデル名とエンドポイントIDの両方をサポートしています。簡便さのためモデル名の使用を推奨します:++```json+{+ "vlm": {+ "provider": "volcengine",+ "model": "doubao-seed-2-0-pro-260215",+ "api_key": "your-api-key",+ "api_base": "https://ark.cn-beijing.volces.com/api/v3"+ }+}+```++エンドポイントIDも使用できます([Volcengine ARKコンソール](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new&utm_content=OpenViking&utm_medium=devrel&utm_source=OWO&utm_term=OpenViking)で確認):++```json+{+ "vlm": {+ "provider": "volcengine",+ "model": "ep-20241220174930-xxxxx",+ "api_key": "your-api-key",+ "api_base": "https://ark.cn-beijing.volces.com/api/v3"+ }+}+```++</details>++<details>+<summary><b>OpenAI</b></summary>++OpenAIの公式APIを使用:++```json+{+ "vlm": {+ "provider": "openai",+ "model": "gpt-4o",+ "api_key": "your-api-key",+ "api_base": "https://api.openai.com/v1"+ }+}+```++カスタムのOpenAI互換エンドポイントも使用できます:++```json+{+ "vlm": {+ "provider": "openai",+ "model": "gpt-4o",+ "api_key": "your-api-key",+ "api_base": "https://your-custom-endpoint.com/v1"+ }+}+```++</details>++<details>+<summary><b>LiteLLM(Anthropic、DeepSeek、Gemini、Qwen、vLLM、Ollamaなど)</b></summary>++LiteLLMは様々なモデルへの統合アクセスを提供します。`model`フィールドはLiteLLMの命名規則に従う必要があります。ここではClaudeとQwenを例に説明します:++**Anthropic:**++```json+{+ "vlm": {+ "provider": "litellm",+ "model": "claude-3-5-sonnet-20240620",+ "api_key": "your-anthropic-api-key"+ }+}+```++**Qwen(DashScope):**++```json+{+ "vlm": {+ "provider": "litellm",+ "model": "dashscope/qwen-turbo", // 詳細は https://docs.litellm.ai/docs/providers/dashscope を参照+ "api_key": "your-dashscope-api-key",+ "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"+ }+}+```++> 💡 **Qwenのヒント**:+> - **中国/北京**リージョンの場合、`api_base`は `https://dashscope.aliyuncs.com/compatible-mode/v1` を使用+> - **国際**リージョンの場合、`api_base`は `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` を使用++**一般的なモデルフォーマット:**++| プロバイダー | モデル例 | 備考 |+|----------|---------------|-------|+| Anthropic | `claude-3-5-sonnet-20240620` | 自動検出、`ANTHROPIC_API_KEY`を使用 |+| DeepSeek | `deepseek-chat` | 自動検出、`DEEPSEEK_API_KEY`を使用 |+| Gemini | `gemini-pro` | 自動検出、`GEMINI_API_KEY`を使用 |+| Qwen | `dashscope/qwen-turbo` | リージョンに基づいて`api_base`を設定(上記参照) |+| OpenRouter | `openrouter/openai/gpt-4o` | フルプレフィックスが必要 |+| vLLM | `hosted_vllm/llama-3.1-8b` | `api_base`をvLLMサーバーに設定 |+| Ollama | `ollama/llama3.1` | `api_base`をOllamaサーバーに設定 |++**ローカルモデル(vLLM / Ollama):**++```bash++# Ollamaの起動+ollama serve+```++```json+// Ollama+{+ "vlm": {+ "provider": "litellm",+ "model": "ollama/llama3.1",+ "api_base": "http://localhost:11434"+ }+}+```++完全なモデルサポートについては、[LiteLLMプロバイダードキュメント](https://docs.litellm.ai/docs/providers)を参照してください。++</details>++### 3. 環境設定++#### サーバー設定テンプレート++設定ファイル `~/.openviking/ov.conf` を作成します。コピー前にコメントを削除してください:++```json+{+ "storage": {+ "workspace": "/home/your-name/openviking_workspace"+ },+ "log": {+ "level": "INFO",+ "output": "stdout" // ログ出力: "stdout" または "file"+ },+ "embedding": {+ "dense": {+ "api_base" : "<api-endpoint>", // APIエンドポイントアドレス+ "api_key" : "<your-api-key>", // モデルサービスAPIキー+ "provider" : "<provider-type>", // プロバイダータイプ: "volcengine" または "openai"(現在サポート済み)+ "dimension": 1024, // ベクトル次元+ "model" : "<model-name>" // Embeddingモデル名(例:doubao-embedding-vision-250615 または text-embedding-3-large)+ },+ "max_concurrent": 10 // 最大同時Embeddingリクエスト数(デフォルト: 10)+ },+ "vlm": {+ "api_base" : "<api-endpoint>", // APIエンドポイントアドレス+ "api_key" : "<your-api-key>", // モデルサービスAPIキー+ "provider" : "<provider-type>", // プロバイダータイプ(volcengine、openai、deepseek、anthropicなど)+ "model" : "<model-name>", // VLMモデル名(例:doubao-seed-2-0-pro-260215 または gpt-4-vision-preview)+ "max_concurrent": 100 // セマンティック処理の最大同時LLM呼び出し数(デフォルト: 100)+ }+}+```++> **注意**: Embeddingモデルについては、現在`volcengine`(Doubao)、`openai`、`jina`プロバイダーがサポートされています。VLMモデルについては、`volcengine`、`openai`、`litellm`の3つのプロバイダーをサポートしています。`litellm`プロバイダーは、Anthropic(Claude)、DeepSeek、Gemini、Moonshot、Zhipu、DashScope、MiniMax、vLLM、Ollamaなど様々なモデルをサポートしています。++#### サーバー設定例++👇 お使いのモデルサービスの設定例を展開して確認:++<details>+<summary><b>例1: Volcengine(Doubaoモデル)を使用</b></summary>++```json+{+ "storage": {+ "workspace": "/home/your-name/openviking_workspace"+ },+ "log": {+ "level": "INFO",+ "output": "stdout" // ログ出力: "stdout" または "file"+ },+ "embedding": {+ "dense": {+ "api_base" : "https://ark.cn-beijing.volces.com/api/v3",+ "api_key" : "your-volcengine-api-key",+ "provider" : "volcengine",+ "dimension": 1024,+ "model" : "doubao-embedding-vision-250615"+ },+ "max_concurrent": 10+ },+ "vlm": {+ "api_base" : "https://ark.cn-beijing.volces.com/api/v3",+ "api_key" : "your-volcengine-api-key",+ "provider" : "volcengine",+ "model" : "doubao-seed-2-0-pro-260215",+ "max_concurrent": 100+ }+}+```++</details>++<details>+<summary><b>例2: OpenAIモデルを使用</b></summary>++```json+{+ "storage": {+ "workspace": "/home/your-name/openviking_workspace"+ },+ "log": {+ "level": "INFO",+ "output": "stdout" // ログ出力: "stdout" または "file"+ },+ "embedding": {+ "dense": {+ "api_base" : "https://api.openai.com/v1",+ "api_key" : "your-openai-api-key",+ "provider" : "openai",+ "dimension": 3072,+ "model" : "text-embedding-3-large"+ },+ "max_concurrent": 10+ },+ "vlm": {+ "api_base" : "https://api.openai.com/v1",+ "api_key" : "your-openai-api-key",+ "provider" : "openai",+ "model" : "gpt-4-vision-preview",+ "max_concurrent": 100+ }+}+```++</details>++#### サーバー設定の環境変数の設定++設定ファイルを作成後、環境変数を設定してファイルを指定します(Linux/macOS):++```bash+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # デフォルト+```++Windowsの場合、以下のいずれかを使用:++PowerShell:++```powershell+$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"+```++コマンドプロンプト(cmd.exe):++```bat+set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"+```++> 💡 **ヒント**: 設定ファイルは他の場所に配置することもできます。環境変数で正しいパスを指定するだけです。++#### CLI/クライアント設定例++👇 CLI/クライアントの設定例を展開して確認:++例:localhostサーバー接続用のovcli.conf++```json+{+ "url": "http://localhost:1933",+ "timeout": 60.0,+ "output": "table"+}+```++設定ファイルを作成後、環境変数を設定してファイルを指定します(Linux/macOS):++```bash+export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # デフォルト+```++Windowsの場合、以下のいずれかを使用:++PowerShell:++```powershell+$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf"+```++コマンドプロンプト(cmd.exe):++```bat+set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"+```++### 4. 最初の例を実行++> 📝 **前提条件**: 前のステップで設定(ov.confとovcli.conf)が完了していることを確認してください。++それでは、完全な例を実行してOpenVikingのコア機能を体験しましょう。++#### サーバーの起動++```bash+openviking-server+```++またはバックグラウンドで実行:++```bash+nohup openviking-server > /data/log/openviking.log 2>&1 &+```++#### CLIの実行++```bash+ov status+ov add-resource https://github.com/volcengine/OpenViking # --wait+ov ls viking://resources/+ov tree viking://resources/volcengine -L 2+# --waitを指定しない場合、セマンティック処理の完了を待つ+ov find "what is openviking"+ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh+```++おめでとうございます!OpenVikingの実行に成功しました 🎉++### VikingBotクイックスタート++VikingBotは、OpenViking上に構築されたAIエージェントフレームワークです。始め方は以下の通りです:++```bash+# オプション1: PyPIからVikingBotをインストール(ほとんどのユーザーに推奨)+pip install "openviking[bot]"++# オプション2: ソースからVikingBotをインストール(開発用)+uv pip install -e ".[bot]"++# Bot有効でOpenVikingサーバーを起動+openviking-server --with-bot++# 別のターミナルでインタラクティブチャットを開始+ov chat+```++---++## サーバーデプロイの詳細++本番環境では、AIエージェントに永続的で高性能なコンテキストサポートを提供するため、OpenVikingをスタンドアロンHTTPサービスとして実行することを推奨します。++🚀 **クラウドにOpenVikingをデプロイ**:+最適なストレージパフォーマンスとデータセキュリティを確保するため、**veLinux**オペレーティングシステムを使用した**Volcengine Elastic Compute Service(ECS)**へのデプロイを推奨します。迅速に開始するための詳細なステップバイステップガイドを用意しています。++👉 **[参照: サーバーデプロイ&ECSセットアップガイド](./docs/en/getting-started/03-quickstart-server.md)**+++## OpenClawメモリプラグインの詳細++* テストデータセット: LoCoMo10(https://github.com/snap-research/locomo)の長距離対話に基づく効果テスト(ground truthのないcategory5を除いた合計1,540ケース)+* 実験グループ: ユーザーがOpenVikingを使用する際にOpenClawのネイティブメモリを無効にしない可能性があるため、ネイティブメモリの有効/無効の実験グループを追加+* OpenVikingバージョン: 0.1.18+* モデル: seed-2.0-code+* 評価スクリプト: https://github.com/ZaynJarvis/openclaw-eval/tree/main++| 実験グループ | タスク完了率 | コスト: 入力トークン数(合計) |+|----------|------------------|------------------|+| OpenClaw(memory-core) | 35.65% | 24,611,530 |+| OpenClaw + LanceDB (-memory-core) | 44.55% | 51,574,530 |+| OpenClaw + OpenViking Plugin (-memory-core) | 52.08% | 4,264,396 |+| OpenClaw + OpenViking Plugin (+memory-core) | 51.23% | 2,099,622 |++* 実験結果:+OpenViking統合後:+- ネイティブメモリ有効時: オリジナルOpenClawと比較して43%改善、入力トークンコスト91%削減。LanceDBと比較して15%改善、入力トークンコスト96%削減。+- ネイティブメモリ無効時: オリジナルOpenClawと比較して49%改善、入力トークンコスト83%削減。LanceDBと比較して17%改善、入力トークンコスト92%削減。++👉 **[参照: OpenClawメモリプラグイン](examples/openclaw-memory-plugin/README.md)**++👉 **[参照: OpenCodeメモリプラグインの例](examples/opencode-memory-plugin/README.md)**++--++## コアコンセプト++最初の例を実行した後、OpenVikingの設計思想を掘り下げましょう。これら5つのコアコンセプトは、先に述べたソリューションと1対1で対応し、完全なコンテキスト管理システムを構築します:++### 1. ファイルシステム管理パラダイム → 断片化の解決++コンテキストをフラットなテキストスライスとして見るのではなく、抽象的な仮想ファイルシステムに統一します。メモリ、リソース、機能のいずれも、`viking://`プロトコル下の仮想ディレクトリにマッピングされ、それぞれにユニークなURIが付与されます。++このパラダイムにより、エージェントはこれまでにないコンテキスト操作能力を獲得し、開発者のように`ls`や`find`などの標準コマンドを通じて、情報を正確かつ決定論的に位置特定、閲覧、操作できます。これにより、コンテキスト管理は曖昧なセマンティックマッチングから、直感的でトレース可能な「ファイル操作」に変わります。詳細: [Viking URI](./docs/en/concepts/04-viking-uri.md) | [コンテキストタイプ](./docs/en/concepts/02-context-types.md)++```+viking://+├── resources/ # リソース: プロジェクトドキュメント、リポジトリ、Webページなど+│ ├── my_project/+│ │ ├── docs/+│ │ │ ├── api/+│ │ │ └── tutorials/+│ │ └── src/+│ └── ...+├── user/ # ユーザー: 個人の好み、習慣など+│ └── memories/+│ ├── preferences/+│ │ ├── writing_style+│ │ └── coding_habits+│ └── ...+└── agent/ # エージェント: スキル、インストラクション、タスクメモリなど+ ├── skills/+ │ ├── search_code+ │ ├── analyze_data+ │ └── ...+ ├── memories/+ └── instructions/+```++### 2. 階層型コンテキストローディング → トークン消費の削減++大量のコンテキストをプロンプトに一度に詰め込むことは、コストが高いだけでなく、モデルウィンドウの超過やノイズの混入を招きやすいです。OpenVikingは書き込み時にコンテキストを自動的に3つのレベルに処理します:+- **L0(Abstract)**: 迅速な検索と識別のための一文の要約。+- **L1(Overview)**: 計画フェーズでのエージェントの意思決定のための、コア情報と使用シナリオを含む。+- **L2(Details)**: エージェントが絶対に必要な場合の深い読み込みのための、完全なオリジナルデータ。++詳細: [コンテキストレイヤー](./docs/en/concepts/03-context-layers.md)++```+viking://resources/my_project/+├── .abstract # L0レイヤー: 要約(〜100トークン)- 迅速な関連性チェック+├── .overview # L1レイヤー: 概要(〜2kトークン)- 構造とキーポイントの理解+├── docs/+│ ├── .abstract # 各ディレクトリに対応するL0/L1レイヤーあり+│ ├── .overview+│ ├── api/+│ │ ├── .abstract+│ │ ├── .overview+│ │ ├── auth.md # L2レイヤー: 完全なコンテンツ - オンデマンドでロード+│ │ └── endpoints.md+│ └── ...+└── src/+ └── ...+```++### 3. ディレクトリ再帰検索 → 検索効果の向上++単一のベクトル検索では、複雑なクエリインテントへの対応が困難です。OpenVikingは、複数の検索手法を深く統合する革新的な**ディレクトリ再帰検索戦略**を設計しました:++1. **インテント分析**: インテント分析により複数の検索条件を生成。+2. **初期位置特定**: ベクトル検索を使用して、初期スライスが位置する高スコアディレクトリを素早く特定。+3. **詳細な探索**: そのディレクトリ内で二次検索を実行し、高スコア結果を候補セットに更新。+4. **再帰的掘り下げ**: サブディレクトリが存在する場合、二次検索ステップを層ごとに再帰的に繰り返し。+5. **結果集約**: 最終的に、最も関連性の高いコンテキストを取得して返却。++この「まず高スコアディレクトリを特定し、次にコンテンツ探索を精緻化する」戦略は、セマンティック的に最もマッチするフラグメントを見つけるだけでなく、情報が存在するコンテキスト全体を理解し、検索のグローバル性と精度を向上させます。詳細: [検索メカニズム](./docs/en/concepts/07-retrieval.md)++### 4. 可視化された検索軌跡 → 観察可能なコンテキスト++OpenVikingの組織は階層的な仮想ファイルシステム構造を使用しています。すべてのコンテキストは統一されたフォーマットで統合され、各エントリはユニークなURI(`viking://`パスのようなもの)に対応し、従来のフラットなブラックボックス管理モードを、理解しやすい明確な階層で打ち破ります。++検索プロセスはディレクトリ再帰戦略を採用しています。各検索のディレクトリブラウジングとファイル位置特定の軌跡が完全に保存され、ユーザーが問題の根本原因を明確に観察し、検索ロジックの最適化を導くことを可能にします。詳細: [検索メカニズム](./docs/en/concepts/07-retrieval.md)++### 5. 自動セッション管理 → コンテキストの自己反復++OpenVikingにはメモリ自己反復ループが組み込まれています。各セッションの終了時に、開発者はメモリ抽出メカニズムを能動的にトリガーできます。システムはタスク実行結果とユーザーフィードバックを非同期的に分析し、ユーザーとエージェントのメモリディレクトリに自動的に更新します。++- **ユーザーメモリの更新**: ユーザーの好みに関するメモリを更新し、エージェントの応答がユーザーのニーズにより適合するように。+- **エージェントの経験蓄積**: タスク実行経験から操作のヒントやツールの使用経験などのコアコンテンツを抽出し、後続タスクでの効率的な意思決定を支援。++これにより、エージェントは世界とのインタラクションを通じて「使うほど賢く」なり、自己進化を実現します。詳細: [セッション管理](./docs/en/concepts/08-session.md)++---++## 上級者向け資料++### ドキュメント++詳細については、[完全なドキュメント](./docs/en/)をご覧ください。++### コミュニティとチーム++詳細については、**[私たちについて](./docs/en/about/01-about-us.md)**をご覧ください。++### コミュニティに参加++OpenVikingはまだ初期段階にあり、改善と探索の余地が多くあります。AIエージェント技術に情熱を持つすべての開発者を心から招待します:++- 前進の原動力となる貴重な**Star**をお願いします。+- 私たちの[**Webサイト**](https://www.openviking.ai)を訪れて、伝えたい思想を理解し、[**ドキュメント**](https://www.openviking.ai/docs)を通じてプロジェクトで使用してください。変化を感じ、最も率直な体験をフィードバックしてください。+- コミュニティに参加して、洞察を共有し、他の人の質問に答え、オープンで互助的な技術の雰囲気を共に作りましょう:+ - 📱 **Larkグループ**: QRコードをスキャンして参加 → [QRコードを表示](./docs/en/about/01-about-us.md#lark-group)+ - 💬 **WeChatグループ**: QRコードをスキャンしてアシスタントを追加 → [QRコードを表示](./docs/en/about/01-about-us.md#wechat-group)+ - 🎮 **Discord**: [Discordサーバーに参加](https://discord.com/invite/eHvx8E9XF3)+ - 🐦 **X(Twitter)**: [フォローする](https://x.com/openvikingai)+- **コントリビューター**になってください。バグ修正の提出でも新機能のコントリビューションでも、あなたのコードの一行一行がOpenVikingの成長の重要な礎石となります。++AIエージェントのコンテキスト管理の未来を共に定義し、構築しましょう。旅は始まりました。あなたの参加をお待ちしています!++### Starの推移++[](https://www.star-history.com/#volcengine/OpenViking&type=timeline&legend=top-left)++## ライセンス++このプロジェクトはApache License 2.0の下でライセンスされています。詳細は[LICENSE](./LICENSE)ファイルを参照してください。+++<!-- リンク定義 -->++[release-shield]: https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff&labelColor=black&logo=github&style=flat-square+[release-link]: https://github.com/volcengine/OpenViking/releases+[license-shield]: https://img.shields.io/badge/license-apache%202.0-white?labelColor=black&style=flat-square+[license-shield-link]: https://github.com/volcengine/OpenViking/blob/main/LICENSE+[last-commit-shield]: https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square+[last-commit-shield-link]: https://github.com/volcengine/OpenViking/commits/main+[github-stars-shield]: https://img.shields.io/github/stars/volcengine/OpenViking?labelColor&style=flat-square&color=ffcb47+[github-stars-link]: https://github.com/volcengine/OpenViking+[github-issues-shield]: https://img.shields.io/github/issues/volcengine/OpenViking?labelColor=black&style=flat-square&color=ff80eb+[github-issues-shield-link]: https://github.com/volcengine/OpenViking/issues+[github-contributors-shield]: https://img.shields.io/github/contributors/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square+[github-contributors-link]: https://github.com/volcengine/OpenViking/graphs/contributors