记忆服务部署（单机）

快速部署

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

当前单机部署脚本支持 OpenViking 和 oGMemory 两种记忆系统后端，通过 deploy.env 中的 MEMORY_BACKEND 选择其一：

MEMORY_BACKEND=openviking|ogmemory

获取部署脚本。
```
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、build_ogmemory.sh、ogmemory.yaml 和 OpenViking openGauss backend patch到“openviking-deploy/”目录。
编辑deploy.env，填写必填项。
部署 OpenViking 时，保持如下配置或不显式配置 MEMORY_BACKEND：
- MEMORY_BACKEND="openviking"
填写以下必填项：
- 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的记忆提取、自动摘要等功能将无法使用。
部署 oGMemory 时，设置：
- MEMORY_BACKEND="ogmemory"
填写以下必填项：
- CONTEXTENGINE_PROVIDER：oGMemory 使用的 LLM 服务提供商，如 volcengine。
- OGMEM_API_KEY：oGMemory 调用 LLM 的 API Key。
- OGMEM_BASE_URL：oGMemory 调用 LLM 的 API Base URL。
- OGMEM_LLM_MODEL：oGMemory 使用的 LLM 模型名。
- EMBEDDING_PROVIDER：oGMemory 使用的 Embedding 服务提供商。
- OGMEM_EMBEDDING_MODEL：Embedding 模型名。
- OGMEM_EMBEDDING_BASE_URL：Embedding API Base URL。
- OGMEM_EMBEDDING_API_KEY：Embedding API Key。
  
  oGMemory 依赖外部 LLM 和 Embedding API 完成记忆提取与向量化。LLM 和 Embedding 可以使用不同厂商，按需分别配置即可。deploy.sh 会将 ogmemory.yaml 挂载到容器内 /etc/ogmem/config.yaml，并把 deploy.env 中的变量传入容器，由 oGMemory 启动脚本完成配置替换。
执行部署。
```
bash deploy.sh -password '<openGauss密码>'
```
OPENGAUSS密码要求：
- 密码长度必须至少为8个字符。
- 必须同时包含大写字母、小写字母、数字、以及特殊字符（#?!@&）。
（可选）查看部署状态。
```
bash deploy.sh --status
```

手动部署（可选）

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

当前单机手动部署支持两种路线： OpenViking + openGauss oGMemory + openGauss OpenViking 和 oGMemory 二选一部署即可，不需要同时启动两个记忆服务。

方式一：手动部署 OpenViking + openGauss

下载openGauss数据库的Docker镜像。

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

启动单机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容器应处于正常运行状态。

配置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
```
下载并启动支持openGauss数据库的OpenViking镜像。
```
docker pull swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/openviking-opengaussbackend:0617
```
启动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:0617
```
- /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模型名称。

修改ov.conf文件。

进入容器。
```
docker exec -it OpenViking bash
```
修改ov.conf配置文件。
```
vi /root/.openviking/ov.conf
```

按“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"
    }
  }

按“Esc”键退出编辑模式，输入:wq!，按“Enter”键保存并退出文件。
重启OpenViking容器使配置生效。
```
 docker restart OpenViking
```
进入openGauss数据库查看。
```
docker exec -it opengauss bash
su omm
gsql -r
\d    
```
应看到OpenViking初始化的三张表，如下图所示。

验证OpenViking服务。
```
curl http://<your_server_ip>:1933/health
```
预期返回：{"status":"ok"}，示例如下。

方式二：手动部署 oGMemory + openGauss

openGauss容器启动与方式一中步骤1到步骤3相同，接下来直接手动启动oGMemory容器。

下载并启动 oGMemory 镜像。

docker pull swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/ogmemory:poc_57

启动 oGMemory 容器：

 docker run -d --name ogmem \ 
 --network host \ 
 -v "$(pwd)/ogmemory.yaml:/etc/ogmem/config.yaml:ro" \ 
 -e CONTEXTENGINE_PROVIDER=volcengine \ 
 -e OGMEM_API_KEY=<your_llm_api_key> \ 
 -e OGMEM_BASE_URL=<your_llm_base_url> \ 
 -e OGMEM_LLM_MODEL=<your_llm_model> \ 
 -e EMBEDDING_PROVIDER=volcengine \ 
 -e OGMEM_EMBEDDING_MODEL=<your_embedding_model> \ 
 -e OGMEM_EMBEDDING_BASE_URL=<your_embedding_base_url> \ 
 -e OGMEM_EMBEDDING_API_KEY=<your_embedding_api_key> \ 
 -e OPENGAUSS_HOST=127.0.0.1 \ 
 -e OPENGAUSS_PORT=36432 \ 
 -e OPENGAUSS_DBNAME=omm \ 
 -e OPENGAUSS_USER=gaussdb \ 
 -e OPENGAUSS_PASSWORD=<openGauss密码> \ 
 -e OGMEM_HTTP_PORT=8090 \  swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/ogmemory:poc_57

ONTEXTENGINE_PROVIDER、OGMEM_API_KEY、OGMEM_BASE_URL、OGMEM_LLM_MODEL：oGMemory 调用 LLM 的配置。
EMBEDDING_PROVIDER、OGMEM_EMBEDDING_MODEL、OGMEM_EMBEDDING_BASE_URL、OGMEM_EMBEDDING_API_KEY：oGMemory 调用 Embedding 服务的配置。
OPENGAUSS_HOST=127.0.0.1：oGMemory 使用 Host 网络访问宿主机映射出的 openGauss 端口。
OPENGAUSS_PORT=36432：对应 openGauss 宿主机映射端口。
OGMEM_HTTP_PORT=8090：oGMemory HTTP 服务端口。

验证 oGMemory 服务。

curl http://<your_server_ip>:8090/api/v1/health

OpenClaw对接记忆配置

在 OpenClaw 中配置 OpenViking 或 oGMemory 服务作为长期记忆后端。

OpenViking 记忆对接配置:

创建新工作区及其首个管理员用户。

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":"NTY0Nw.aHVhd2Vp.ZjVkNz..."},"error":null,"telemetry":null}

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

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":"MTIzNA.b3Yy.ZWRk..."},"error":null,"time":0.0,"usage":null}

生成的API Key值可以作为参数值传递到启动OpenClaw镜像的OPENVIKING_API_KEY环境变量中。

openclaw.json记忆插件参考配置：

"plugins": {
    "enabled": true,
    "load": {
      "paths": [
        "/root/.openclaw/extensions/openviking"
      ]
    },
    "allow": [
      "openviking"
    ],
    "slots": {
      "contextEngine": "openviking"
    },
    "entries": {
      "openviking": {
        "enabled": true,
        "config": {
          "mode": "remote",
          "baseUrl": "http://172.17.0.1:1933",
          "targetUri": "viking://user/memories",
          "autoRecall": true,
          "autoCapture": true,
          "recallMaxContentChars": 50000,
          "apiKey": "MTIzNA.b3Y.MGMxNDRhMjNjNWI0ZWFhYjE1ZDMxODNiY2VjZjNjYzE0ODM2OWYwODhhZWJhYmJlYmM0NWFmMjg4OTRlODI2OQ",
          "agent_prefix": "main"
        }
      },
      "openai": {
        "enabled": true
      }
    },
    "bundledDiscovery": "compat"
  },

oGMemory 记忆对接配置 :

使用 oGMemory，需要使能OpenClaw插件中的og-memory-context-engine。

openclaw.json的插件配置如下：

"plugins": {
    "enabled": true,
    "load": {
      "paths": [
        "/root/.openclaw/extensions/og-memory-context-engine"
      ]
    },
    "allow": [
      "og-memory-context-engine",
      "openai"
    ],
    "slots": {
      "contextEngine": "og-memory-context-engine"
    },
    "entries": {
      "og-memory-context-engine": {
        "enabled": true,
        "config": {
          "mode": "remote",
          "memoryApiBaseUrl": "http://172.17.0.1:8090",
          "authApiKey": "",
          "authAccountId": ""
        }
      },
      "memory-core": {
        "enabled": false
      },
      "openai": {
        "enabled": true
      }
    },
    "bundledDiscovery": "compat"
  },

父主题： 组件自定义部署（可选）