Coze Studio 知识库向量化如何配置 Embedding 模型与向量维度-平芜编程栈

Coze Studio 知识库向量化如何配置 Embedding 模型与向量维度

【免费下载链接】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 中部署好服务后，要让知识库功能真正跑起来，向量化的前提是把 Embedding 模型和向量维度配置好：知识库向量化依赖的 Embedding 模型由部署环境的配置提供（见 docker/.env.example 中# Settings for Embedding一段的说明）。本文以 docker compose 本地部署为环境，说明如何选定一种 Embedding 接入方式、填写对应的环境变量或后台配置项、设置向量维度，以及确认配置已经生效。

如果向量数据库本身带内建 Embedding 能力（文档以 VikingDB 为例，即设置了VIKING_DB_MODEL_NAME），则不需要再配置 Embedding 相关项；其余向量库（如示例默认的 Milvus）都需要按本文完成配置。

准备条件

已按项目部署方式启动服务，环境变量基线为 docker/.env.example；
向量库已完成选择，VECTOR_STORE_TYPE为milvus/vikingdb/oceanbase之一，对应的连接变量（如MILVUS_ADDR、VIKING_DB_*、OCEANBASE_*）已按该向量库的要求填写；
手上有一个可用的 Embedding 服务，属于 Coze Studio 支持的接入方式之一：ark、openai、ollama、gemini、http。

主路径：通过环境变量配置 Embedding

编辑.env文件（由docker/.env.example复制而来），完成以下三步。

第一步：选定 Embedding 接入方式

设置类型开关（示例文件默认值为ark）：

export EMBEDDING_TYPE="ark" # embedding type: ark / openai / ollama / gemini / http

注意后端对未识别的值有兜底：在 knowledge.go 的getEmbeddingType()中，EMBEDDING_TYPE不是上述五种取值时会回落到 Ark，所以填错类型不会报"未知类型"，而是静默按 Ark 走。

第二步：填写所选类型的连接与维度变量

各类型的必填变量都遵循<类型>_EMBEDDING_*前缀（来源：.env.example 的# Settings for Embedding段）：

类型	连接/模型变量	维度变量	附加可选变量
ark	`ARK_EMBEDDING_BASE_URL`、`ARK_EMBEDDING_MODEL`、`ARK_EMBEDDING_API_KEY`	`ARK_EMBEDDING_DIMS`（示例值 2048）	`ARK_EMBEDDING_API_TYPE`：`text_api`/`multi_modal_api`，默认`text_api`
openai	`OPENAI_EMBEDDING_BASE_URL`、`OPENAI_EMBEDDING_MODEL`、`OPENAI_EMBEDDING_API_KEY`	`OPENAI_EMBEDDING_DIMS`（示例值 1024）	`OPENAI_EMBEDDING_BY_AZURE`、`OPENAI_EMBEDDING_API_VERSION`、`OPENAI_EMBEDDING_REQUEST_DIMS`（API 不支持指定维度时置空）
ollama	`OLLAMA_EMBEDDING_BASE_URL`、`OLLAMA_EMBEDDING_MODEL`	`OLLAMA_EMBEDDING_DIMS`	—
gemini	`GEMINI_EMBEDDING_BASE_URL`、`GEMINI_EMBEDDING_MODEL`（示例值`gemini-embedding-001`）、`GEMINI_EMBEDDING_API_KEY`	`GEMINI_EMBEDDING_DIMS`（示例值 2048）	`GEMINI_EMBEDDING_BACKEND`：`1`为 BackendGeminiAPI，`2`为 BackendVertexAI；`GEMINI_EMBEDDING_PROJECT`、`GEMINI_EMBEDDING_LOCATION`
http	`HTTP_EMBEDDING_ADDR`	`HTTP_EMBEDDING_DIMS`（示例值 1024）	—

以上除base_url/api_key/model/addr由你的 Embedding 服务决定外，其余均可直接照抄示例文件中的取值。关于维度需要说明两点：

示例文件把各类型的*_EMBEDDING_DIMS标注为 required；而代码兜底逻辑（knowledge.go 中getKnowledgeConfigurationFromOldConfig()）在未读到维度变量时按 1024 处理。建议显式写维度，不要依赖兜底值。
Ark 的 API Key 有一个额外来源：ARK_EMBEDDING_API_KEY为空时会回退读取ARK_EMBEDDING_AK（getArkEmbeddingAPIKey()）。

第三步：设置批处理大小

export EMBEDDING_MAX_BATCH_SIZE=100

这是 Embedding 调用的批处理大小，示例默认 100。

重启使配置生效

环境变量是进程启动时读取的，修改.env后需要按项目部署文档重启后端容器（例如docker compose restart，以你实际使用的 compose 文件为准）。

替代路径：管理页在线配置 Embedding

后端在/admin下挂了管理页面（register.go 中r.StaticFS("/admin", ...)提供静态页，api.go 中/admin/config路由组受管理端鉴权中间件保护）。该页面的"Embedding 配置"区块（见 admin 页面中knowledge.section.embedding对应区域）提供与上面相同字段的表单：类型下拉（Ark / OpenAI / Ollama / Gemini / HTTP）、max_batch_size、各类型的dims以及api_type、by_azure、api_version、backend等附加项。

使用这条路径时注意配置的优先级：GetKnowledgeConfig()会优先读取数据库knowledge_config键中保存的配置，只有该键不存在时才回退到环境变量推导出的配置。也就是说，一旦你在管理页保存过知识配置，环境变量就不再是生效值，后续改动要回到管理页做。

验证配置是否生效

打开/admin管理页，进入"Embedding 配置"区块。页面加载时会回显当前生效的配置值：若数据库里已有保存值则回显保存值，否则回显由环境变量推导出的值（admin 页面中embedding_config的回显逻辑）。核对你设置过的type、max_batch_size、对应类型的连接信息与dims是否与预期一致。
知识库向量化过程使用这份 Embedding 配置（.env.example 明确说明该配置是"knowledge base vectorization"所依赖的 Embedding 模型）。创建知识库并上传文档后，观察文档向量化任务能否正常完成，即可判断所配置的 Embedding 服务（地址、Key、模型名、维度）是否可用。

边界与限制

配置优先级：数据库knowledge_config> 环境变量。两套来源同时存在时，以管理页保存的值为准，排查"改了 .env 没生效"时先确认数据库里是否已有保存配置。
维度一致性：示例文件中各类型的维度示例值并不相同（ark 2048、openai 1024、gemini 2048、http 1024、ollama 无示例值），维度必须按你所用 Embedding 模型实际产出的维度填写，文档未提供通用换算规则。
VikingDB 例外：向量库为 VikingDB 且已设置VIKING_DB_MODEL_NAME时，向量化使用其内建 Embedding，可跳过本文的 Embedding 配置。
Rerank 不属于本配置：知识库的 rerank 走独立的RERANK_TYPE（vikingdb/rrf）一组变量，与向量化 Embedding 配置相互独立，本文不展开。

完成上述任一路径的配置并通过管理页回显核对后，知识库向量化即可使用你所指定的 Embedding 模型与维度工作；若后续更换 Embedding 模型，需要同步更新对应*_EMBEDDING_DIMS并在管理页或.env中保持单一来源生效。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考