Windows 下 OpenViking 安装与启动完整指南

适用系统：Windows 10/11（PowerShell）

目标：在隔离的虚拟环境中干净安装 OpenViking，并成功启动其记忆服务。

1. 环境准备

注意：如果通过 pip install openviking 安装，不需要 Go 和 C++ 编译器，只需 Python ≥ 3.10。

2. 创建专用虚拟环境

由于 Windows 全局环境可能存在权限限制、路径过长或旧包元数据损坏等问题，我们直接在 C 盘根目录 创建短路径虚拟环境。

python -m venv C:\v

如果提示 python: command not found，请确认 Python 已添加到 PATH，或使用 python3 替换。

3. 激活虚拟环境

3.1 一键激活（推荐直接复制运行）

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& C:\v\Scripts\Activate.ps1

3.2 验证成功

命令行开头会出现 (v) 标识：

(v) PS C:\Users\Administrator>

常见问题：
- 如果提示"禁止运行脚本"，先执行第一条 Set-ExecutionPolicy 命令即可。
- 不要用 C:\v\Scripts\activate（那是 CMD 脚本，在 PowerShell 中不会生效）。

4. 升级 pip 并安装 OpenViking

python -m pip install --upgrade pip
pip install openviking

安装过程中不会再遇到 volcengine-python-sdk 的 uninstall-no-record-file 错误，因为虚拟环境是全新无污染的状态。

若长时间卡住，可以临时使用国内镜像：

pip install openviking -i https://pypi.tuna.tsinghua.edu.cn/simple

5. 常见错误处理

6. 创建配置文件

OpenViking 服务器启动必须依赖配置文件 ~/.openviking/ov.conf。在 PowerShell 中执行以下命令，快速生成模板：

mkdir -p $env:USERPROFILE\.openviking

然后用记事本创建配置文件：

notepad $env:USERPROFILE\.openviking\ov.conf

粘贴以下内容，并将 <你的API_KEY> 替换为真实密钥：

{
    "embedding":{
        "dense":{
            "backend":"openai",
            "api_key":"<你的API_KEY>",
            "model":"text-embedding-3-small",
            "api_base":"https://api.openai.com/v1",
            "dimension":1024
        }
    },"vlm":{
        "backend":"openai",
        "api_key":"<你的API_KEY>",
        "model":"gpt-4o",
        "api_base":"https://api.openai.com/v1"
    },
    "storage":{
        "agfs":{
            "timeout":60
        }
    }
}

也可以使用兼容 OpenAI API 的其他服务（如 DeepSeek），修改 api_base 和 model 即可。

7. 启动 OpenViking 服务

openviking-server --config $env:USERPROFILE\.openviking\ov.conf

首次启动会自动初始化数据库和所需的模型连接，待出现 Server started 类的日志，即表示运行成功。

8. 便捷脚本（可选）

将以下内容保存为 start_openviking.ps1，以后双击运行即可激活环境并启动服务：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& C:\v\Scripts\Activate.ps1
openviking-server --config $env:USERPROFILE\.openviking\ov.conf

9. 退出与清理

• 退出服务：在运行窗口按 Ctrl + C。
• 退出虚拟环境：输入 deactivate。
• 若想完全删除虚拟环境，直接删除 C:\v 文件夹。

通过虚拟环境隔离安装，彻底避开了 Windows 下常见的权限、路径和元数据损坏问题。通过 C 盘根目录创建短路径虚拟环境是整个安装流程的关键。