Coze Studio 集成 OceanBase 向量数据库完全指南:架构、配置与 Kubernetes 部署实战
【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio
本文基于 Coze Studio 开源仓库中的 OceanBase 集成文档,结合后端源码、Docker 编排文件与 Helm Chart,系统讲解 OceanBase 作为向量存储的适配原理、环境变量配置、Docker/Helm 部署流程与故障排查方法。读完本文,你将掌握如何在 Coze Studio 知识库场景中,用一套兼容 MySQL 协议的数据库完成向量入库与近似检索,并能够在单机 Docker 与 Kubernetes 两种环境下快速落地。
一、集成背景:为什么在 Coze Studio 中选择 OceanBase
Coze Studio 是一个面向 AI Agent 开发的一体化平台,其知识库功能依赖向量存储完成文档召回。除 Milvus、vikingdb 等专用向量数据库外,仓库在 docker/.env.example 中明确支持将VECTOR_STORE_TYPE配置为oceanbase,作为第三类向量存储后端。
选择 OceanBase 的理由集中在以下几点:
- 完整事务支持:OceanBase 提供完整的 ACID 事务能力,向量数据与业务元数据可共享同一事务边界,保证数据一致性;
- 部署简单:相比 Milvus 依赖 etcd、MinIO 等周边组件,OceanBase 支持单机部署,一条 Docker Compose 服务即可拉起;
- MySQL 兼容:兼容 MySQL 协议,连接串、SQL 语法与生态工具(如
mysql客户端、GORM ORM)开箱即用,学习成本低; - 原生向量扩展:支持
VECTOR数据类型与 HNSW/IVF 向量索引,可执行COSINE_DISTANCE等距离函数; - 运维友好:无需维护独立集群,适合中小规模应用的知识库检索场景。
与 Milvus 的对比
原文档给出的对比表如下,可以作为选型参考:
| 特性 | OceanBase | Milvus |
|---|---|---|
| 部署复杂度 | 低(单机部署) | 高(需要 etcd、MinIO) |
| 事务支持 | 完整 ACID | 有限 |
| 向量检索速度 | 中等 | 更快 |
| 存储效率 | 中等 | 更高 |
| 运维成本 | 低 | 高 |
| 学习曲线 | 平缓 | 陡峭 |
从源码角度看,Coze Studio 的向量存储层被抽象为统一的searchstore.Manager接口(见 backend/infra/document/searchstore/impl/impl.go),New()会同时初始化 ES 全文检索 Manager 与一个由VECTOR_STORE_TYPE决定的向量存储 Manager,因此 OceanBase 与 Milvus 在架构上是可替换的平等实现。
二、架构设计与核心组件
整体架构
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Coze Studio │ │ OceanBase │ │ Vector Store │ │ Application │───▶│ Client │───▶│ Manager │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ OceanBase │ │ Database │ └─────────────────┘数据流为:Coze Studio 应用层 → OceanBase Client(GORM 驱动)→ Vector Store Manager(建集合/写读向量)→ OceanBase 数据库。实际代码中,Manager 还负责调用 Embedding 模型完成文档向量化。
1. OceanBase Client(backend/infra/oceanbase/)
主要文件:
- oceanbase.go —— 委托客户端,提供向后兼容接口;
- oceanbase_official.go —— 核心实现,基于 GORM + MySQL 驱动;
- types.go —— 向量索引配置、距离类型与结果类型定义。
核心接口能力:
type OceanBaseClient interface { CreateCollection(ctx context.Context, collectionName string) error InsertVectors(ctx context.Context, collectionName string, vectors []VectorResult) error SearchVectors(ctx context.Context, collectionName string, queryVector []float64, topK int) ([]VectorResult, error) DeleteVector(ctx context.Context, collectionName string, vectorID string) error InitDatabase(ctx context.Context) error DropCollection(ctx context.Context, collectionName string) error }实际实现中,OceanBaseClient持有一个*OceanBaseOfficialClient,全部方法直接委托给后者,这正是文档强调的委托模式(Delegation Pattern):对外保持接口稳定,对内可以随时替换底层实现,保证向后兼容。
OceanBaseOfficialClient通过gorm.io/driver/mysql连接 OceanBase(复用 MySQL 协议),并在初始化时调用setVectorParameters()设置三项关键全局参数(oceanbase_official.go):
params := map[string]string{ "ob_vector_memory_limit_percentage": "30", "ob_query_timeout": "86400000000", "max_allowed_packet": "1073741824", }ob_vector_memory_limit_percentage:向量索引可占用的内存百分比,默认 30;ob_query_timeout:查询超时(微秒),86400000000即 24 小时,避免大查询被截断;max_allowed_packet:最大报文包大小(字节),1GB 以支持大批量向量写入。
2. Search Store Manager(backend/infra/document/searchstore/impl/oceanbase/)
主要文件:
- oceanbase_manager.go —— 管理器实现,含缓存、连接池、维度获取;
- oceanbase_searchstore.go —— 搜索存储实现(Store/Retrieve/Delete);
- factory.go —— 工厂模式创建 Manager;
- consts.go —— 配置结构与默认值;
- convert.go —— 集合名校验、表名生成、元数据与向量转换;
- register.go —— 环境变量解析与注册函数。
核心接口:
type Manager interface { Create(ctx context.Context, collectionName string) (SearchStore, error) Get(ctx context.Context, collectionName string) (SearchStore, error) Delete(ctx context.Context, collectionName string) error }oceanbaseManager在创建时完成多项初始化:校验 Client 与 Embedder 非空、填充默认配置(批次大小、缓存 TTL、连接数、超时、重试等)、可选启动缓存清理协程,并调用Client.InitDatabase探活。
写入链路(Store):对每个文档提取内容 → 调用Embedding.EmbedStrings向量化 → 构建元数据 JSON → 通过batchInsertWithRetry分批写入(默认每批 100 条,失败按MaxRetries重试)。
检索链路(Retrieve):查询串向量化 →SearchVectors取 TopK → 将结果转成 Einoschema.Document并附上相似度分数 → 按分数降序排序、截断 TopK、归一化分数到 [0,1] 区间。
3. 应用层集成(向量存储工厂)
原文档将集成点描述在backend/application/base/appinfra/app_infra.go,实际仓库中 OceanBase 的初始化分支位于 backend/infra/document/searchstore/impl/impl.go 的getVectorStore():
case "oceanbase": emb, err := impl.GetEmbedding(ctx, conf.EmbeddingConfig) ... host = os.Getenv("OCEANBASE_HOST") port = os.Getenv("OCEANBASE_PORT") user = os.Getenv("OCEANBASE_USER") password = os.Getenv("OCEANBASE_PASSWORD") database = os.Getenv("OCEANBASE_DATABASE") // host/port/user/password/database 任一为空都会报错 dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local", user, password, host, port, database) client, err := oceanbase.NewOceanBaseClient(dsn) if err := client.InitDatabase(ctx); err != nil { ... }随后从环境变量读取OCEANBASE_BATCH_SIZE、OCEANBASE_ENABLE_CACHE、OCEANBASE_CACHE_TTL、OCEANBASE_MAX_CONNECTIONS、OCEANBASE_CONN_TIMEOUT,组装ManagerConfig并创建 Manager。应用层通过AppDependencies.SearchStoreManagers(backend/application/base/appinfra/app_infra.go)持有这些 Manager 供知识库服务调用。
三、配置说明
环境变量配置
必需配置
仓库实际使用的连接账号是root@test(租户格式),见 docker/.env.example:
# 向量存储类型 VECTOR_STORE_TYPE=oceanbase # OceanBase 连接配置 OCEANBASE_HOST=127.0.0.1 OCEANBASE_PORT=2881 OCEANBASE_USER=root@test OCEANBASE_PASSWORD=coze123 OCEANBASE_DATABASE=test注意:impl.go的校验逻辑要求上述五个变量全部非空,否则启动报invalid oceanbase configuration。
可选配置
以下变量均在 consts.go 的DefaultConfig()中有默认值,可依据 register.go 中的解析逻辑覆盖:
# 性能优化配置 OCEANBASE_VECTOR_MEMORY_LIMIT_PERCENTAGE=30 # 向量索引内存占比(%) OCEANBASE_BATCH_SIZE=100 # 写入批次大小,上限 1000 OCEANBASE_MAX_OPEN_CONNS=100 # 最大打开连接数 OCEANBASE_MAX_IDLE_CONNS=10 # 最大空闲连接数 OCEANBASE_CONN_MAX_LIFETIME=3600 # 连接最大生命周期(秒) OCEANBASE_CONN_MAX_IDLE_TIME=1800 # 连接最大空闲时间(秒) # 缓存配置 OCEANBASE_ENABLE_CACHE=true # 是否启用集合缓存(默认开启) OCEANBASE_CACHE_TTL=300 # 缓存 TTL(秒),默认 300 # 监控配置 OCEANBASE_ENABLE_METRICS=true # 是否启用指标 OCEANBASE_ENABLE_SLOW_QUERY_LOG=true # 是否启用慢查询日志(阈值 1000ms) # 重试与超时配置 OCEANBASE_MAX_RETRIES=3 # 批量写入/检索最大重试次数 OCEANBASE_RETRY_DELAY=1 # 重试间隔(秒) OCEANBASE_CONN_TIMEOUT=30 # 连接超时(秒)向量维度方面,getVectorDimension()会优先读取ARK_EMBEDDING_DIMS,其次OPENAI_EMBEDDING_DIMS,两者都未设置时回落到2048(defaultVectorDimension);Validate()会将维度限制在 1~4096 之间。若通过config.Knowledge().GetKnowledgeConfig能取到嵌入模型配置,oceanbaseManager.getVectorDimension()会以模型声明的Dims为准(见 oceanbase_manager.go)。
Docker 配置
仓库中实际使用的 OceanBase 服务定义位于 docker/docker-compose-oceanbase.yml,比原文档多出OB_CLUSTER_NAME与健康检查:
oceanbase: image: oceanbase/oceanbase-ce:latest container_name: coze-oceanbase restart: always environment: MODE: SLIM OB_DATAFILE_SIZE: 1G OB_SYS_PASSWORD: ${OCEANBASE_PASSWORD:-coze123} OB_TENANT_PASSWORD: ${OCEANBASE_PASSWORD:-coze123} OB_CLUSTER_NAME: ${OCEANBASE_CLUSTER_NAME:-cozeAi} ports: - '2881:2881' volumes: - ./data/oceanbase/ob:/root/ob - ./data/oceanbase/cluster:/root/.obd/cluster deploy: resources: limits: memory: 4G reservations: memory: 2G healthcheck: test: ['CMD-SHELL', 'obclient -h127.0.0.1 -P2881 -uroot@test -pcoze123 -e "SELECT 1;"'] interval: 10s retries: 30 start_period: 30s timeout: 10s同文件中的coze-server通过depends_on: oceanbase: condition: service_healthy确保向量存储就绪后才启动后端。
四、使用指南
1. 快速启动
仓库通过 Makefile 提供两个专用目标:
# 克隆项目 git clone https://github.com/coze-dev/coze-studio.git cd coze-studio # 设置 OceanBase 环境文件 make oceanbase_env # 启动 OceanBase 调试环境(含中间件与调试服务) make oceanbase_debugmake oceanbase_env实际执行 scripts/setup/oceanbase_env.sh,该脚本将docker/.env.debug(或docker/.env)中的VECTOR_STORE_TYPE从milvus/vikingdb替换为oceanbase,并做幂等校验:若已配置则直接提示Already configured for OceanBase,避免重复改写。
2. 验证部署
# 检查容器状态 docker ps | grep oceanbase # 测试连接(MySQL 协议兼容) mysql -h localhost -P 2881 -u root@test -p -e "SELECT 1;" # 查看数据库 mysql -h localhost -P 2881 -u root@test -p -e "SHOW DATABASES;"3. 创建知识库
在 Coze Studio 界面中:
- 进入知识库管理;
- 在向量存储中选择 OceanBase(对应
VECTOR_STORE_TYPE=oceanbase); - 上传文档触发向量化——代码中
Store()会对每个文档调用 Embedding 模型生成向量,并以vector_<collectionName>为表名写入 OceanBase; - 测试向量检索——
Retrieve()内部执行近似最近邻查询并返回带相似度分数的文档列表。
关于集合命名,convert.go 的ValidateCollectionName有严格约束:非空、长度 ≤ 255、不能以数字开头、仅允许字母数字下划线与连字符、不能是 SQL 保留字;TableName()会将集合名清洗后统一转换为vector_<小写名>的表名,物理表位于OCEANBASE_DATABASE指定的库中。
4. 性能监控
# 查看容器资源使用 docker stats coze-oceanbase # 查看慢查询日志 docker logs coze-oceanbase | grep "slow query" # 查看连接数 mysql -h localhost -P 2881 -u root@test -p -e "SHOW PROCESSLIST;"五、Helm 部署指南(Kubernetes)
Coze Studio 的 Helm Chart(helm/charts/opencoze/)内置了完整的 OceanBase 编排:oceanbase-secret.yaml(四类用户密钥)、oceanbase-service.yaml、oceanbase-serviceaccount.yaml、oceanbase-statefulset.yaml(基于 ob-operator 的 OBCluster CRD)。
1. 环境准备
- Kubernetes 集群(推荐 k3s 或 kind);
- Helm 3.x;
- kubectl。
2. 安装依赖
安装 cert-manager
helm repo add jetstack https://charts.jetstack.io helm repo update # 安装 cert-manager(v1.16.2) kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml # 等待 cert-manager 就绪 kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=cert-manager -n cert-manager --timeout=300s安装 ob-operator
helm repo add ob-operator https://oceanbase.github.io/ob-operator/ helm repo update helm install ob-operator ob-operator/ob-operator --set reporter=cozeAi --namespace=oceanbase-system --create-namespace kubectl wait --for=condition=ready pod -l control-plane=controller-manager -n oceanbase-system --timeout=300s3. 部署 OceanBase
使用集成 Helm Chart
# 部署完整的 Coze Studio 应用(包含 OceanBase) helm install coze-studio helm/charts/opencoze \ --set oceanbase.enabled=true \ --namespace coze-studio \ --create-namespace # 或者只部署 OceanBase 组件 helm install oceanbase-only helm/charts/opencoze \ --set oceanbase.enabled=true \ --set mysql.enabled=false \ --set redis.enabled=false \ --set minio.enabled=false \ --set elasticsearch.enabled=false \ --set milvus.enabled=false \ --set rocketmq.enabled=false \ --namespace oceanbase \ --create-namespace自定义配置
Chart 默认值位于 helm/charts/opencoze/values.yaml,其中oceanbase默认enabled: false。创建oceanbase-values.yaml覆盖关键参数:
oceanbase: enabled: true port: 2881 targetPort: 2881 clusterName: 'cozeAi' clusterId: 1 image: repository: oceanbase/oceanbase-cloud-native tag: '4.3.5.3-103000092025080818' obAgentVersion: '4.2.2-100000042024011120' monitorEnabled: true storageClass: '' observerConfig: resource: cpu: 2 memory: 8Gi storages: dataStorage: 30Gi redoLogStorage: 30Gi logStorage: 10Gi monitorResource: cpu: 100m memory: 256Mi generateUserSecrets: true userSecrets: root: 'coze123' monitor: 'coze123' operator: 'coze123' proxyro: 'coze123' topology: - zone: zone1 replica: 1 parameters: - name: system_memory value: '4G' - name: '__min_full_resource_pool_memory' value: '4294967296' annotations: {} backupVolumeEnabled: false使用自定义配置部署:
helm install oceanbase-custom helm/charts/opencoze \ -f oceanbase-values.yaml \ --namespace oceanbase \ --create-namespace4. 验证部署
kubectl get obcluster -n oceanbase kubectl get pods -n oceanbase kubectl get svc -n oceanbase kubectl describe obcluster -n oceanbase5. 连接测试
端口转发
kubectl port-forward svc/oceanbase-service -n oceanbase 2881:2881使用 obclient 连接
# 在集群内连接 kubectl exec -it deployment/oceanbase-obcluster-zone1 -n oceanbase -- obclient -h127.0.0.1 -P2881 -uroot@test -pcoze123 -Dtest # 从外部连接(需要端口转发) obclient -h127.0.0.1 -P2881 -uroot@test -pcoze123 -Dtest使用 MySQL 客户端连接
mysql -h127.0.0.1 -P2881 -uroot@test -pcoze123 -Dtest6. 监控和管理
查看日志
kubectl logs -f deployment/oceanbase-obcluster-zone1 -n oceanbase kubectl logs -f deployment/oceanbase-controller-manager -n oceanbase-system扩缩容
# 扩展副本数 kubectl patch obcluster oceanbase-obcluster -n oceanbase --type='merge' -p='{"spec":{"topology":[{"zone":"zone1","replica":2}]}}' # 调整资源配置 kubectl patch obcluster oceanbase-obcluster -n oceanbase --type='merge' -p='{"spec":{"observer":{"resource":{"cpu":4,"memory":"16Gi"}}}}'备份和恢复
kubectl apply -f - <<EOF apiVersion: oceanbase.oceanbase.com/v1alpha1 kind: OBTenantBackupPolicy metadata: name: backup-policy namespace: oceanbase spec: obClusterName: oceanbase-obcluster tenantName: test backupType: FULL schedule: "0 2 * * *" destination: path: "file:///backup" EOF7. 故障排除
常见问题
OBCluster 创建失败
kubectl get pods -n oceanbase-system kubectl describe obcluster -n oceanbase镜像拉取失败
kubectl describe node docker pull oceanbase/oceanbase-cloud-native:4.3.5.3-103000092025080818存储问题
kubectl get pvc -n oceanbase kubectl get storageclass
日志分析
kubectl logs -f deployment/oceanbase-controller-manager -n oceanbase-system kubectl logs -f deployment/oceanbase-obcluster-zone1 -n oceanbase kubectl logs -f deployment/cert-manager -n cert-manager8. 卸载
helm uninstall oceanbase-custom -n oceanbase kubectl delete namespace oceanbase helm uninstall ob-operator -n oceanbase-system kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml六、适配特点与技术亮点
1. 设计原则
架构兼容性设计:严格遵循 Coze Studio 的向量存储抽象(searchstore.Manager/searchstore.SearchStore),OceanBase 适配层实现同一接口,与 ES、Milvus 实现平级注册;采用委托模式保证向后兼容,OceanBaseClient仅是OceanBaseOfficialClient的薄封装。
性能优先:
- 建集合时自动创建 HNSW 向量索引(
distance=cosine, type=hnsw, lib=vsag, m=16, ef_construction=200, ef_search=64),见 oceanbase_official.go; - 批量操作:写入按 100 条一批,
SearchVectors使用APPROXIMATE提示走近似检索,先取topK*2再在内存中按相似度过滤、排序、截断(oceanbase_official.go); - 连接池与集合缓存:
MaxOpenConns/MaxIdleConns控制连接资源,EnableCache开启后按CacheTTL缓存 SearchStore 实例并由后台协程定期清理过期条目(oceanbase_manager.go)。
易于部署:单机镜像、Docker Compose 一段服务、环境变量全量可调,配合make oceanbase_env一条命令完成向量存储类型切换。
2. 技术亮点
委托模式设计
type OceanBaseClient struct { official *OceanBaseOfficialClient } func (c *OceanBaseClient) CreateCollection(ctx context.Context, collectionName string, dimension int) error { return c.official.CreateCollection(ctx, collectionName, dimension) }智能配置管理
func DefaultConfig() *Config { return &Config{ Host: getEnv("OCEANBASE_HOST", "localhost"), Port: getEnvAsInt("OCEANBASE_PORT", 2881), User: getEnv("OCEANBASE_USER", "root"), Password: getEnv("OCEANBASE_PASSWORD", ""), Database: getEnv("OCEANBASE_DATABASE", "test"), // ... 其他配置均提供默认值 } }错误处理优化
func (c *OceanBaseOfficialClient) setVectorParameters() error { params := map[string]string{ "ob_vector_memory_limit_percentage": "30", "ob_query_timeout": "86400000000", "max_allowed_packet": "1073741824", } for param, value := range params { if err := c.db.Exec(fmt.Sprintf("SET GLOBAL %s = %s", param, value)).Error; err != nil { log.Printf("Warning: Failed to set %s: %v", param, err) } } return nil }参数设置失败只告警不阻断启动,避免因权限不足导致整个向量存储不可用;同理,HNSW 索引创建失败时日志提示will use exact search,系统自动降级为精确检索,保证功能可用性。
3. 向量索引与距离类型(types.go)
types.go 定义了完整的索引配置体系,供建索引与查询场景使用:
- 索引类型:
hnsw、hnsw_sq、hnsw_bq、ivf_flat、ivf_sq8、ivf_pq; - 距离度量:
l2、cosine、inner_product; - 索引库:
vsag(默认,配合 HNSW)与ob(配合 IVF); - 默认 HNSW 参数:
m=16、ef_construction=200、ef_search=64,与建表 SQL 中的参数保持一致。
七、故障排查
1. 常见问题
连接问题
docker ps | grep oceanbase docker port coze-oceanbase mysql -h localhost -P 2881 -u root@test -p -e "SELECT 1;"向量索引问题
-- 检查索引状态 SHOW INDEX FROM test_vectors; -- 重建索引 DROP INDEX idx_test_embedding ON test_vectors; CREATE VECTOR INDEX idx_test_embedding ON test_vectors(embedding) WITH (distance=cosine, type=hnsw, lib=vsag, m=16, ef_construction=200, ef_search=64);性能问题
-- 调整向量索引内存限制 SET GLOBAL ob_vector_memory_limit_percentage = 50; -- 查看慢查询开关 SHOW VARIABLES LIKE 'slow_query_log';2. 日志分析
# 查看 OceanBase 容器日志 docker logs coze-oceanbase # 查看应用日志中的向量相关输出 tail -f logs/coze-studio.log | grep -i "oceanbase\|vector"代码中SearchVectors与Retrieve均带有丰富的 Debug 日志(集合信息、原始查询 SQL、结果数量、相似度分数、归一化前后分值等),排查召回异常时可优先检索[Debug]与Normalizing scores关键字。
八、总结
OceanBase 向量数据库在 Coze Studio 中的集成实现了以下目标:
- 功能完整:通过统一的
searchstore.Manager接口支持集合创建、向量写入、近似检索与删除,完整覆盖知识库向量化召回全流程; - 性能良好:HNSW 向量索引 +
APPROXIMATE近似查询 + 批量写入 + 连接池/缓存,兼顾检索速度与资源利用; - 部署简单:Docker Compose 单服务即可拉起,
make oceanbase_env一条命令切换向量存储类型; - 运维友好:环境变量全量可调、慢查询日志与指标开关、Kubernetes 下由 ob-operator 托管扩缩容与备份;
- 扩展性强:既支持单机垂直扩容(调大
observerConfig.resource),也支持通过 topology 副本扩展实现水平扩展。
对于需要事务支持、部署简单、运维成本低的场景,OceanBase 是 Coze Studio 知识库向量存储的一个务实选择。
相关资源
- 集成文档原文:docs/oceanbase-integration-guide.md(英文版见 docs/oceanbase-integration-guide-en.md);
- OceanBase 客户端实现:backend/infra/oceanbase/;
- 向量存储适配层:backend/infra/document/searchstore/impl/oceanbase/;
- 向量存储工厂与类型分发:backend/infra/document/searchstore/impl/impl.go;
- Docker 编排:docker/docker-compose-oceanbase.yml;
- Helm Chart 默认值:helm/charts/opencoze/values.yaml 与模板 helm/charts/opencoze/templates/oceanbase-statefulset.yaml;
- 环境配置脚本:scripts/setup/oceanbase_env.sh;
- 环境变量示例:docker/.env.example。
【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考