如何用 Docker 运行 OceanBase CE 并将其作为 CAMEL 向量存储接入智能体？-育师

如何用 Docker 运行 OceanBase CE 并将其作为 CAMEL 向量存储接入智能体？

【免费下载链接】camel🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel

这篇文章完成一个连续任务：在本地用 Docker 跑起 OceanBase Community Edition（CE，4.3.5+），然后使用 CAMEL 的OceanBaseStorage把它作为持久化向量存储接入，验证向量写入与相似度查询是否可用。OceanBase 是 MySQL 兼容的分布式数据库，可通过 OceanBase Vector 提供向量能力；CAMEL 的OceanBaseStorage基于pyobvector实现，支持存储 embedding + 元数据并执行 ANN 相似度搜索。

准备条件

本机已安装 Docker（文档中的镜像拉取与运行命令均以 Docker 为前提）。
Python 环境需满足pyobvector的安装要求：根据 pyproject.toml，pyobvector>=0.2.22仅在python_version < '3.13'时安装，即该依赖目前仅支持 Python 3.13 以下版本。
安装 CAMEL 的 RAG 依赖（会一并引入pyobvector）。如果本地已有源码检出安装，可跳过此步。文档给出的安装命令为：

!pip install "camel-ai[rag]==0.2.85"

关于 extras 的说明可参考安装文档：ragextras 包含 Sentence Transformers、Qdrant、Milvus、TiDB、BM25、OceanBase、Weaviate、chroma 等依赖。

用 Docker 运行 OceanBase CE

OceanBase 提供官方镜像oceanbase/oceanbase-ce，两个关键端口：

2881：MySQL 兼容端点；
2886：OceanBase dashboard / obshell。

推荐设置环境变量OB_TENANT_PASSWORD。本地开发时MODE=SLIM会以轻量单节点模式快速启动。

方式 A：快速启动

docker pull oceanbase/oceanbase-ce docker run -d --name oceanbase-ce \ -p 2881:2881 \ -p 2886:2886 \ -e MODE=SLIM \ -e OB_TENANT_PASSWORD=TenantPassw0rd! \ oceanbase/oceanbase-ce # Watch logs until the service prints "boot success!" docker logs -f oceanbase-ce

方式 B：带持久化卷（适合反复迭代开发，可选）

该方式会把数据目录挂载到宿主机，容器删除后数据仍保留。副作用是会在当前目录创建ob与ob-cluster两个目录，后续数据落在其中：

mkdir -p ob ob-cluster docker run -d --name oceanbase-ce \ -p 2881:2881 \ -p 2886:2886 \ -e MODE=SLIM \ -e OB_TENANT_PASSWORD=TenantPassw0rd! \ -v "$PWD/ob:/root/ob" \ -v "$PWD/ob-cluster:/root/.obd/cluster" \ oceanbase/oceanbase-ce

启动成功的判定条件

在日志中等待boot success!出现，之后再进行 CAMEL 侧的存储操作。如果本机装有 MySQL 客户端，文档给了一个可选的连通性检查（用户名可用租户限定形式，例如root@test）：

mysql -h 127.0.0.1 -P 2881 -u root@test -p

注意：文档提醒，具体的默认租户/用户可能随镜像版本和你的配置而变化。

在 CAMEL 中创建并连接 OceanBaseStorage

OceanBaseStorage把向量和元数据存在一张 OceanBase 表中；如果表不存在，会先建表并创建 HNSW 向量索引。关键参数（见 camel/storages/vectordb_storages/oceanbase.py）：

vector_dim：embedding 维度；
table_name：OceanBase 中的表名；
uri：host:port（本地 Docker 场景为127.0.0.1:2881）；
user：通常为租户限定的用户（如root@test）；
password：用户密码；
db_name：数据库名；
distance：距离度量，实现支持"l2"、"cosine"、"inner_product"、"negative_inner_product"，默认"l2"。

下面这段代码来自 cookbook，连接参数通过环境变量提供，括号内为文档给出的默认值，不设置环境变量即可按默认值直接运行：

import os import random from camel.storages import OceanBaseStorage, VectorDBQuery, VectorRecord # Connection settings for local Docker OB_URI = os.environ.get("OB_URI", "127.0.0.1:2881") OB_USER = os.environ.get("OB_USER", "root@test") OB_PASSWORD = os.environ.get("OB_PASSWORD", "TenantPassw0rd!") OB_DB_NAME = os.environ.get("OB_DB_NAME", "test") TABLE_NAME = os.environ.get("OB_TABLE_NAME", "camel_oceanbase_vectors") VECTOR_DIM = int(os.environ.get("VECTOR_DIM", "4")) storage = OceanBaseStorage( vector_dim=VECTOR_DIM, table_name=TABLE_NAME, uri=OB_URI, user=OB_USER, password=OB_PASSWORD, db_name=OB_DB_NAME, distance="cosine", ) print(storage.status())

status()返回VectorDBStatus，包含vector_dim与vector_count（表内记录数），是贯穿下文验证步骤的检查手段。

写入、查询与清理，并核对结果

下面这组操作用随机向量做连通性验证，不依赖任何 embedding 模型。向量维度要与建表时的VECTOR_DIM一致，否则add会抛出ValueError。

写入 200 条记录并核对数量（batch_size=100为每批插入条数）：

random.seed(20260131) records = [] for i in range(200): records.append( VectorRecord( vector=[random.uniform(-1, 1) for _ in range(VECTOR_DIM)], payload={"doc_id": f"doc-{i}", "source": "sanity-check"}, ) ) storage.add(records=records, batch_size=100) print(storage.status())

此时status()输出的vector_count应为 200。

用随机向量做相似度查询，取top_k=5：

query_vector = [random.uniform(-1, 1) for _ in range(VECTOR_DIM)] results = storage.query(VectorDBQuery(query_vector=query_vector, top_k=5)) for r in results: print({"id": r.record.id, "similarity": r.similarity, "payload": r.record.payload})

返回的每条结果包含id、similarity（由距离转换得到的相似度分数）和payload（写入时的元数据，如doc_id）。如果这里能打印出 5 条带有doc-*元数据的结果，说明写入与 ANN 查询链路已经打通。

清理（破坏性操作，会清空整张表的所有记录，请确认表内没有需要保留的数据）：

# Clean up the table contents (destructive) storage.clear() print(storage.status())

执行后status()的vector_count应回到 0。

已知限制与边界

HNSW 索引参数是固定的：当前 CAMEL 实现在首次建表时以m=16、ef_construction=256创建 HNSW 索引。文档明确说明，如果需要不同的 HNSW 参数，必须修改或扩展 OceanBaseStorage 实现，当前 API 不暴露这些参数。
用户与租户：cookbook 默认使用root@test，而 storages 模块文档中的示例使用root@sys。两者都是文档给出的连接示例，默认租户/用户随镜像版本和配置变化，连不上时先核对实际租户名。
距离度量：cookbook 示例使用distance="cosine"；实现层面还支持l2（默认）、inner_product、negative_inner_product，查询时会自动映射到 OceanBase 对应的距离函数。
索引调优方面，文档按数据规模给出了方向性建议：小集合（<= 100k 向量）保持中等建索引设置、必要时加大查询期搜索宽度；中等集合（约 100k–5M）先测 P95/P99 延迟与 recall，达不到目标再提高建索引设置并重建；大集合（5M+）需规划内存与重建时间，可考虑按租户/语料/时间分片。完整内容见 cookbook。