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 中选择 OceanBaseCoze 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 的对比原文档给出的对比表如下可以作为选型参考特性OceanBaseMilvus部署复杂度低单机部署高需要 etcd、MinIO事务支持完整 ACID有限向量检索速度中等更快存储效率中等更高运维成本低高学习曲线平缓陡峭从源码角度看Coze Studio 的向量存储层被抽象为统一的searchstore.Manager接口见 backend/infra/document/searchstore/impl/impl.goNew()会同时初始化 ES 全文检索 Manager 与一个由VECTOR_STORE_TYPE决定的向量存储 Manager因此 OceanBase 与 Milvus 在架构上是可替换的平等实现。二、架构设计与核心组件整体架构┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Coze Studio │ │ OceanBase │ │ Vector Store │ │ Application │───▶│ Client │───▶│ Manager │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ OceanBase │ │ Database │ └─────────────────┘数据流为Coze Studio 应用层 → OceanBase ClientGORM 驱动→ Vector Store Manager建集合/写读向量→ OceanBase 数据库。实际代码中Manager 还负责调用 Embedding 模型完成文档向量化。1. OceanBase Clientbackend/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.goparams : map[string]string{ ob_vector_memory_limit_percentage: 30, ob_query_timeout: 86400000000, max_allowed_packet: 1073741824, }ob_vector_memory_limit_percentage向量索引可占用的内存百分比默认 30ob_query_timeout查询超时微秒86400000000即 24 小时避免大查询被截断max_allowed_packet最大报文包大小字节1GB 以支持大批量向量写入。2. Search Store Managerbackend/infra/document/searchstore/impl/oceanbase/主要文件oceanbase_manager.go —— 管理器实现含缓存、连接池、维度获取oceanbase_searchstore.go —— 搜索存储实现Store/Retrieve/Deletefactory.go —— 工厂模式创建 Managerconsts.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:%stcp(%s:%s)/%s?charsetutf8mb4parseTimeTruelocLocal, 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.SearchStoreManagersbackend/application/base/appinfra/app_infra.go持有这些 Manager 供知识库服务调用。三、配置说明环境变量配置必需配置仓库实际使用的连接账号是roottest租户格式见 docker/.env.example# 向量存储类型 VECTOR_STORE_TYPEoceanbase # OceanBase 连接配置 OCEANBASE_HOST127.0.0.1 OCEANBASE_PORT2881 OCEANBASE_USERroottest OCEANBASE_PASSWORDcoze123 OCEANBASE_DATABASEtest注意impl.go的校验逻辑要求上述五个变量全部非空否则启动报invalid oceanbase configuration。可选配置以下变量均在 consts.go 的DefaultConfig()中有默认值可依据 register.go 中的解析逻辑覆盖# 性能优化配置 OCEANBASE_VECTOR_MEMORY_LIMIT_PERCENTAGE30 # 向量索引内存占比% OCEANBASE_BATCH_SIZE100 # 写入批次大小上限 1000 OCEANBASE_MAX_OPEN_CONNS100 # 最大打开连接数 OCEANBASE_MAX_IDLE_CONNS10 # 最大空闲连接数 OCEANBASE_CONN_MAX_LIFETIME3600 # 连接最大生命周期秒 OCEANBASE_CONN_MAX_IDLE_TIME1800 # 连接最大空闲时间秒 # 缓存配置 OCEANBASE_ENABLE_CACHEtrue # 是否启用集合缓存默认开启 OCEANBASE_CACHE_TTL300 # 缓存 TTL秒默认 300 # 监控配置 OCEANBASE_ENABLE_METRICStrue # 是否启用指标 OCEANBASE_ENABLE_SLOW_QUERY_LOGtrue # 是否启用慢查询日志阈值 1000ms # 重试与超时配置 OCEANBASE_MAX_RETRIES3 # 批量写入/检索最大重试次数 OCEANBASE_RETRY_DELAY1 # 重试间隔秒 OCEANBASE_CONN_TIMEOUT30 # 连接超时秒向量维度方面getVectorDimension()会优先读取ARK_EMBEDDING_DIMS其次OPENAI_EMBEDDING_DIMS两者都未设置时回落到2048defaultVectorDimensionValidate()会将维度限制在 14096 之间。若通过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 -uroottest -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 roottest -p -e SELECT 1; # 查看数据库 mysql -h localhost -P 2881 -u roottest -p -e SHOW DATABASES;3. 创建知识库在 Coze Studio 界面中进入知识库管理在向量存储中选择 OceanBase对应VECTOR_STORE_TYPEoceanbase上传文档触发向量化——代码中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 roottest -p -e SHOW PROCESSLIST;五、Helm 部署指南KubernetesCoze Studio 的 Helm Charthelm/charts/opencoze/内置了完整的 OceanBase 编排oceanbase-secret.yaml四类用户密钥、oceanbase-service.yaml、oceanbase-serviceaccount.yaml、oceanbase-statefulset.yaml基于 ob-operator 的 OBCluster CRD。1. 环境准备Kubernetes 集群推荐 k3s 或 kindHelm 3.xkubectl。2. 安装依赖安装 cert-managerhelm repo add jetstack https://charts.jetstack.io helm repo update # 安装 cert-managerv1.16.2 kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml # 等待 cert-manager 就绪 kubectl wait --forconditionready pod -l app.kubernetes.io/namecert-manager -n cert-manager --timeout300s安装 ob-operatorhelm repo add ob-operator https://oceanbase.github.io/ob-operator/ helm repo update helm install ob-operator ob-operator/ob-operator --set reportercozeAi --namespaceoceanbase-system --create-namespace kubectl wait --forconditionready pod -l control-planecontroller-manager -n oceanbase-system --timeout300s3. 部署 OceanBase使用集成 Helm Chart# 部署完整的 Coze Studio 应用包含 OceanBase helm install coze-studio helm/charts/opencoze \ --set oceanbase.enabledtrue \ --namespace coze-studio \ --create-namespace # 或者只部署 OceanBase 组件 helm install oceanbase-only helm/charts/opencoze \ --set oceanbase.enabledtrue \ --set mysql.enabledfalse \ --set redis.enabledfalse \ --set minio.enabledfalse \ --set elasticsearch.enabledfalse \ --set milvus.enabledfalse \ --set rocketmq.enabledfalse \ --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 -uroottest -pcoze123 -Dtest # 从外部连接需要端口转发 obclient -h127.0.0.1 -P2881 -uroottest -pcoze123 -Dtest使用 MySQL 客户端连接mysql -h127.0.0.1 -P2881 -uroottest -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 --typemerge -p{spec:{topology:[{zone:zone1,replica:2}]}} # 调整资源配置 kubectl patch obcluster oceanbase-obcluster -n oceanbase --typemerge -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.SearchStoreOceanBase 适配层实现同一接口与 ES、Milvus 实现平级注册采用委托模式保证向后兼容OceanBaseClient仅是OceanBaseOfficialClient的薄封装。性能优先建集合时自动创建 HNSW 向量索引distancecosine, typehnsw, libvsag, m16, ef_construction200, ef_search64见 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.gotypes.go 定义了完整的索引配置体系供建索引与查询场景使用索引类型hnsw、hnsw_sq、hnsw_bq、ivf_flat、ivf_sq8、ivf_pq距离度量l2、cosine、inner_product索引库vsag默认配合 HNSW与ob配合 IVF默认 HNSW 参数m16、ef_construction200、ef_search64与建表 SQL 中的参数保持一致。七、故障排查1. 常见问题连接问题docker ps | grep oceanbase docker port coze-oceanbase mysql -h localhost -P 2881 -u roottest -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 (distancecosine, typehnsw, libvsag, m16, ef_construction200, ef_search64);性能问题-- 调整向量索引内存限制 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.mdOceanBase 客户端实现backend/infra/oceanbase/向量存储适配层backend/infra/document/searchstore/impl/oceanbase/向量存储工厂与类型分发backend/infra/document/searchstore/impl/impl.goDocker 编排docker/docker-compose-oceanbase.ymlHelm 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），仅供参考