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: 合并快速开始为单一 CLI 优先的 server 服务路径 (#5195)
Zayn Jarvisb05cc863104e
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 7d5d485fb..70a6fd02b 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -109,14 +109,12 @@ const gettingStartedSidebar = {en: [['01-introduction.md', 'Introduction'],['02-quickstart.md', 'Quick Start'],- ['03-quickstart-server.md', 'Server Deployment'],['04-setup-for-agent.md', 'Server Setup for Agent'],['05-cli-setup.md', 'OpenViking CLI']],zh: [['01-introduction.md', '简介'],['02-quickstart.md', '快速开始'],- ['03-quickstart-server.md', '服务端部署'],['04-setup-for-agent.md', '服务端安装(Agent 版)'],['05-cli-setup.md', 'OpenViking CLI']]diff --git a/docs/en/getting-started/01-introduction.md b/docs/en/getting-started/01-introduction.mdindex 6ecca3bac..64ac90076 100644--- a/docs/en/getting-started/01-introduction.md+++ b/docs/en/getting-started/01-introduction.md@@ -8,7 +8,7 @@ Use it when an agent needs to reuse documents and experience across sessions, wi| I want to… | Start here || --- | --- |-| Run a server and retrieve my first document | [Quick Start](./02-quickstart.md) |+| Connect to a service and retrieve my first document | [Quick Start](./02-quickstart.md) || Connect an existing agent or coding tool | [Agent Integrations](../agent-integrations/01-overview.md) || Use OpenViking from a terminal | [CLI Setup](./05-cli-setup.md) || Deploy and operate a shared server | [Deployment](../guides/03-deployment.md) and [Authentication](../guides/04-authentication.md) |diff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.mdindex cc6d9cbb1..80ae70a90 100644--- a/docs/en/getting-started/02-quickstart.md+++ b/docs/en/getting-started/02-quickstart.md@@ -1,268 +1,104 @@# Quick Start-Start a local server, import a resource, and run your first search.+OpenViking runs as a server. Connect to it with the standalone `ov` CLI, import a small document, and retrieve its content. If you use a managed service or someone else's deployment, you only need the CLI.-## Prerequisites+## 1. Choose a service-Before using OpenViking, ensure your environment meets the following requirements:+**Already have an endpoint?** Keep its URL and API key ready and skip to step 2. For a server using API key authentication, use a user/admin key for data access; a root key is for administration. See [Authentication](../guides/04-authentication.md).-- **Python Version**: 3.10 or higher-- **Operating System**: Linux, macOS, Windows-- **Network Connection**: Stable network connection required (for downloading dependencies and accessing model services)+Otherwise, choose one:-## Installation & Startup+### Managed service on Volcengine-Choose one server installation method: a Python package or Docker. The Python SDK connects to either server over HTTP.+Open the [OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing) and obtain your key from **User Management → API Key**. The service endpoint is:-### Option 1: Install the server and CLI--Choose your preferred Python package manager to install OpenViking:--::: code-group--```bash [uv (recommended)]-uv tool install openviking --upgrade-```--```bash [pip]-python -m pip install openviking --upgrade+```text+https://api.vikingdb.cn-beijing.volces.com/openviking```-```bash [pipx]-# Install-pipx install openviking--# Update-pipx upgrade openviking-```--:::--After installation, use `ov` as the client command (`openviking` is an alias) and `openviking-server` as the server command.--### Option 2: Start via Docker (As an independent service)--If you prefer to run OpenViking as a standalone service, Docker is recommended.--1. **Prepare Configuration Directory**- Create the OpenViking directory on your host and prepare the `ov.conf` configuration file (see the "Configuration" section below for details). All persistent state — config and workspace data — lives under this single directory:- ```bash- mkdir -p ~/.openviking- ```-- Write a complete JSON configuration to `~/.openviking/ov.conf` using the manual template below before starting the container. An empty file is not a valid configuration.--2. **Start with Docker Compose**- Create a `docker-compose.yml` file:- ```yaml- services:- openviking:- # Prefer ghcr.io. If it is hard to reach, use openviking-cn-beijing.cr.volces.com/volcengine/openviking:latest- image: ghcr.io/volcengine/openviking:latest- container_name: openviking- ports:- - "127.0.0.1:1933:1933"- volumes:- - ~/.openviking:/app/.openviking- restart: unless-stopped- ```- Then run the following command in the same directory:- ```bash- docker compose up -d- ```-- By default, the container starts the OpenViking API server on `1933` (which also serves the Web Studio UI at `/studio`) and the bundled `vikingbot` gateway. If you need to disable `vikingbot`, add either `command: ["--without-bot"]` or `environment: ["OPENVIKING_WITH_BOT=0"]`.-- On platforms that don't allow bind mounts, set `OPENVIKING_CONF_CONTENT` to the full config JSON to bootstrap on first start, or `docker exec` in and run `openviking-server init` after the container is up. See [Deployment Guide](../guides/03-deployment.md#when-docker-v-is-not-available) for details.--The container entrypoint binds to `0.0.0.0` inside the container. The [port mapping](https://docs.docker.com/engine/network/port-publishing/) above makes it accessible at `http://localhost:1933` on the host, including macOS. For access from other machines, see [Authentication](../guides/04-authentication.md) and [Public Access](../guides/12-public-access.md).--## Model Preparation--OpenViking requires the following model capabilities:-- **VLM Model**: For image and content understanding-- **Embedding Model**: For vectorization and semantic retrieval+No server installation or local model configuration is needed. See the [product page](https://www.volcengine.com/product/openviking-service) and [service documentation](https://docs.volcengine.com/docs/84313/2374478) for managed-service usage and limits. Continue to step 2.-OpenViking supports multiple model services:-- **Volcengine (Doubao Models)**: Recommended, cost-effective with good performance, free quota for new users. For purchase and activation, see: [Volcengine Purchase Guide](../guides/02-volcengine-purchase-guide.md)-- **OpenAI Models**: Supports vision-capable models and embedding models through the OpenAI API-- **OpenAI Codex**: Supports Codex as the VLM provider through ChatGPT/Codex OAuth-- **Other Custom Model Services**: Supports model services compatible with OpenAI API format+### Self-host a server-## Configuration--### Configuration File Template--For a Python package installation, use the setup wizard:+[Install uv](https://docs.astral.sh/uv/getting-started/installation/) on the server machine, then install OpenViking:```bash+uv tool install openviking --upgradeopenviking-server initopenviking-server doctor+openviking-server```-For Docker, or if you prefer manual setup, create `~/.openviking/ov.conf`:--```json-{- "embedding": {- "dense": {- "api_base" : "<api-endpoint>",- "api_key" : "<your-api-key>",- "provider" : "<provider-type>",- "dimension": 1024,- "model" : "<model-name>"- }- },- "vlm": {- "api_base" : "<api-endpoint>",- "api_key" : "<your-api-key>",- "provider" : "<provider-type>",- "model" : "<model-name>"- }-}-```--`provider`, `model`, `api_base`, and `api_key` depend on the VLM service you choose. Some providers may use local OAuth state instead of a manually copied API key.+The setup wizard configures the server's models and writes `~/.openviking/ov.conf`. Prepare access to an embedding model and a VLM — Volcengine (Doubao) models are recommended; see the [Volcengine Purchase Guide](../guides/02-volcengine-purchase-guide.md) for purchase and activation — then check the configuration with `doctor`. Keep the server running and use another terminal for the remaining steps.-For complete examples for each model provider, see [Configuration Guide - Examples](../guides/01-configuration.md#configuration-examples).+A single curl confirms the server is up — no client required:-For first-time setup, `openviking-server init` is the recommended path. It helps you pick a provider and writes a working config template for the selected setup.+```bash+curl http://127.0.0.1:1933/health+# {"status":"ok","healthy":true,...}+```-### Environment Variables+The local endpoint is `http://127.0.0.1:1933`; the default local setup needs no API key. Web Studio is available at `/studio`. For Docker, persistent storage, and remote access, see [Deployment](../guides/03-deployment.md), [Model Configuration](../guides/01-configuration.md), and [Authentication](../guides/04-authentication.md).-When the config file is at the default path `~/.openviking/ov.conf`, no additional setup is needed — OpenViking loads it automatically.+## 2. Install and connect the CLI-If the config file is at a different location, specify it via environment variable:+On your client machine, with Node.js and npm installed:```bash-export OPENVIKING_CONFIG_FILE=/path/to/your/ov.conf+npm install -g @openviking/cli+ov language en+ov config```-## Start the Local Server+In the interactive configuration, choose **OpenViking Service** for Volcengine or **Custom** for a self-hosted endpoint. Enter the API key and, for a custom service, its URL. Leave the key empty for the default local server. Save and activate the configuration.-After configuring a Python package installation, start the server. If Docker is already running, skip this step:+The CLI stores the active connection in `~/.openviking/ovcli.conf`. This is separate from the server's `ov.conf`. For scripted setup or multiple endpoints, see [CLI Setup](05-cli-setup.md).-```bash-openviking-server-```+Verify the connection:-Keep the server running and open another terminal for the Python SDK example below.-To use a custom config path, start it with `openviking-server --config /path/to/ov.conf`.--The default local setup does not require an API key. For an authenticated server, set-`OPENVIKING_API_KEY` before running the example.--## Run Your First Example--### Create Python Script--Create `example.py`:--```python-import time--from openviking_sdk import SyncHTTPClient--# Connect to the local OpenViking Server-client = SyncHTTPClient(url="http://localhost:1933")--try:- # Check the connection- client.initialize()-- # Add resource (supports URL, file, or directory)- # Local directory scans respect .gitignore by default.- add_result = client.add_resource(- path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",- )-- task_id = add_result["task_id"]- print(f"Import task: {task_id}")- while True:- task = client.get_task(task_id)- if task is None:- raise RuntimeError(f"Task {task_id} is no longer available")- if task["status"] == "completed":- break- if task["status"] in {"failed", "cancelled"}:- raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")- time.sleep(2)- root_uri = task["result"]["root_uri"]-- # Explore the resource tree structure- ls_result = client.ls(uri=root_uri)- print(f"Directory structure:\n{ls_result}\n")-- # Use glob to find markdown files- glob_result = client.glob(pattern="**/*.md", uri=root_uri)- if glob_result['matches']:- content = client.read(uri=glob_result["matches"][0])- print(f"Content preview: {content[:200]}...\n")-- # Get abstract and overview of the resource- abstract = client.abstract(uri=root_uri)- overview = client.overview(uri=root_uri)- print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n")-- # Perform semantic search- results = client.find(- query="what is openviking",- target_uri=root_uri,- )- print("Search results:")- for result in results.get("resources", []):- print(f" {result['uri']} (score: {result.get('score', 0.0):.4f})")--finally:- client.close()+```bash+ov health```-### Run the Script+This checks that the server responds; the import below also exercises model processing and data access.-Install the SDK in the environment that runs the script. [`uv tool install`](https://docs.astral.sh/uv/guides/tools/#installing-tools) and `pipx install` isolate server dependencies; they do not install the SDK into your current Python environment. Docker also does not install a client on the host.+## 3. Import a document-::: code-group+Save the following as `quickstart.md` in your current directory:-```bash [uv]-uv run --with openviking-sdk python example.py-```+```markdown+# Project Atlas-```bash [pip (in your virtual environment)]-python -m pip install --upgrade openviking-sdk-python example.py+Project Atlas backs up its documents every Friday.+Maya owns the backup process. Keep each backup for 30 days.```-:::--### Expected Output+Import it into a new resource directory:+```bash+ov add-resource ./quickstart.md --to viking://resources/quickstart-demo --wait --timeout 120```-Import task: ...-Directory structure:-...+The CLI uploads the local file automatically. `--wait` waits for processing; continue after the command succeeds. Without it, save the returned `task_id` and use `ov task status <task_id>` until the task is `completed`. See [Background Tasks](../api/17-tasks.md).-Content preview: ...+Use an unused target URI for this example. If you repeat the example, choose a new target and use that same URI in the commands below.-Abstract:-...+## 4. Browse and search-Overview:-...--Search results:- viking://resources/... (score: 0.8523)- ...+```bash+ov tree viking://resources/quickstart-demo+ov overview viking://resources/quickstart-demo+ov find "Who owns the backup process?" --uri viking://resources/quickstart-demo```-Congratulations! You have successfully run OpenViking.+`tree` lists the imported structure; `overview` reads its generated summary. `find` returns relevant context with URIs and scores. To read a match, pass its returned URI to `ov read`:-## Server Mode+```bash+ov read "<returned-file-uri>"+```-Want to run OpenViking as a shared service? See [Quick Start: Server Mode](03-quickstart-server.md).+Replace `<returned-file-uri>` with a file URI from the results, without the angle brackets. For more resource types and retrieval options, see [Resources](../api/02-resources.md) and [Retrieval](../api/06-retrieval.md).-## Next Steps+## Use an SDK-- [Configuration Guide](../guides/01-configuration.md) - Detailed configuration options-- [API Overview](../api/01-overview.md) - API reference-- [Resource Management](../api/02-resources.md) - Resource management API+OpenViking also provides Python, TypeScript/JavaScript, and Go SDKs that connect to the same server. See the [API Overview](../api/01-overview.md) for client examples.diff --git a/docs/en/getting-started/03-quickstart-server.md b/docs/en/getting-started/03-quickstart-server.mdindex 152e27faa..f52787fc4 100644--- a/docs/en/getting-started/03-quickstart-server.md+++ b/docs/en/getting-started/03-quickstart-server.md@@ -1,223 +1,19 @@-# Quick Start: Server Mode+# Quick Start Has Moved-Run OpenViking as a standalone HTTP server and connect from any client.+<a id="quick-start-server-mode"></a>+OpenViking runs as an HTTP service. Server setup and client verification are now combined in the [Quick Start](02-quickstart.md), which starts with the independent CLI and covers managed, existing, and self-hosted services.-## Prerequisites+<a id="prerequisites"></a>+<a id="start-the-server"></a>+<a id="verify"></a>+<a id="connect-with-cli"></a>+For setup and your first import/search, follow the [Quick Start](02-quickstart.md). For named connections or scripted setup, see [CLI Setup](05-cli-setup.md).-- OpenViking installed (`uv tool install openviking --upgrade`)-- Model configuration ready (see [Quick Start](02-quickstart.md) for setup)+<a id="connect-with-python-sdk"></a>+<a id="authentication"></a>+<a id="connect-with-curl"></a>+For Python, TypeScript/JavaScript, Go, and HTTP examples, see the [API Overview](../api/01-overview.md), [Resource API](../api/02-resources.md), and [Authentication](../guides/04-authentication.md).-> Python 3.14 note for Volcengine Ark users:-> if your `ov.conf` uses `provider = "volcengine"` / Ark runtime, prefer Python 3.13 or lower for `openviking-server` right now.-> `volcengine-python-sdk[ark]` still emits a Pydantic V1 compatibility warning on Python 3.14, so the server works but startup/version commands may print noisy warnings until the upstream SDK removes that compatibility layer.--## Start the Server--Make sure you have a config file at `~/.openviking/ov.conf` with your model and storage settings (see [Configuration](../guides/01-configuration.md)).--For first-time setup, run `openviking-server init` first.--Before startup, validate local setup:--```bash-openviking-server doctor-```--`openviking-server doctor` validates that the configured local setup is usable, including provider-specific auth when required.--```bash-# Config file at default path ~/.openviking/ov.conf — just start-openviking-server--# Config file at a different location — specify with --config-openviking-server --config /path/to/ov.conf--# Use a different port-openviking-server --port 8000-```--You should see:--```-INFO: Uvicorn running on http://127.0.0.1:1933-```--## Verify--```bash-curl http://localhost:1933/health-# {"status": "ok"}-```--`openviking-server doctor` checks local configuration, model access, and auth readiness. `curl /health` only confirms that the server process is already running.--Web Studio is also served at `http://localhost:1933/studio` (bundled with pip/pipx installs since v0.3.21 — no Docker required).--## Connect with Python SDK--Install the standalone SDK in your client Python environment:--```bash-python -m pip install --upgrade openviking-sdk-```--Server installations made with `uv tool` or pipx use a separate environment. You can also run a saved script with `uv run --with openviking-sdk python example.py`.--```python-from openviking_sdk import SyncHTTPClient--client = SyncHTTPClient(url="http://localhost:1933")-```--### Authentication--When authentication is enabled, pass an API key. OpenViking uses a two-tier key system:--**Regular data access: use a `user_key` (recommended)**--For most scenarios, use a `user_key` — it directly works with tenant-scoped APIs like `add_resource`, `find`, and `ls`:--```python-from openviking_sdk import SyncHTTPClient--client = SyncHTTPClient(- url="http://localhost:1933",- api_key="<user-key>",-)-```--> `user_key` is created via the Admin API (see [Authentication](../guides/04-authentication.md)). The server can automatically resolve the tenant from the key.--**Administrative operations: use a `root_key`**--`root_key` is for management operations (creating accounts, system status, etc.).-Tenant-scoped data APIs such as `add_resource`, `find`, and sessions need a key-that is bound to an account/user, such as a user key or admin key:--```python-from openviking_sdk import SyncHTTPClient--client = SyncHTTPClient(- url="http://localhost:1933",- api_key="<user-or-admin-key>",-)-```--> Using `root_key` for tenant-scoped data APIs in `api_key` mode returns-> `PERMISSION_DENIED`. Use a user/admin key for data access, or trusted mode for-> upstream identity assertion.--See [Authentication](../guides/04-authentication.md) for details (trusted mode, CLI config, etc.).--**Full example:**--For an authenticated server, set `OPENVIKING_API_KEY` to a user/admin key before running this script. The SDK reads this environment variable automatically.--```python-import time--from openviking_sdk import SyncHTTPClient--client = SyncHTTPClient(url="http://localhost:1933")--try:- client.initialize()-- # Add a resource- result = client.add_resource(- path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",- )-- task_id = result["task_id"]- print(f"Import task: {task_id}")- while True:- task = client.get_task(task_id)- if task is None:- raise RuntimeError(f"Task {task_id} is no longer available")- if task["status"] == "completed":- break- if task["status"] in {"failed", "cancelled"}:- raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")- time.sleep(2)- root_uri = task["result"]["root_uri"]-- # Search- results = client.find(- query="what is openviking",- target_uri=root_uri,- )- for result in results.get("resources", []):- print(f" {result['uri']} (score: {result.get('score', 0.0):.4f})")--finally:- client.close()-```--## Connect with CLI--For the default local server, omit `api_key`. For an authenticated server, replace `your-key` below with a user/admin key.--Create a CLI config file `~/.openviking/ovcli.conf` that points to your server:--```json-{- "url": "http://localhost:1933",- "api_key": "your-key"-}-```--Once configured, use the CLI to manage resources and query your Agent's memory:--```bash-# Check system health-openviking observer system--# Add a resource to memory-openviking add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md--# List all synchronized resources-openviking ls viking://resources--# Query-openviking find "what is openviking"--```--If the config file is at a different location, specify it via environment variable:--```bash-export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf-```--## Connect with curl--The examples below use the default local server. With authentication enabled, add `-H "X-API-Key: $OPENVIKING_API_KEY"` to each request, using a user/admin key. Resource imports are asynchronous: poll `GET /api/v1/tasks/{task_id}` with the returned `task_id` until it completes before searching.--Use direct `path` for remote URLs. For local files, upload first with `POST /api/v1/resources/temp_upload`, then call the target API with the returned `temp_file_id`. For local directories in raw HTTP mode, zip the directory first and upload the `.zip` file.--```bash-# Add a resource-curl -X POST http://localhost:1933/api/v1/resources \- -H "Content-Type: application/json" \- -d '{"path": "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"}'--# List resources-curl "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/"--# Semantic search-curl -X POST http://localhost:1933/api/v1/search/find \- -H "Content-Type: application/json" \- -d '{"query": "what is openviking"}'-```--## Deploy on a cloud server--For Volcengine ECS, create an instance in the [official ECS console](https://console.volcengine.com/ecs/). Follow the [Deployment Guide](../guides/03-deployment.md) for persistent storage, Docker, and service management.--The local server binds to `127.0.0.1` by default. Before allowing remote clients, configure [authentication](../guides/04-authentication.md), a reachable bind address, and the required network access rules. See [Public Access](../guides/12-public-access.md) for TLS and reverse-proxy configuration. Use a tenant-bound user/admin key for data access.--## Next Steps--- [Server Deployment](../guides/03-deployment.md) - Configuration, authentication, and deployment options-- [API Overview](../api/01-overview.md) - Complete API reference-- [Authentication](../guides/04-authentication.md) - Secure your server with API keys+<a id="deploy-on-a-cloud-server"></a>+<a id="next-steps"></a>+For Docker, storage, service management, or a managed service, see [Deployment](../guides/03-deployment.md). Configure [Public Access](../guides/12-public-access.md) before exposing a self-hosted service.diff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.mdindex becc3b9fc..b4b68ab71 100644--- a/docs/en/getting-started/05-cli-setup.md+++ b/docs/en/getting-started/05-cli-setup.md@@ -2,7 +2,7 @@This guide helps you install the OpenViking CLI, configure it, and verify that it can connect to OpenViking.-`ov` is the client CLI. It connects to an existing OpenViking server or to OpenViking Service (VolcEngine Cloud). It does not replace server setup. If you still need to install or start a custom OpenViking server, follow the [Quick Start](02-quickstart.md) or the [Server Mode guide](03-quickstart-server.md) first.+`ov` is the client CLI. It connects to an existing OpenViking server or to OpenViking Service (VolcEngine Cloud). It does not replace server setup. If you still need to install or start a custom OpenViking server, follow the [Quick Start](02-quickstart.md) first.Use this page in either of two ways:@@ -284,7 +284,7 @@ For a local unauthenticated server:ov config add custom --name <CONFIG-NAME> --url http://127.0.0.1:1933 --activate -o json```-If the local server is not running, guide the user to start it first. See the [Server Mode guide](03-quickstart-server.md).+If the local server is not running, guide the user to start it first. See the [Deployment Guide](../guides/03-deployment.md).### Add a Remote Custom Server@@ -431,7 +431,7 @@ Use this only when the user chose local custom setup. Then verify the server:curl http://127.0.0.1:1933/health```-If it fails, start the server before configuring `ov`. See the [Server Mode guide](03-quickstart-server.md).+If it fails, start the server before configuring `ov`. See the [Deployment Guide](../guides/03-deployment.md).### API Key Validation Failsdiff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.mdindex c89f8f6a1..e6cdcd52b 100644--- a/docs/en/guides/03-deployment.md+++ b/docs/en/guides/03-deployment.md@@ -1,11 +1,23 @@# Server Deployment-OpenViking can run as a standalone HTTP server, allowing multiple clients to connect over the network.+OpenViking runs as an HTTP service. Choose who operates it before installing a server:++| Service | What you need |+| --- | --- |+| [Volcano Engine managed OpenViking](https://www.volcengine.com/product/openviking-service) | Obtain an API key in the [console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing), then connect with the independent CLI. No local server or model configuration is needed. |+| An existing team or remote deployment | Obtain the service URL and a user/admin key from its administrator. |+| Self-hosted OpenViking | Install and configure the server using the instructions below. |++Managed and existing-service users can start with the [CLI quickstart](../getting-started/02-quickstart.md). For managed-service availability, plans, and limits, see the [official service documentation](https://docs.volcengine.com/docs/84313/2374478).++The rest of this guide covers self-hosting.For sizing, measure memory and disk use with a representative corpus and expected concurrency. Budget storage for source files, indexes, and snapshots; use [observability](../guides/05-observability.md) to check headroom before expanding the workload.## Quick Start+Install the server first using the [self-hosted quickstart](../getting-started/02-quickstart.md). For Volcengine Ark on Python 3.14, the upstream Python SDK may emit Pydantic V1 compatibility warnings; Python 3.13 avoids that warning in this setup.+```bash# Create or refresh ~/.openviking/ov.conf with the setup wizardopenviking-server init@@ -21,9 +33,8 @@ openviking-server# Or specify a custom config pathopenviking-server --config /path/to/ov.conf-# Verify it's running-curl http://localhost:1933/health-# {"status": "ok"}+# In another terminal, configure ov for this server using the quickstart, then verify+ov health```## Command Line Optionsdiff --git a/docs/en/guides/11-grafana-prometheus.md b/docs/en/guides/11-grafana-prometheus.mdindex 9bc3001f9..a120d0800 100644--- a/docs/en/guides/11-grafana-prometheus.md+++ b/docs/en/guides/11-grafana-prometheus.md@@ -462,4 +462,4 @@ It is recommended to first go back to Explore and manually run PromQL to confirm- [Metrics](../concepts/12-metrics.md)- [Metrics API](../api/09-metrics.md)- [Server Deployment](03-deployment.md)-- [Quick Start: Server Mode](../getting-started/03-quickstart-server.md)+- [Quick Start](../getting-started/02-quickstart.md)diff --git a/docs/zh/getting-started/01-introduction.md b/docs/zh/getting-started/01-introduction.mdindex fe7ea409e..b17992aba 100644--- a/docs/zh/getting-started/01-introduction.md+++ b/docs/zh/getting-started/01-introduction.md@@ -8,7 +8,7 @@ OpenViking 是面向 AI Agent 的开源上下文数据库。它用虚拟文件| 我想要…… | 阅读入口 || --- | --- |-| 启动服务并检索第一份文档 | [快速开始](./02-quickstart.md) |+| 连接服务并检索第一份文档 | [快速开始](./02-quickstart.md) || 接入已有 Agent 或编程工具 | [Agent 集成](../agent-integrations/01-overview.md) || 在终端使用 OpenViking | [CLI 配置](./05-cli-setup.md) || 部署和运维共享服务 | [部署](../guides/03-deployment.md)与[认证](../guides/04-authentication.md) |diff --git a/docs/zh/getting-started/02-quickstart.md b/docs/zh/getting-started/02-quickstart.mdindex 38e9b626d..b8cc7f42f 100644--- a/docs/zh/getting-started/02-quickstart.md+++ b/docs/zh/getting-started/02-quickstart.md@@ -1,268 +1,104 @@# 快速开始-启动本地服务,导入一份资源,然后完成第一次检索。+OpenViking 以服务端运行。用独立的 `ov` CLI 连接服务,导入一份小文档,再检索其中的内容。使用托管服务或他人部署的服务时,只需安装 CLI。-## 前置要求+## 1. 选择服务-在开始使用 OpenViking 之前,请确保您的环境满足以下要求:+**已有服务地址?** 准备好 URL 和 API Key,直接跳到第 2 步。服务采用 API Key 认证时,数据访问使用 user/admin key,root key 用于管理操作。详见[认证](../guides/04-authentication.md)。-- **Python 版本**:3.10 或更高版本-- **操作系统**:Linux、macOS、Windows-- **网络连接**:需要稳定的网络连接(用于下载依赖包和访问模型服务)+还没有服务时,选择以下一种方式:-## 安装与启动+### 火山引擎托管服务-选择一种服务端安装方式:Python 包或 Docker。Python SDK 通过 HTTP 连接这两种方式启动的服务。+打开 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing),从**用户管理 → API Key** 获取密钥。服务地址为:-### 方式一:安装服务端和 CLI--选择你常用的 Python 包管理工具安装 OpenViking:--::: code-group--```bash [uv(推荐)]-uv tool install openviking --upgrade-```--```bash [pip]-python -m pip install openviking --upgrade+```text+https://api.vikingdb.cn-beijing.volces.com/openviking```-```bash [pipx]-# 安装-pipx install openviking--# 更新-pipx upgrade openviking-```--:::--安装完成后,可以使用客户端命令 `ov`(`openviking` 是其别名)和服务端命令 `openviking-server`。--### 方式二:通过 Docker 启动 (作为独立服务)--如果你希望将 OpenViking 作为独立的服务运行,推荐使用 Docker。--1. **准备配置目录**- 在宿主机上创建 OpenViking 目录,并准备好 `ov.conf` 配置文件(配置项参考下方“配置环境”章节)。所有持久化状态 —— 配置和工作区数据 —— 都放在这一个目录下:- ```bash- mkdir -p ~/.openviking- ```-- 启动容器前,参照下方手动配置模板,将完整 JSON 写入 `~/.openviking/ov.conf`。空文件不是有效配置。--2. **使用 Docker Compose 启动**- 创建 `docker-compose.yml` 文件:- ```yaml- services:- openviking:- # 推荐优先使用 ghcr.io;如果访问有问题,可改用 openviking-cn-beijing.cr.volces.com/volcengine/openviking:latest- image: ghcr.io/volcengine/openviking:latest- container_name: openviking- ports:- - "127.0.0.1:1933:1933"- volumes:- - ~/.openviking:/app/.openviking- restart: unless-stopped- ```- 然后在同目录下执行启动命令:- ```bash- docker compose up -d- ```-- 默认情况下,容器会启动 OpenViking API 服务(`1933`,同时在 `/studio` 提供 Web Studio 前端)以及内置的 `vikingbot` gateway。如果你需要关闭 `vikingbot`,可以在 Compose 里增加 `command: ["--without-bot"]`,或者设置 `environment: ["OPENVIKING_WITH_BOT=0"]`。-- 如果运行平台不支持 bind mount,可以通过 `OPENVIKING_CONF_CONTENT` 环境变量传入完整的配置 JSON,或在容器启动后 `docker exec` 进去执行 `openviking-server init`。详见 [部署指南](../guides/03-deployment.md#无法使用-docker-v-时)。--容器入口脚本在容器内监听 `0.0.0.0`。上述端口映射使宿主机(包括 macOS)可通过 `http://localhost:1933` 访问服务。如需允许其他机器访问,请参见 [身份认证](../guides/04-authentication.md) 和 [公网访问](../guides/12-public-access.md)。--## 模型准备--OpenViking 需要以下模型能力:-- **VLM 模型**:用于图像和内容理解-- **Embedding 模型**:用于向量化和语义检索+无需安装服务端,也无需在本机配置模型。[产品介绍](https://www.volcengine.com/product/openviking-service)和[服务文档](https://docs.volcengine.com/docs/84313/2374478)说明托管服务的使用方式与额度。继续第 2 步。-OpenViking 支持多种模型服务:-- **火山引擎(豆包模型)**:推荐使用,成本低、性能好,新用户有免费额度。如需购买和开通,请参考:[火山引擎购买指南](../guides/02-volcengine-purchase-guide.md)-- **OpenAI 模型**:通过 OpenAI API 使用支持视觉理解的模型和 Embedding 模型-- **OpenAI Codex**:支持通过 ChatGPT/Codex OAuth 使用 Codex 作为 VLM-- **其他自定义模型服务**:支持兼容 OpenAI API 格式的模型服务+### 自建服务-## 配置环境--### 配置文件模版--通过 Python 包安装时,使用配置向导:+在运行服务端的机器上[安装 uv](https://docs.astral.sh/uv/getting-started/installation/),再安装 OpenViking:```bash+uv tool install openviking --upgradeopenviking-server initopenviking-server doctor+openviking-server```-使用 Docker,或希望手动配置时,编写 `~/.openviking/ov.conf`:--```json-{- "embedding": {- "dense": {- "api_base" : "<api-endpoint>",- "api_key" : "<your-api-key>",- "provider" : "<provider-type>",- "dimension": 1024,- "model" : "<model-name>"- }- },- "vlm": {- "api_base" : "<api-endpoint>",- "api_key" : "<your-api-key>",- "provider" : "<provider-type>",- "model" : "<model-name>"- }-}-```--`provider`、`model`、`api_base` 和 `api_key` 取决于你选择的 VLM 服务;部分 provider 可能会使用本地 OAuth 状态,而不是手动填写 API key。+配置向导用于设置服务端模型并写入 `~/.openviking/ov.conf`。准备好 Embedding 模型和 VLM 的访问凭据——推荐使用火山引擎(豆包)模型,购买和开通见[火山引擎购买指南](../guides/02-volcengine-purchase-guide.md)——再用 `doctor` 检查配置。保持服务运行,另开终端完成后续步骤。-各模型服务的完整配置示例请参见 [配置指南 - 配置示例](../guides/01-configuration.md#配置示例)。+服务是否在运行,用一条 curl 即可确认,不依赖任何客户端:-首次配置建议优先使用 `openviking-server init`,它会帮助你选择 provider,并生成对应场景可直接使用的配置模板。+```bash+curl http://127.0.0.1:1933/health+# {"status":"ok","healthy":true,...}+```-### 设置环境变量+本地地址为 `http://127.0.0.1:1933`,默认本地配置不需要 API Key;Web Studio 位于 `/studio`。Docker、持久化存储和远程访问配置见[部署](../guides/03-deployment.md)、[模型配置](../guides/01-configuration.md)和[认证](../guides/04-authentication.md)。-配置文件放在默认路径 `~/.openviking/ov.conf` 时,无需额外设置,OpenViking 会自动加载。+## 2. 安装并连接 CLI-如果配置文件放在其他位置,需要通过环境变量指定:+在客户端机器上安装好 Node.js 和 npm 后,运行:```bash-export OPENVIKING_CONFIG_FILE=/path/to/your/ov.conf+npm install -g @openviking/cli+ov language zh-CN+ov config```-## 启动本地服务+在交互配置中,火山托管服务选择 **OpenViking Service**,自建服务选择 **自定义(Custom)**。填写 API Key,自建服务还需填写 URL。默认本地服务的密钥留空。保存并激活配置。-通过 Python 包安装并完成配置后,启动服务。如果 Docker 已运行,跳过此步骤:+CLI 将当前连接保存到 `~/.openviking/ovcli.conf`,它与服务端的 `ov.conf` 是两个文件。脚本化配置和多服务切换见 [CLI 配置](05-cli-setup.md)。-```bash-openviking-server-```+检查连接:-保持服务运行,然后打开另一个终端执行下面的 Python SDK 示例。-如果使用自定义配置路径,通过 `openviking-server --config /path/to/ov.conf` 启动。--默认本地模式不需要 API Key;连接启用鉴权的 Server 时,先设置-`OPENVIKING_API_KEY`。--## 运行第一个示例--### 创建 Python 脚本--创建 `example.py`:--```python-import time--from openviking_sdk import SyncHTTPClient--# 连接本地 OpenViking Server-client = SyncHTTPClient(url="http://localhost:1933")--try:- # 检查连接- client.initialize()-- # Add resource (supports URL, file, or directory)- # Local directory scans respect .gitignore by default.- add_result = client.add_resource(- path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",- )-- task_id = add_result["task_id"]- print(f"Import task: {task_id}")- while True:- task = client.get_task(task_id)- if task is None:- raise RuntimeError(f"Task {task_id} is no longer available")- if task["status"] == "completed":- break- if task["status"] in {"failed", "cancelled"}:- raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")- time.sleep(2)- root_uri = task["result"]["root_uri"]-- # Explore the resource tree structure- ls_result = client.ls(uri=root_uri)- print(f"Directory structure:\n{ls_result}\n")-- # Use glob to find markdown files- glob_result = client.glob(pattern="**/*.md", uri=root_uri)- if glob_result['matches']:- content = client.read(uri=glob_result["matches"][0])- print(f"Content preview: {content[:200]}...\n")-- # Get abstract and overview of the resource- abstract = client.abstract(uri=root_uri)- overview = client.overview(uri=root_uri)- print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n")-- # Perform semantic search- results = client.find(- query="what is openviking",- target_uri=root_uri,- )- print("Search results:")- for result in results.get("resources", []):- print(f" {result['uri']} (score: {result.get('score', 0.0):.4f})")--finally:- client.close()+```bash+ov health```-### 运行脚本+这一步确认服务能响应;下面的导入还会验证模型处理和数据访问。-SDK 需要安装在运行脚本的 Python 环境中。[`uv tool install`](https://docs.astral.sh/uv/guides/tools/#installing-tools) 和 `pipx install` 会隔离服务端依赖,不会把 SDK 安装到当前 Python 环境;Docker 也不会在宿主机安装客户端。+## 3. 导入文档-::: code-group+在当前目录创建 `quickstart.md`,内容如下:-```bash [uv]-uv run --with openviking-sdk python example.py-```+```markdown+# Atlas 项目-```bash [pip(在你的虚拟环境中)]-python -m pip install --upgrade openviking-sdk-python example.py+Atlas 项目每周五备份文档。+Maya 负责备份流程,每份备份保留 30 天。```-:::--### 预期输出+将它导入新的资源目录:+```bash+ov add-resource ./quickstart.md --to viking://resources/quickstart-demo --wait --timeout 120```-Import task: ...-Directory structure:-...+CLI 会自动上传本地文件。`--wait` 等待处理完成,命令成功后再继续。若省略该参数,保存返回的 `task_id`,用 `ov task status <task_id>` 查询到 `completed` 后再使用结果。详见[后台任务](../api/17-tasks.md)。-Content preview: ...+本例使用尚未使用的目标 URI。重复运行示例时,换一个新目标,并同步替换下方命令中的 URI。-Abstract:-...+## 4. 浏览与检索-Overview:-...--Search results:- viking://resources/... (score: 0.8523)- ...+```bash+ov tree viking://resources/quickstart-demo+ov overview viking://resources/quickstart-demo+ov find "谁负责备份流程?" --uri viking://resources/quickstart-demo```-恭喜!你已成功运行 OpenViking。+`tree` 列出导入后的结构,`overview` 读取生成的概览,`find` 返回相关上下文的 URI 和分数。读取某条命中时,把返回的 URI 传给 `ov read`:-## 服务端模式+```bash+ov read "<returned-file-uri>"+```-想要将 OpenViking 作为共享服务运行?请参见 [快速开始:服务端模式](03-quickstart-server.md)。+将 `<returned-file-uri>` 替换为结果中的文件 URI,不保留尖括号。更多资源类型和检索参数见[资源管理](../api/02-resources.md)与[检索](../api/06-retrieval.md)。-## 下一步+## 使用 SDK-- [配置详解](../guides/01-configuration.md) - 详细配置选项-- [API 概览](../api/01-overview.md) - API 参考-- [资源管理](../api/02-resources.md) - 资源管理 API+OpenViking 也提供 Python、TypeScript/JavaScript 和 Go SDK,均连接同一个服务端。客户端示例见 [API 概览](../api/01-overview.md)。diff --git a/docs/zh/getting-started/03-quickstart-server.md b/docs/zh/getting-started/03-quickstart-server.mdindex d12bff682..d7d617732 100644--- a/docs/zh/getting-started/03-quickstart-server.md+++ b/docs/zh/getting-started/03-quickstart-server.md@@ -1,218 +1,19 @@-# 快速开始:服务端模式+# 快速开始已合并-将 OpenViking 作为独立 HTTP 服务运行,并从任意客户端连接。+<a id="快速开始-服务端模式"></a>+OpenViking 以 HTTP 服务运行。服务搭建与客户端验证已合并到[快速开始](02-quickstart.md),以独立 CLI 为入口,覆盖托管、已有服务和自建服务。-## 前置要求+<a id="前置要求"></a>+<a id="启动服务"></a>+<a id="验证"></a>+<a id="使用-cli-连接"></a>+搭建服务、首次导入和检索请阅读[快速开始](02-quickstart.md)。命名连接和脚本化设置见 [CLI 配置](05-cli-setup.md)。-- 已安装 OpenViking(`uv tool install openviking --upgrade`)-- 模型配置已就绪(参见 [快速开始](02-quickstart.md) 了解配置方法)+<a id="使用-python-sdk-连接"></a>+<a id="启用认证"></a>+<a id="使用-curl-连接"></a>+Python、TypeScript/JavaScript、Go 和 HTTP 示例见 [API 概览](../api/01-overview.md)、[资源 API](../api/02-resources.md)和[身份认证](../guides/04-authentication.md)。-> Python 3.14 说明(适用于火山方舟 / Volcengine Ark):-> 如果你的 `ov.conf` 中使用了 `provider = "volcengine"` / Ark runtime,当前建议优先使用 Python 3.13 及以下版本运行 `openviking-server`。-> 这是因为 `volcengine-python-sdk[ark]` 仍会在 Python 3.14 下输出 Pydantic V1 兼容性警告,服务通常仍可运行,但启动命令和 `--version` 等输出会带有噪声,直到上游 SDK 去掉这层兼容逻辑。--## 启动服务--确保 `ov.conf` 已配置好存储路径和模型信息(参见 [快速开始](02-quickstart.md)),然后启动服务:--如果是首次配置,建议先运行 `openviking-server init`。--启动前建议先做本地校验:--```bash-openviking-server doctor-```--`openviking-server doctor` 会校验当前本地配置是否可用,包括各 provider 需要的鉴权状态。--```bash-# 配置文件在默认路径 ~/.openviking/ov.conf 时,直接启动-openviking-server--# 配置文件在其他位置时,通过 --config 指定-openviking-server --config /path/to/ov.conf--# 使用其他端口-openviking-server --port 8000-```--你应该看到:--```-INFO: Uvicorn running on http://127.0.0.1:1933-```--## 验证--```bash-curl http://localhost:1933/health-# {"status": "ok"}-```--`openviking-server doctor` 用于校验本地配置、模型访问和鉴权状态;`curl /health` 只表示服务进程已经启动。--Web Studio 也会在 `http://localhost:1933/studio` 提供(自 v0.3.21 起 pip/pipx 安装即自带,无需 Docker)。--## 使用 Python SDK 连接--在客户端的 Python 环境中安装独立 SDK:--```bash-python -m pip install --upgrade openviking-sdk-```--`uv tool` 或 pipx 安装的服务端使用独立环境。也可以将脚本保存后,通过 `uv run --with openviking-sdk python example.py` 运行。--```python-from openviking_sdk import SyncHTTPClient--client = SyncHTTPClient(url="http://localhost:1933")-```--### 启用认证--服务端启用认证后,需要传入 `api_key`。OpenViking 使用两层 API Key 体系,请根据场景选择:--**常规数据访问:使用 `user_key` 或 `admin_key`**--大多数场景应使用 `user_key`,也可以使用绑定到管理员用户的 `admin_key`。两者都可直接调用 `add_resource`、`find`、`ls` 等租户级 API:--```python-from openviking_sdk import SyncHTTPClient--client = SyncHTTPClient(- url="http://localhost:1933",- api_key="<user-key>",-)-```--> `user_key` / `admin_key` 通过 Admin API 创建(参见 [认证文档](../guides/04-authentication.md)),服务端可自动识别其所属租户和用户。--**管理操作:使用 `root_key`**--`root_key` 只适用于管理操作(创建账户、系统状态等)和少量 system/monitoring API。常规数据访问不要使用 `root_key`,也不要通过 `account` / `user` header 模拟某个用户;数据面应使用对应的 `user_key` 或 `admin_key`。--```python-from openviking_sdk import SyncHTTPClient--client = SyncHTTPClient(- url="http://localhost:1933",- api_key="<root-key>",-)-```--> 如果确实需要由上游网关注入 `account` / `user` 身份,应使用 `trusted` 模式;在默认 `api_key` 模式下,只有绑定了用户身份的 user/admin key 能访问自己的数据空间。--更多认证细节(trusted 模式、CLI 配置等)请参见 [认证文档](../guides/04-authentication.md)。--**完整示例:**--连接启用认证的服务时,先将 `OPENVIKING_API_KEY` 设置为 user/admin key。SDK 会自动读取这个环境变量。--```python-import time--from openviking_sdk import SyncHTTPClient--client = SyncHTTPClient(url="http://localhost:1933")--try:- client.initialize()-- # Add a resource- result = client.add_resource(- path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",- )-- task_id = result["task_id"]- print(f"Import task: {task_id}")- while True:- task = client.get_task(task_id)- if task is None:- raise RuntimeError(f"Task {task_id} is no longer available")- if task["status"] == "completed":- break- if task["status"] in {"failed", "cancelled"}:- raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")- time.sleep(2)- root_uri = task["result"]["root_uri"]-- # Search- results = client.find(- query="what is openviking",- target_uri=root_uri,- )- for result in results.get("resources", []):- print(f" {result['uri']} (score: {result.get('score', 0.0):.4f})")--finally:- client.close()-```--## 使用 CLI 连接--默认本地服务可省略 `api_key`。启用认证时,将下方的 `your-key` 替换为 user/admin key。--创建 CLI 连接配置文件 `~/.openviking/ovcli.conf`:--```json-{- "url": "http://localhost:1933",- "api_key": "your-key"-}-```--然后直接使用 CLI 命令:--```bash-# Check system health-openviking observer system--# Add a resource to memory-openviking add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md--# List all synchronized resources-openviking ls viking://resources--# Query-openviking find "what is openviking"-```--如果配置文件在其他位置,通过环境变量指定:--```bash-export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf-```--## 使用 curl 连接--下面的示例使用默认本地服务。启用认证时,为每个请求增加 `-H "X-API-Key: $OPENVIKING_API_KEY"`,使用 user/admin key。资源导入为异步操作:根据返回的 `task_id` 轮询 `GET /api/v1/tasks/{task_id}`,完成后再检索。--远端 URL 可以直接放在 `path` 里。本地文件需要先调用 `POST /api/v1/resources/temp_upload` 上传,再用返回的 `temp_file_id` 调目标 API。裸 HTTP 如果导入本地目录,需要先把目录打成 `.zip` 再上传。--```bash-# Add a resource-curl -X POST http://localhost:1933/api/v1/resources \- -H "Content-Type: application/json" \- -d '{"path": "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"}'--# List resources-curl "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/"--# Semantic search-curl -X POST http://localhost:1933/api/v1/search/find \- -H "Content-Type: application/json" \- -d '{"query": "what is openviking"}'-```--## 部署到云服务器--使用火山引擎 ECS 时,在 [官方 ECS 控制台](https://console.volcengine.com/ecs/) 创建实例。持久化存储、Docker 和服务管理请参见 [部署指南](../guides/03-deployment.md)。--本地服务默认监听 `127.0.0.1`。允许远程客户端访问前,需要配置 [身份认证](../guides/04-authentication.md)、可访问的监听地址和必要的网络访问规则。TLS 与反向代理配置请参见 [公网访问](../guides/12-public-access.md)。数据访问使用绑定租户和用户身份的 user/admin key。--## 下一步--- [服务部署](../guides/03-deployment.md) - 配置、认证和部署选项-- [API 概览](../api/01-overview.md) - 完整 API 参考-- [认证](../guides/04-authentication.md) - 使用 API Key 保护你的服务+<a id="部署到云服务器"></a>+<a id="下一步"></a>+Docker、存储、服务管理和托管方案见[部署指南](../guides/03-deployment.md)。将自建服务开放到网络前,请配置[公网访问](../guides/12-public-access.md)。diff --git a/docs/zh/getting-started/05-cli-setup.md b/docs/zh/getting-started/05-cli-setup.mdindex ffe7acf53..141e2fc54 100644--- a/docs/zh/getting-started/05-cli-setup.md+++ b/docs/zh/getting-started/05-cli-setup.md@@ -2,7 +2,7 @@本文介绍如何安装 OpenViking CLI、完成配置,并验证它可以连接到 OpenViking。-`ov` 是客户端 CLI。它连接到已经存在的 OpenViking 服务端,或连接到 OpenViking Service(火山引擎云)。它不是服务端安装命令。如果你还没有安装或启动自定义 OpenViking 服务端,请先阅读[快速开始](02-quickstart.md)或[服务端模式](03-quickstart-server.md)。+`ov` 是客户端 CLI。它连接到已经存在的 OpenViking 服务端,或连接到 OpenViking Service(火山引擎云)。它不是服务端安装命令。如果你还没有安装或启动自定义 OpenViking 服务端,请先阅读[快速开始](02-quickstart.md)。你可以用两种方式阅读本文:@@ -284,7 +284,7 @@ ov config add ov-service --name <CONFIG-NAME> --api-key-env <API-KEY-ENV-VAR> --ov config add custom --name <CONFIG-NAME> --url http://127.0.0.1:1933 --activate -o json```-如果本地服务没有运行,请先引导用户启动服务端。参见[服务端模式](03-quickstart-server.md)。+如果本地服务没有运行,请先引导用户启动服务端。参见[部署指南](../guides/03-deployment.md)。### 添加远程自定义服务@@ -431,7 +431,7 @@ npm prefix -gcurl http://127.0.0.1:1933/health```-如果失败,先启动服务端再配置 `ov`。参见[服务端模式](03-quickstart-server.md)。+如果失败,先启动服务端再配置 `ov`。参见[部署指南](../guides/03-deployment.md)。### API Key 校验失败diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.mdindex 5556048ac..7a48c2256 100644--- a/docs/zh/guides/03-deployment.md+++ b/docs/zh/guides/03-deployment.md@@ -1,11 +1,23 @@# 服务端部署-OpenViking 可以作为独立的 HTTP 服务器运行,允许多个客户端通过网络连接。+OpenViking 以 HTTP 服务运行。安装服务端之前,先选择由谁运行服务:++| 服务方式 | 你需要准备什么 |+| --- | --- |+| [火山引擎托管 OpenViking](https://www.volcengine.com/product/openviking-service) | 在[控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing)获取 API Key,用独立 CLI 连接,无需本地服务端或模型配置。 |+| 团队已有服务或他人部署 | 向管理员获取服务地址和 user/admin key。 |+| 自建 OpenViking | 按下文安装、配置和运行服务端。 |++托管及已有服务用户可直接从 [CLI 快速开始](../getting-started/02-quickstart.md)进入。托管服务的可用范围、套餐和额度见[官方服务文档](https://docs.volcengine.com/docs/84313/2374478)。++本页后续内容适用于自建服务。容量规划应使用有代表性的数据集和预期并发量测量内存、磁盘占用,为原始文件、索引和快照预留空间。扩大工作负载前,通过[可观测性](../guides/05-observability.md)检查容量余量。## 快速开始+先按[自建服务快速开始](../getting-started/02-quickstart.md)安装服务端。Python 3.14 下使用火山引擎 Ark 时,上游 Python SDK 可能输出 Pydantic V1 兼容性警告;此场景可使用 Python 3.13 避免该警告。+```bash# 使用初始化向导创建或刷新 ~/.openviking/ov.confopenviking-server init@@ -21,9 +33,8 @@ openviking-server# 配置文件在其他位置时,通过 --config 指定openviking-server --config /path/to/ov.conf-# 验证服务器是否运行-curl http://localhost:1933/health-# {"status": "ok"}+# 在另一终端按快速开始配置 ov,连接本服务后验证+ov health```## 命令行选项diff --git a/docs/zh/guides/11-grafana-prometheus.md b/docs/zh/guides/11-grafana-prometheus.mdindex 241e4f3da..72b8920a7 100644--- a/docs/zh/guides/11-grafana-prometheus.md+++ b/docs/zh/guides/11-grafana-prometheus.md@@ -463,4 +463,4 @@ Bind for 0.0.0.0:9090 failed: port is already allocated- [指标与 Metrics](../concepts/12-metrics.md)- [Metrics API](../api/09-metrics.md)- [服务端部署](03-deployment.md)-- [快速开始:服务端模式](../getting-started/03-quickstart-server.md)+- [快速开始](../getting-started/02-quickstart.md)