记忆服务部署（单机）

快速部署

具体部署使用说明与参数介绍，可参见OpenViking + openGauss Docker 部署使用说明。

1. 获取部署脚本。

   curl -fsSL https://gitee.com/kunpeng_compute/KunpengRAG/raw/master/OpenViking_OpenGauss/install.sh | bash 
   cd openviking-deploy

   install.sh会自动下载deploy.sh、deploy.env、build.sh到“openviking-deploy/”目录。

2. 编辑deploy.env，填写必填项。
   • OPENVIKING_ROOT_API_KEY：OpenViking管理密钥。
   • OPENVIKING_VLM_API_KEY：VLM大模型API Key（记忆提取、自动摘要依赖此模型）。
   • OPENVIKING_VLM_PROVIDER/OPENVIKING_VLM_API_BASE/OPENVIKING_VLM_MODEL：VLM服务配置。
     

     VLM模型是记忆提取功能的核心依赖。如果不配置VLM，OpenViking的记忆提取、自动摘要等功能将无法使用。

3. 执行部署。

   bash deploy.sh -password '<openGauss密码>'

   

   OPENGAUSS密码要求：

   • 密码长度必须至少为8个字符。
   • 必须同时包含大写字母、小写字母、数字、以及特殊字符（#?!@&）。
4. （可选）查看部署状态。

   bash deploy.sh --status

手动部署（可选）

记忆服务相关进程（openGauss、OpenViking）整体CPU资源建议限定为16个vCPU，可按需进行绑核约束。

1. 下载openGauss数据库的Docker镜像。

   docker pull swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/opengauss-distributed:0422

2. 启动单机openGauss容器。

     docker run --name opengauss --privileged=true -d \
     --net=host \
     -e GS_USERNAME={OG_USER} \
     -e GS_PASSWORD={OG_PASSWORD} \
     -e GS_NODENAME={OG_NODE_NAME
   }    \
     -e GS_PORT={OG_PORT}    \
     swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/opengauss-distributed:0422

   

   GS_PASSWORD需包含大写字母、小写字母、数字及特殊符号中的四种，特殊符号仅支持“#?!@&”，需要用转义符""进行转义。

   推荐使用以下简易启动命令，默认{OG_USER}为omm、{OG_NODE_NAME}为omm、{OG_PORT}为5432。

     docker run --name opengauss --privileged=true -d \
     --cpuset-cpus="32-39" \
     --net=host \
     -e GS_PASSWORD={OG_PASSWORD} \
     swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/opengauss-distributed:0422

   按照默认配置部署成功后，下列openGauss容器应处于正常运行状态。

   

3. 配置openGauss。
   1. 进入容器。

      docker exec -it opengauss bash

   2. 切换到管理用户。

      su omm

   3. 进入SQL命令行。

      gsql -r

   4. 创建新用户test，并赋予权限。user_password包含大写字母、小写字母、数字及特殊符号中这四种。

      create user test with password '<user_password>';
      grant all privileges to test;

   5. 退出数据库和容器。

      \q
      exit

4. 下载并启动支持openGauss数据库的OpenViking镜像。

   docker pull swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/openviking-opengaussbackend:0422

   启动OpenViking容器。

     docker run -d --name OpenViking \
     -p 1933:1933 \
     -e OPENVIKING_VLM_PROVIDER=openai \
     -e OPENVIKING_VLM_API_BASE=<your_vlm_api_base> \
     -e OPENVIKING_VLM_API_KEY="<your_api_key>" \
     -e OPENVIKING_VLM_MODEL=<your_vlm_model> \
     -e OPENVIKING_TARGET_URI=viking://user/memories \
     -e OPENVIKING_ROOT_API_KEY=<your_root_key> \
     -v /your_path/openclaw-data:/root/.openclaw \
     -v /your_path/openviking-data:/root/.openviking \
     swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/openviking-opengaussbackend:0422

   

   • /your_path/openclaw-data：挂载宿主机目录，用于持久化OpenClaw的配置和数据。
   • /your_path/openviking-data：挂载宿主机目录，用于持久化OpenViking的配置和数据。
   • your_root_key：设置用于控制OpenViking多租户模式下用户的访问。
   • -e OPENVIKING_EMBEDDING_API_KEY：（可选）Embedding模型的访问令牌（API key）。
   • -e OPENVIKING_EMBEDDING_PROVIDER：（可选）OPENVIKING_EMBEDDING_API_KEY配置下有效，Embedding服务提供商名称。
   • -e OPENVIKING_EMBEDDING_API_BASE：（可选）OPENVIKING_EMBEDDING_API_KEY配置下有效，Embedding API的Base URL。
   • -e OPENVIKING_EMBEDDING_MODEL：（可选）OPENVIKING_EMBEDDING_API_KEY配置下有效，Embedding模型名称。
5. 修改ov.conf文件。
   1. 进入容器。

      docker exec -it OpenViking bash

   2. 修改ov.conf配置文件。

      vi /root/.openviking/ov.conf

   3. 按“i”进入编辑模式，配置OpenViking的向量数据库后端引擎为openGauss，按需修改Embedding模型，没有设置embedding将使用内置的bge-small-zh-v1.5-f16模型。

      {
          "server": {
            "host": "0.0.0.0",
            "port": 1933,
            "root_api_key": null,
            "cors_origins": ["*"]
          },
          "storage": {
            "workspace": "/home/your_user/openviking_workspace",
            "vectordb": {
              "backend": "opengauss",        # 使用openGauss
              "dimension": 512,             # 需根据模型而定，建议小于等于1536
              "opengauss": {
                "host": "{HOST_IP}",         # 对应配置
                "port": "{OG_PORT}",       # 对应配置
                "user": "{OG_USER}",         # 对应创建的用户
                "password": "{OG_PASSWORD}", # 对应配置
                "db_name": "{OG_NODE_NAME}", # 对应配置
                "mode": "standalone"         # 单机
              }
            },
            "agfs": {
              "port": 1833,
              "log_level": "warn",
              "backend": "local"
            }
          },
          "vlm": {
            "provider": "openai",
            "api_key": "your_api_key",
            "model": "your_model",
            "api_base": "your_model_api_base",
            "temperature": 0.1,
            "max_retries": 3
          },
          "log": {
            "level": "INFO",
            "output": "stdout"
          }
        }

   4. 按“Esc”键退出编辑模式，输入:wq!，按“Enter”键保存并退出文件。
   5. 重启OpenViking容器使配置生效。

       docker restart OpenViking

   6. 进入openGauss数据库查看。

      docker exec -it opengauss bash
      su omm
      gsql -r
      \d    

      应看到OpenViking初始化的三张表。

      

6. 验证OpenViking服务。

   curl http://<your_server_ip>:1933/health

   预期返回：{"status":"ok"}，示例如下。

   

7. 如需实现多Agent共享记忆，需启用OpenViking的多租户模式，并让多个Agent共用一个工作区下的User Key。
   1. 创建新工作区及其首个管理员用户。

      curl -X POST http://localhost:1933/api/v1/admin/accounts\
         -H "Content-Type: application/json"\
         -H "X-API-Key: <root_key>"\
         -d '{
          "account_id": "<your_account_id>",
          "admin_user_id": "<your_user_id>"
        }'

      响应示例如下：

      {"status":"ok","result":{"account_id":"your_account_id","admin_user_id":"your_user_id","user_key":"c11e7372fe26ed05541ad7f..."},"error":null,"telemetry":null}

      

   2. 在工作区中注册新用户，产生的user_key就是填到openclaw.json中OpenViking配置中的apikey。

      curl -X POST http://localhost:1933/api/v1/admin/accounts/<your_account_id>/users\
         -H "Content-Type: application/json"\
         -H "X-API-Key: <root_key>"\
         -d '{
          "user_id": "<your_user_id>",
          "role": "user"
        }'

      响应示例如下：

      {"status":"ok","result":{"account_id":"your_account_id","user_id":"your_user_id","user_key":"590765af3963be..."},"error":null,"time":0.0,"usage":null}

      

      

      • 生成的user_key值可以作为参数值传递到启动openclaw镜像的OPENVIKING_API_KEY环境变量中。
      • account_id值可以作为参数值传递到启动openclaw镜像的OPENVIKING_ACCOUNT_ID环境变量中。
      • user_id值可以作为参数值传递到启动openclaw镜像的OPENVIKING_USER_ID环境变量中。
      • openclaw.json记忆插件参考配置：

        "entries": {
              "openviking": {
                "config": {
                  "mode": "remote",
                  "baseUrl": "http://127.0.0.1:1933",
                  "agentId": "main",
                  "targetUri": "viking://user/memories",
                  "autoRecall": true,
                  "apiKey": "590765af3963bea034b3c573e88c4d615527b83e607ebdff8b7adabe4af5ca85",
                  "autoCapture": true,
                  "recallMaxContentChars": 10000,
                  "recallTokenBudget": 8000,
                  "accountId": "admin",
                  "userId": "jack"
                }
              }
        }