From e0fc73c6b58986f902e457b8a38e45de7e96cdbd Mon Sep 17 00:00:00 2001 From: Daria Korenieva Date: Wed, 8 Jul 2026 20:17:14 -0700 Subject: [PATCH] docs: add Valkey Search vector database configuration Document the new valkey_search vdb backend (LangBot#2276) in the deploy settings config example and notes for en/zh/ja, including the vector_weight not-honored caveat. Closes #100 (#101) Signed-off-by: Daria Korenieva --- en/deploy/settings.mdx | 11 +++++++++++ ja/deploy/settings.mdx | 11 +++++++++++ zh/deploy/settings.mdx | 11 +++++++++++ 3 files changed, 33 insertions(+) diff --git a/en/deploy/settings.mdx b/en/deploy/settings.mdx index 53425d5f6..3889f9307 100644 --- a/en/deploy/settings.mdx +++ b/en/deploy/settings.mdx @@ -79,6 +79,16 @@ vdb: database: 'langbot' user: 'postgres' password: 'postgres' + valkey_search: + host: 'localhost' + port: 6379 + db: 0 + username: '' # Optional (ACL user) + password: '' # Optional (ACL / requirepass), never logged + tls: false # Optional, for toB/SaaS deployments + index_algorithm: 'HNSW' # HNSW (approximate) or FLAT (exact) + distance_metric: 'COSINE' # COSINE, L2, or IP + request_timeout: 5000 # Per-request timeout in ms storage: use: local cleanup: @@ -154,6 +164,7 @@ space: - When SQLite is used as the database, automatic monitoring cleanup directly releases database file space after deleting expired records. - `plugin.binary_storage.max_value_bytes` limits the size of a single plugin binary storage value. The default is 10 MiB. - The WebUI sidebar includes a “Storage Analysis” page for viewing database, logs, uploaded files, vector store, plugins, MCP, temporary files, and cleanup candidates. +- `vdb.valkey_search` uses the [Valkey Search](https://valkey.io/) module via the official async `valkey-glide` client and supports vector, full-text, and hybrid search. Run a server with the module loaded, e.g. `valkey/valkey-bundle:9.1.0` (`docker run -d -p 6379:6379 valkey/valkey-bundle:9.1.0`). Note: hybrid search follows a filter-then-KNN model, so the `vector_weight` parameter is accepted but **not honored** (a native Valkey Search limitation). The connection is lazy, so a down or misconfigured server does not block startup. See the [Valkey Search integration doc](https://github.com/langbot-app/LangBot/blob/master/docs/VALKEY_SEARCH_INTEGRATION.md) for details. - `api.global_api_key` is a global API key for agents / automation: once set, calls to the HTTP API or the built-in MCP server (`/mcp`) authenticate by sending `X-API-Key: ` or `Authorization: Bearer *** — no login session and no database-stored `lbk_` key required. It is stored in plaintext in `config.yaml`, so enable it only on trusted / internal deployments and serve it over HTTPS. See [API Key Authentication](https://github.com/langbot-app/LangBot/blob/master/docs/API_KEY_AUTH.md). ## Set Configuration Via Environment Variables diff --git a/ja/deploy/settings.mdx b/ja/deploy/settings.mdx index 705a95eff..1b1581635 100644 --- a/ja/deploy/settings.mdx +++ b/ja/deploy/settings.mdx @@ -79,6 +79,16 @@ vdb: database: 'langbot' user: 'postgres' password: 'postgres' + valkey_search: + host: 'localhost' + port: 6379 + db: 0 + username: '' # 任意（ACL ユーザー） + password: '' # 任意（ACL / requirepass）、ログには記録されません + tls: false # 任意、toB/SaaS 環境向け + index_algorithm: 'HNSW' # HNSW（近似）または FLAT（厳密） + distance_metric: 'COSINE' # COSINE、L2、または IP + request_timeout: 5000 # リクエストごとのタイムアウト（ミリ秒） storage: use: local cleanup: @@ -152,6 +162,7 @@ space: - SQLite をデータベースとして使用している場合、監視レコードの自動削除後にデータベースファイルの空き容量を直接解放します。 - `plugin.binary_storage.max_value_bytes` は 1 つのプラグインバイナリストレージ値のサイズを制限します。デフォルトは 10 MiB です。 - WebUI のサイドバーには「ストレージ分析」ページがあり、データベース、ログ、アップロードファイル、ベクターストア、プラグイン、MCP、一時ファイル、クリーンアップ候補を確認できます。 +- `vdb.valkey_search` は [Valkey Search](https://valkey.io/) モジュールを公式の非同期クライアント `valkey-glide` 経由で利用し、ベクター検索・全文検索・ハイブリッド検索の 3 モードに対応します。モジュールを読み込んだサーバー（例: `valkey/valkey-bundle:9.1.0`、`docker run -d -p 6379:6379 valkey/valkey-bundle:9.1.0`）を起動してください。注意: ハイブリッド検索はフィルタ後に KNN を行うモデルのため、`vector_weight` パラメータは受け付けられますが**反映されません**（Valkey Search の原生的な制限）。接続は遅延確立されるため、サーバーが停止・誤設定でも起動を妨げません。詳細は [Valkey Search 統合ドキュメント](https://github.com/langbot-app/LangBot/blob/master/docs/VALKEY_SEARCH_INTEGRATION.md) を参照してください。 - `api.global_api_key` はエージェント / 自動化向けのグローバル API キーです。設定すると、HTTP API または組み込み MCP サーバー（`/mcp`）の呼び出し時に `X-API-Key: ` または `Authorization: Bearer *** を送るだけで認証されます（ログインセッションやデータベース保存の `lbk_` キーは不要）。`config.yaml` に平文で保存されるため、信頼できる / 内部デプロイでのみ有効化し、HTTPS で公開してください。[API キー認証](https://github.com/langbot-app/LangBot/blob/master/docs/API_KEY_AUTH.md) を参照。 ## 環境変数による設定 diff --git a/zh/deploy/settings.mdx b/zh/deploy/settings.mdx index e9bd09096..2f5809303 100644 --- a/zh/deploy/settings.mdx +++ b/zh/deploy/settings.mdx @@ -79,6 +79,16 @@ vdb: database: 'langbot' user: 'postgres' password: 'postgres' + valkey_search: + host: 'localhost' + port: 6379 + db: 0 + username: '' # 可选（ACL 用户） + password: '' # 可选（ACL / requirepass），不会记录到日志 + tls: false # 可选，用于 toB/SaaS 场景 + index_algorithm: 'HNSW' # HNSW（近似）或 FLAT（精确） + distance_metric: 'COSINE' # COSINE、L2 或 IP + request_timeout: 5000 # 单次请求超时时间（毫秒） storage: use: local cleanup: @@ -154,6 +164,7 @@ space: - SQLite 作为数据库时，监控记录自动清理后会直接释放数据库文件空间。 - `plugin.binary_storage.max_value_bytes` 用于限制插件单个二进制存储值大小，默认 10 MiB。 - WebUI 侧边栏的“存储分析”页面可查看数据库、日志、上传文件、向量库、插件、MCP、临时文件等空间占用和清理候选项。 +- `vdb.valkey_search` 基于 [Valkey Search](https://valkey.io/) 模块，通过官方异步客户端 `valkey-glide` 接入，支持向量搜索、全文搜索和混合搜索三种模式。需要运行已加载该模块的服务，例如 `valkey/valkey-bundle:9.1.0`（`docker run -d -p 6379:6379 valkey/valkey-bundle:9.1.0`）。注意：混合搜索采用先过滤再 KNN 的模型，因此 `vector_weight` 参数虽被接受但**不会生效**（Valkey Search 原生限制）。连接为惰性建立，服务不可用或配置错误不会阻塞启动。详见 [Valkey Search 集成文档](https://github.com/langbot-app/LangBot/blob/master/docs/VALKEY_SEARCH_INTEGRATION.md)。 - `api.global_api_key` 是面向 Agent / 自动化的全局 API Key：设置后，调用 HTTP API 或内置 MCP 服务（`/mcp`）时在请求头携带 `X-API-Key: ` 或 `Authorization: Bearer ` 即可鉴权，无需登录会话、无需在数据库中创建 `lbk_` 密钥。它是明文写在 `config.yaml` 中的，请仅在可信 / 内网环境启用，并通过 HTTPS 暴露。详见 [API Key 鉴权](https://github.com/langbot-app/LangBot/blob/master/docs/API_KEY_AUTH.md)。 ## 通过环境变量设置