Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: 合并快速开始为单一 CLI 优先的 server 服务路径 (#5195)

Zayn Jarvisb05cc863104e
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 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.md
index 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.md
index 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 --upgrade
openviking-server init
openviking-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.md
index 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.md
index 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 Fails
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index 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 wizard
openviking-server init
@@ -21,9 +33,8 @@ openviking-server
# Or specify a custom config path
openviking-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 Options
diff --git a/docs/en/guides/11-grafana-prometheus.md b/docs/en/guides/11-grafana-prometheus.md
index 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.md
index 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.md
index 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 --upgrade
openviking-server init
openviking-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.md
index 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.md
index 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 -g
curl 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.md
index 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.conf
openviking-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.md
index 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)