docs(deploy): clarify optional SeekDB installation

2026-10-28 19:35:27 +08:00 · 2026-08-21 12:07:48 +08:00
parent 7200a97bb4
commit 33fb2e1f61
18 changed files with 117 additions and 8 deletions
@@ -45,6 +45,14 @@ This starts `langbot`, `langbot_plugin_runtime`, and `langbot_box`. If you only
 docker compose up
 ```

+## SeekDB support
+
+The official Docker image already includes the optional SeekDB dependencies;
+no additional build argument is required. The container uses the matching
+Linux `pylibseekdb` wheel, so the host macOS version does not limit embedded
+mode inside the container. Keep the default `vdb.use: chroma` when SeekDB is
+not needed.
+
 `langbot_box` creates sandbox containers through the host Docker socket, so the Box root path must be identical on the host and inside the container:

 ```yaml
@@ -47,6 +47,12 @@ kubectl port-forward -n langbot svc/langbot 5300:5300

 For production, expose via Ingress + TLS (the manifest already includes commented Ingress / LoadBalancer / NodePort examples — uncomment as needed).

+### Using SeekDB
+
+The official image already includes the optional SeekDB dependencies, so no
+dedicated image or additional build argument is required. Set `vdb.use` to
+`seekdb` to enable it, or keep the default `chroma` when it is not needed.
+
 ## Box Sandbox Runtime

 `langbot-box` provides the code-sandbox capability backing the sandbox tools (`exec` / `read` / `write` / `edit` / `glob` / `grep`), the skill `activate` tool and skill add/edit, and stdio-mode MCP servers. It is **optional**: without it, LangBot still runs and the dashboard / skills list stay visible (read-only), but those features are disabled — in that case set `BOX__ENABLED=false` on `langbot`.
@@ -18,6 +18,17 @@ pip install uv
 uv sync
 ```

+The default installation does not include optional SeekDB support. If you need
+the SeekDB vector store or built-in embedding model, use:
+
+```bash
+uv sync --extra seekdb
+```
+
+Embedded-mode platform support depends on the available `pylibseekdb` wheels;
+Apple Silicon currently requires macOS 15 or later. All other LangBot features
+can use the default `uv sync` installation.
+
 3. Run the main program once to generate configuration files

 ```bash
@@ -14,3 +14,20 @@ uvx langbot@latest
 ```

 This will set the current directory as the working directory, and you can access `http://localhost:5300` to start using it.
+
+## Optional SeekDB support
+
+The default installation uses Chroma and does not include the SeekDB Python
+SDK or native components. Install the `seekdb` extra only when you want to use
+SeekDB as the vector store or use its built-in embedding model:
+
+```bash
+uvx --from 'langbot[seekdb]@latest' langbot
+```
+
+SeekDB embedded mode also requires a compatible `pylibseekdb` wheel. Apple
+Silicon currently requires macOS 15 or later; follow
+[oceanbase/seekdb#1324](https://github.com/oceanbase/seekdb/issues/1324) for the
+macOS 14 ARM64 support plan. Because of the current `pyseekdb` package
+metadata, the extra also fails to resolve on macOS 14 ARM64 for server-only
+use. These platform limits do not affect LangBot when SeekDB is not installed.
@@ -195,6 +195,9 @@ vdb:
        host: localhost
        port: 6333
        api_key: ''
+    # SeekDB is optional. Source/package deployments need the `seekdb` extra.
+    # The official Docker/Kubernetes image already includes it.
+    # Embedded-mode platform support depends on the native pylibseekdb wheels.
    seekdb:
        mode: embedded  # 'embedded' or 'server'
        # Embedded mode options:
@@ -439,6 +442,7 @@ Treat the global API key, JWT secret, database credentials, S3 credentials, emai
 - `database.use` selects SQLite or PostgreSQL. A non-empty `database.postgresql.url` overrides the structured connection fields and preserves TLS/query options.
 - PostgreSQL pool and timeout settings bound shared runtime resources. `database.cloud_migration.operator_dsn_env` names the environment variable containing the operator-only migration DSN; keep that role separate from the runtime role.
 - `vdb.use` selects the vector backend. Configure only the selected backend. `runtime_cache_limit` bounds process-local collection/index handles.
+- `vdb.use: seekdb` requires `uv sync --extra seekdb` for a source deployment or `uvx --from 'langbot[seekdb]@latest' langbot` for a package deployment. The official Docker/Kubernetes image already includes the dependency and needs no additional build argument.
 - `vdb.pgvector.use_business_database` reuses `database.postgresql`; `allowed_dimensions` controls the partial ANN indexes created by release migrations.
 - Valkey Search requires a Valkey server with the Search module, such as `valkey/valkey-bundle:9.1.0`.

@@ -46,8 +46,8 @@ Embedding models are used to compute vector representations of messages. If you

 Enter these four parameters: `Model Name`, `Model Provider`, `Request URL`, and `API Key`, then submit. After that, please configure the knowledge base to use this model.

-### Using seekdb Built-in Embedding Model (Zero Configuration)
-The system has integrated the official embedding model provided by seekdb, no parameters required.
+### Using the seekdb Built-in Embedding Model (Optional Dependency Required)
+The model needs no request parameters. Use `uv sync --extra seekdb` for source deployments or `uvx --from 'langbot[seekdb]@latest' langbot` for package deployments. The official Docker/Kubernetes image already includes the SeekDB dependency. Native deployment support depends on the available `pylibseekdb` wheel.
 - On the "Embedding Model" page, select "seekdb-built-in";
 - Click "Save" to use it immediately;
 - Then select this model in your knowledge base to take effect.
@@ -44,6 +44,10 @@ docker compose --profile all up -d
 docker compose up
 ```

+## SeekDB サポート
+
+公式 Docker イメージにはオプションの SeekDB 依存関係がすでに含まれており、追加のビルド引数は不要です。コンテナは対応する Linux アーキテクチャの `pylibseekdb` wheel を使用するため、ホストの macOS バージョンはコンテナ内の組み込みモードを制限しません。SeekDB を使用しない場合は、デフォルトの `vdb.use: chroma` のまま使用できます。
+
 `langbot_box` はホスト Docker socket 経由でサンドボックスコンテナを作成するため、Box root のホスト側パスとコンテナ内パスは同一である必要があります：

 ```yaml
@@ -47,6 +47,10 @@ kubectl port-forward -n langbot svc/langbot 5300:5300

 本番環境では Ingress + TLS での公開を推奨します（マニフェストにはコメントアウトされた Ingress / LoadBalancer / NodePort の例が含まれているので、必要に応じてコメントを解除してください）。

+### SeekDB を使用する場合
+
+公式イメージにはオプションの SeekDB 依存関係がすでに含まれているため、専用イメージや追加のビルド引数は不要です。`vdb.use` を `seekdb` に設定すると有効になり、不要な場合はデフォルトの `chroma` のまま使用できます。
+
 ## Box サンドボックスランタイム

 `langbot-box` は LangBot にコードサンドボックス機能を提供し、サンドボックスツール（`exec` / `read` / `write` / `edit` / `glob` / `grep`）、スキルの `activate` ツールと追加・編集、および stdio モードの MCP サーバーを支えます。これは**任意のコンポーネント**です：デプロイしなくても LangBot は動作し、ダッシュボードとスキル一覧は読み取り専用で表示されますが、上記の機能は無効になります。その場合は `langbot` に `BOX__ENABLED=false` を設定してください。
@@ -18,6 +18,14 @@ pip install uv
 uv sync
 ```

+デフォルトのインストールにはオプションの SeekDB サポートは含まれません。SeekDB ベクトルストアまたは組み込み埋め込みモデルを使用する場合は、次を実行します：
+
+```bash
+uv sync --extra seekdb
+```
+
+組み込みモードの対応プラットフォームは `pylibseekdb` wheel に依存します。Apple Silicon では現在 macOS 15 以降が必要です。その他の LangBot 機能はデフォルトの `uv sync` で利用できます。
+
 3. メインプログラムを一度実行して設定ファイルを生成します

 ```bash
@@ -14,3 +14,13 @@ uvx langbot@latest
 ```

 これにより現在のディレクトリが作業ディレクトリとして設定され、`http://localhost:5300`にアクセスして使用を開始できます。
+
+## オプションの SeekDB サポート
+
+デフォルトのインストールでは Chroma を使用し、SeekDB の Python SDK とネイティブコンポーネントは含まれません。SeekDB をベクトルストアとして使用する場合、または組み込み埋め込みモデルを使用する場合だけ `seekdb` extra を指定します：
+
+```bash
+uvx --from 'langbot[seekdb]@latest' langbot
+```
+
+SeekDB の組み込みモードには、現在のプラットフォームに対応する `pylibseekdb` wheel も必要です。Apple Silicon では現在 macOS 15 以降が必要です。macOS 14 ARM64 の対応予定は [oceanbase/seekdb#1324](https://github.com/oceanbase/seekdb/issues/1324) を参照してください。現在の `pyseekdb` package metadata のため、macOS 14 ARM64 ではサーバーモードだけを使う場合も extra を解決できません。SeekDB をインストールしない場合、この制限は LangBot に影響しません。
@@ -159,7 +159,9 @@ vdb:
        host: localhost
        port: 6333
        api_key: ''
-    # SeekDB の組み込みまたはサーバーモード設定です。
+    # SeekDB はオプションです。ソース/package デプロイでは `seekdb` extra が必要です。
+    # 公式 Docker/Kubernetes イメージにはすでに含まれています。
+    # 組み込みモードの対応環境は pylibseekdb wheel に依存します。
    seekdb:
        mode: embedded
        path: './data/seekdb'
@@ -352,6 +354,7 @@ space:
 - `database.use` で SQLite または PostgreSQL を選択します。`database.postgresql.url` が空でなければ分割された接続項目より優先され、TLS/クエリオプションも保持できます。
 - PostgreSQL のプールとタイムアウトは共有ランタイム資源を制限します。`database.cloud_migration.operator_dsn_env` は運用者専用のマイグレーション DSN を格納する環境変数名で、ランタイムロールとは分離してください。
 - `vdb.use` で利用するベクトルバックエンドを選びます。実際に選択したバックエンドだけを設定します。
+- `vdb.use: seekdb` は、ソースデプロイでは `uv sync --extra seekdb`、パッケージデプロイでは `uvx --from 'langbot[seekdb]@latest' langbot` が必要です。公式 Docker/Kubernetes イメージには依存関係がすでに含まれており、追加のビルド引数は不要です。
 - `vdb.pgvector.use_business_database` は `database.postgresql` を再利用します。`allowed_dimensions` はリリースマイグレーションが作成する ANN インデックスの次元を制御します。
 - Valkey Search には Search モジュール入りの Valkey（例: `valkey/valkey-bundle:9.1.0`）が必要です。

@@ -46,8 +46,8 @@ LangBot Modelsは、LangBotが公式に提供するモデルサービスです

 これら4つのパラメータを入力します: `モデル名`、`モデルプロバイダー`、`リクエストURL`、`APIキー`、そして送信します。その後、ナレッジベースでこのモデルを使用するように設定してください。

-### seekdb内蔵埋め込みモデルの使用（ゼロ設定）
-システムにはseekdbが提供する公式埋め込みモデルが統合されており、パラメータの入力は不要です。
+### seekdb 内蔵埋め込みモデルの使用（オプション依存関係が必要）
+リクエストパラメータの入力は不要です。ソースデプロイでは `uv sync --extra seekdb`、パッケージデプロイでは `uvx --from 'langbot[seekdb]@latest' langbot` を使用します。公式 Docker/Kubernetes イメージには SeekDB 依存関係がすでに含まれています。ネイティブデプロイの対応環境は `pylibseekdb` wheel に依存します。
 - 「埋め込みモデル」ページで「seekdb-内蔵」を選択します；
 - 「保存」をクリックするとすぐに使用できます；
 - その後、ナレッジベースでこのモデルを選択すると有効になります。
@@ -45,6 +45,10 @@ docker compose --profile all up -d
 docker compose up
 ```

+## SeekDB 支持
+
+官方 Docker 镜像已经包含可选的 SeekDB 依赖，无需额外构建参数。容器会使用对应 Linux 架构的 `pylibseekdb` wheel，因此宿主机的 macOS 版本不会限制容器内的 embedded 模式；不使用 SeekDB 时保持默认 `vdb.use: chroma` 即可。
+
 `langbot_box` 通过主机 Docker socket 创建沙箱容器，因此 Box 根目录的宿主机路径和容器内路径必须一致：

 ```yaml
@@ -47,6 +47,10 @@ kubectl port-forward -n langbot svc/langbot 5300:5300

 生产环境推荐使用 Ingress + TLS 对外暴露（清单中已附带被注释的 Ingress / LoadBalancer / NodePort 示例，按需取消注释）。

+### 使用 SeekDB
+
+官方镜像已经包含可选的 SeekDB 依赖，无需构建专用镜像或添加额外构建参数。将 `vdb.use` 配置为 `seekdb` 即可启用；不使用时保持默认的 `chroma`。
+
 ## Box 沙箱运行时

 `langbot-box` 为 LangBot 提供代码沙箱能力，支撑沙箱工具（`exec` / `read` / `write` / `edit` / `glob` / `grep`）、技能的 `activate` 工具与新增/编辑、以及 stdio 模式的 MCP 服务器。它是**可选组件**：不部署时 LangBot 仍可运行，仪表盘与技能列表只读可见，但上述能力会被禁用，此时请在 `langbot` 上设置 `BOX__ENABLED=false`。
@@ -22,6 +22,14 @@ pip install uv
 uv sync
 ```

+默认安装不包含可选的 SeekDB 支持。如果需要使用 SeekDB 向量数据库或内置嵌入模型，请改用：
+
+```bash
+uv sync --extra seekdb
+```
+
+SeekDB 嵌入式模式的平台支持取决于 `pylibseekdb` wheel；Apple Silicon 当前要求 macOS 15 或更高版本。其他功能仍可使用默认的 `uv sync` 安装。
+
 或者使用清华源

 ```bash
@@ -14,3 +14,18 @@ uvx langbot@latest
 ```

 这将把该目录作为工作目录，访问 `http://localhost:5300` 即可开始使用。
+
+## 可选的 SeekDB 支持
+
+默认安装使用 Chroma，不包含 SeekDB 的 Python SDK 和原生组件。只有在需要将
+SeekDB 用作向量数据库或使用其内置嵌入模型时，才用 `seekdb` extra 启动：
+
+```bash
+uvx --from 'langbot[seekdb]@latest' langbot
+```
+
+SeekDB 嵌入式模式还要求当前平台存在兼容的 `pylibseekdb` wheel。Apple Silicon
+目前要求 macOS 15 或更高版本；macOS 14 ARM64 的支持计划见
+[oceanbase/seekdb#1324](https://github.com/oceanbase/seekdb/issues/1324)。受当前
+`pyseekdb` 包元数据影响，macOS 14 ARM64 即使只连接远程 SeekDB，也无法解析该
+extra。不使用 SeekDB 时，这些平台限制不影响 LangBot。
@@ -159,7 +159,9 @@ vdb:
        host: localhost
        port: 6333
        api_key: ''
-    # SeekDB 嵌入式或服务端模式参数。
+    # SeekDB 是可选功能；源码/包管理器部署需安装 langbot[seekdb] extra。
+    # 官方 Docker/Kubernetes 镜像已包含该依赖。
+    # 嵌入式模式的平台支持取决于 pylibseekdb wheel。
    seekdb:
        mode: embedded
        path: './data/seekdb'
@@ -379,6 +381,7 @@ space:
 - PostgreSQL 的 `pool_size`、`max_overflow`、连接池超时与回收参数共同限制连接资源；三个数据库超时字段只应用于 Cloud 运行时连接。
 - `database.cloud_migration.operator_dsn_env` 指定 Cloud 发布迁移读取的运维级 DSN 环境变量。运维角色必须与运行时角色分离，密码不要写入配置文件或命令行参数。
 - `vdb.use` 选择向量后端。页面列出了 Qdrant、SeekDB、Milvus、pgvector 与 Valkey Search 的连接参数；只需要配置实际选中的后端。
+- `vdb.use: seekdb` 在源码部署中要求执行 `uv sync --extra seekdb`，包管理器部署使用 `uvx --from 'langbot[seekdb]@latest' langbot`。官方 Docker/Kubernetes 镜像已包含该依赖，无需额外构建参数。
 - `vdb.runtime_cache_limit` 限制进程内集合/索引句柄数量。
 - `vdb.pgvector.use_business_database: true` 表示复用 `database.postgresql`；`allowed_dimensions` 限定发布迁移创建 ANN 索引的向量维度。
 - `vdb.valkey_search` 需要带 Search 模块的 Valkey 服务，例如 `valkey/valkey-bundle:9.1.0`。连接按需建立，支持 HNSW/FLAT 与 COSINE/L2/IP。
@@ -63,8 +63,8 @@ LangBot Models 是 LangBot 官方提供的模型服务。当您使用 LangBot Sp

 填入 `模型名称`、选择 `模型供应商`，然后提交即可。之后请在知识库中配置使用此模型。

-### 使用 seekdb 内置嵌入模型（零配置）
-系统已集成 seekdb 提供的官方嵌入模型，无需填写任何参数。
+### 使用 seekdb 内置嵌入模型（需要可选依赖）
+该模型无需填写请求参数。源码部署使用 `uv sync --extra seekdb`，包管理器部署使用 `uvx --from 'langbot[seekdb]@latest' langbot`；官方 Docker/Kubernetes 镜像已包含 SeekDB 依赖。原生部署的平台支持取决于 `pylibseekdb` wheel。
 - 在”嵌入模型”页面选择「seekdb-内置」；
 - 点击「保存」即可立即使用；
 - 后续在知识库中选择该模型即可生效。