Skip to content

5. 基础组件配置

Jump to bottom
newacc edited this page Aug 22, 2025 · 5 revisions

部署 Coze Studio 开源版之后，如需使用图片上传功能，或知识库相关功能，应参考本文档配置功能相关的基础组件。这些组件通常依赖火山引擎等第三方服务，配置组件时需要填写第三方服务的账号密钥等鉴权配置。

上传组件

在多模态对话场景，往往需要在对话中上传图片、文件等信息，例如在智能体调试区域中发送图片消息：

Image

此功能由上传组件提供。Coze Studio 上传组件目前支持以下三种，你可以任选一种作为上传组件。

  • （默认）minio：图片和文件自动上传至本地主机的 minio 服务，通过指定端口号可访问。但本地主机必须配置公网域名，否则已上传的图片和文件只能生成内网访问链接，无法被大模型读取和识别。
  • 火山引擎对象存储 TOS：图片和文件自动上传至指定的火山引擎对象存储 TOS 服务，并生成一个公网可访问的 URL。如果选择 TOS，必须先开通 TOS 并在 Coze Studio 中配置火山密钥。
  • 火山引擎 ImageX：图片和文件自动上传至指定的火山引擎 ImageX，并生成一个公网可访问的 URL。如果选择 ImageX，必须先开通 ImageX 并在 Coze Studio 中配置火山密钥。

上传组件的配置方式如下：

  1. 设置上传组件类型。 在 docker 目录中打开 .env 文件，配置项 "FILE_UPLOAD_COMPONENT_TYPE" 的值表示上传组件类型。

    • storage（默认）：表示使用STORAGE_TYPE 配置的存储组件，STORAGE_TYPE 默认为 minio，也支持配置为 tos。
    • imagex：表示使用火山 ImageX 组件。
    # This Upload component used in Agent / workflow File/Image With LLM  , support the component of imagex / storage
# default: storage, use the settings of storage component
# if imagex, you must finish the configuration of <VolcEngine ImageX> 
export FILE_UPLOAD_COMPONENT_TYPE="storage"

  2. 为上传组件添加秘钥等配置。 同样在 docker 目录的 .env 文件中，根据组件类型填写以下配置。

    组件类型 配置方式 示例
    minio
    （默认）    		 1. 在 Coze studio 项目的 docker/.env 文件中，FILE_UPLOAD_COMPONENT_TYPE 设置为 storage。
    2. 在 Storage component 区域，设置 STORAGE_TYPE 为 minio。
    3. 在 MiniO 区域，维持默认配置即可。

    如果你选择在火山引擎等公共云上部署 Coze Studio，则需要提前为你的云服务器开放 8888、8889 端口的访问权限。
    		Image
    tos 1. 开通火山引擎 TOS 产品。
    2. 在 Coze studio 项目的 docker/.env 文件中，FILE_UPLOAD_COMPONENT_TYPE 设置为 storage。
    3. 在 Storage component 区域，设置 STORAGE_TYPE 为 tos。
    4. 在 TOS 区域，填写以下参数：
    * TOS_ACCESS_KEY：火山引擎密钥 AK。获取方式可参考获取火山引擎 API 密钥。
    * TOS_SECRET_KEY：火山引擎密钥 SK。获取方式可参考获取火山引擎 API 密钥。
    * TOS_ENDPOINT：TOS 服务的 Endpoint，获取方式可参考地域和访问域名。
    * TOS_REGION：TOS 服务所在的地域，获取方式可参考地域和访问域名。
    Image
    imagex 1. 开通火山引擎 veImageX 产品，并创建素材托管服务。操作步骤可参考火山 veImageX 官方文档。注意创建素材托管服务时需要填写域名，建议提前获取一个可用的公开域名。
    2. 在 Coze studio 项目的 docker/.env 文件中，FILE_UPLOAD_COMPONENT_TYPE 设置为 imagex。
    3. 在 VolcEngine ImageX 区域，填写以下参数：
    * VE_IMAGEX_AK：火山引擎密钥 AK。获取方式可参考获取火山引擎 API 密钥。
    * VE_IMAGEX_SK：火山引擎密钥 SK。获取方式可参考获取火山引擎 API 密钥。
    * VE_IMAGEX_SERVER_ID：火山引擎 veImageX 产品服务管理页面展示的服务 ID。
    * VE_IMAGEX_DOMAIN：创建服务时指定的域名。
    * VE_IMAGEX_TEMPLATE：图片处理配置的模板名称。
    Image

  3. 执行以下命令重启服务，使以上配置生效。

    docker compose --profile '*' up -d --force-recreate --no-deps coze-server

知识库相关组件

文档解析器（Document Parser）

文档解析是信息入库的必要前置环节，也是整个流程的起点。文档解析器能够从 PDF、DOCX 等多种类型的文档中抽取文本、表格等核心内容，这些内容在经过后续组件处理后，最终被存储到知识库中。 Coze Studio 支持用户通过修改配置定制文档解析器。目前，支持的文档解析器类型如下：

  • 内置文档解析器：提供基本的文档解析能力，支持处理 PDF、TXT、Markdown、DOCX、CSV、XLSX、JSON 等多种类型文件。Coze Studio 默认使用内置文档解析器，无需调整配置。
  • PaddleOCR 文档解析器：对于 PDF 文件，采用 PaddleOCR 的 PP-StructureV3 版面解析方案，提供更强大的文档解析能力，不仅可以提取文本、表格、公式、图片、印章等版面元素，还可以保持版面的原始阅读顺序，尤其适合处理扫描件。对于其他类型的文件，目前与内置文档解析器的功能相同。

如果希望使用 PaddleOCR 文档解析器，可参考如下步骤将文档解析器由内置文档解析器改为 PaddleOCR：

  1. 参考 PaddleOCR 安装文档 安装飞桨框架与 PaddleOCR 推理包。 为了取得最佳精度，PP-StructureV3 的默认配置需要使用较多计算资源。建议准备 16 GB 以上显存的 GPU，并安装 GPU 版本的飞桨框架。如果希望使用更少的计算资源，例如用 CPU 部署服务，可参考后续步骤说明调整产线配置。

  2. 执行以下命令，安装服务化部署所需依赖：

    paddlex --install serving

  3. 执行如下命令，以默认配置运行 PP-StructureV3 产线推理服务：

    paddlex --serve --pipeline PP-StructureV3 --port <端口号>

如果希望调整产线配置（例如希望更换轻量级模型以使用更少的计算资源），可参考如下步骤：

  1. 通过 paddlex --get_pipeline_config PP-StructureV3 获取默认产线配置文件。
  2. 根据需要修改产线配置文件。例如：
    • 关闭不需要用到的功能，如设置 use_formula_recognition 为 False 以禁用公式识别。
    • 使用轻量级的模型，如将 OCR 模型替换为 mobile 版本、换用轻量的公式识别模型 PP-FormulaNet-S 等。
  3. 以修改后的配置运行产线推理服务：paddlex --serve --pipeline <配置文件路径> --port <端口号>。 关于 PaddleOCR 产线的更多说明，可以参考 PP-StructureV3 产线使用文档 以及 PaddleOCR 服务化部署文档。
  4. 在本地项目中填写文档解析器配置。
    1. 进入 docker 目录。
    2. 打开文件 .env ，将 PARSER_TYPE 设置为 paddleocr，将 PADDLEOCR_STRUCTURE_API_URL 设置为上一步骤启动的 PP-StructureV3 产线推理服务的 API URL，例如 http://localhost:9999/layout-parsing 。
    3. 保存配置。

完成配置修改后，执行以下命令重启 Coze Studio 后端服务。

docker compose --profile '*' up -d --force-recreate --no-deps coze-server

文字识别（OCR）

在创建知识库时，如果上传的本地文件是扫描件，往往需要开启 ORC 功能来识别图片或文件中的文字信息。配置示例如下： Image 在 Coze Studio 开源版中开启 OCR 功能前，应先配置提供 OCR 能力的底层服务。目前，支持如下类型的底层 OCR 服务，对接时任选其一即可：

  • 火山引擎 OCR：火山引擎提供的商业化产品 OCR 产品。
  • PaddleOCR：百度飞桨推出的开源 OCR 方案，默认使用最新的 PP-OCRv5 模型。

火山引擎 ORC

如果选择火山引擎 OCR 方案，需要先在火山开通 OCR 产品，并在本地项目中填写 ORC 配置，将 OCR 组件的 AK、SK 配置为火山引擎的密钥对。详细操作步骤如下：

  1. 开通火山引擎通用文字识别产品。 你可以根据页面提示完成开通。开通产品后，通用文字识别产品页面显示接入状态为正式开通，示例如下： Image

  2. 获取火山账号的 AK 和 SK，后续步骤中需要使用。 获取方式可参考火山官方文档。

  3. 在本地项目中填写 ORC 配置。

    1. 进入目录docker/目录。
    2. 打开文件 .env ，修改 VE_OCR_AK、VE_OCR_SK 配置项。
      • VE_OCR_AK：配置为步骤二中获取的火山账号 AK。
      • VE_OCR_SK：配置为步骤二中获取的火山账号 SK。
    3. 保存配置。 
      # Settings for OCR
# If you want to use the OCR-related functions in the knowledge base feature，You need to set up the OCR configuration. 
# Currently, Coze Studio has built-in Volcano OCR.
# ocr_type: default type `ve`
export OCR_TYPE="ve"
# ve ocr
export VE_OCR_AK=""
export VE_OCR_SK=""

  4. 执行以下命令重启服务。

    docker compose --profile '*' up -d --force-recreate --no-deps coze-server

PaddleOCR

如果希望使用 PaddleOCR 方案，可参考如下步骤：

  1. 参考 PaddleOCR 安装文档 安装飞桨框架与 PaddleOCR 推理包。为了取得最佳精度，默认的 PP-OCRv5 配置需要使用较多计算资源。建议准备 8 GB 以上显存的 GPU，并安装 GPU 版本的飞桨框架。如果希望使用更少的计算资源，例如用 CPU 部署服务，可参考后续步骤说明调整产线配置。

  2. 执行以下命令，安装服务化部署所需依赖：

    paddlex --install serving

  3. 执行如下命令，以默认配置运行通用 OCR 产线推理服务：

    paddlex --serve --pipeline OCR --port <端口号>

如果希望调整产线配置（例如，希望更换轻量级模型以使用更少的计算资源），可参考如下步骤：

  1. 通过 paddlex --get_pipeline_config OCR 获取默认产线配置文件。
  2. 根据需要修改产线配置文件。 例如使用轻量级的模型，如将文本检测模型（SubModules.TextDetection.model_name）与文本识别模型（SubModules.TextRecognition.model_name）分别替换为 PP-OCRv5_mobile_det 和 PP-OCRv5_mobile_rec。
  3. 以修改后的配置运行产线推理服务：paddlex --serve --pipeline <配置文件路径> --port <端口号>。 关于 PaddleOCR 产线的更多说明，可以参考 通用 OCR 产线使用文档 以及 PaddleOCR 服务化部署文档。
  4. 在本地项目中填写 OCR 配置。
    1. 进入 docker 目录。
    2. 打开文件 .env ，将 OCR_TYPE 设置为 paddleocr，将 PADDLEOCR_OCR_API_URL 设置为上一步骤启动的通用 OCR 产线推理服务的 API URL，例如 http://localhost:8999/ocr 。
    3. 保存配置。
  5. 完成配置修改后，执行以下命令重启 Coze Studio 后端服务。 
    docker compose --profile '*' up -d --force-recreate --no-deps coze-server

向量化存储（VectorStore）

Coze Studio 知识库功能依赖向量化存储组件，目前支持以下两种组件：

  • milvus：开源的高性能向量数据库，专注于解决大规模向量相似度搜索（如图片、视频、文本的语义检索）问题。milvus 未内置 embedding 模型，需要另外添加本地部署的 embedding 模型。
  • vikingdb：火山引擎提供的新一代分布式向量数据库，专为超大规模向量数据管理与检索设计。vikingdb 内置多个可选的向量化模型，目前可选的 embedding 模型列表可参考VikingDB 模型列表，你也可以选择本地部署的 embedding 模型。

配置流程如下：

  1. 进入docker/目录，打开文件 .env ，找到 vectorstore 配置模块。 以下部分为 vectorstore 配置模块。

    # Settings for VectorStore
# VectorStore type: milvus / vikingdb
# If you want to use vikingdb, you need to set up the vikingdb configuration.
export VECTOR_STORE_TYPE="milvus"
# milvus vector store
export MILVUS_ADDR="localhost:19530"
# vikingdb vector store for Volcengine
export VIKING_DB_HOST=""
export VIKING_DB_REGION=""
export VIKING_DB_AK=""
export VIKING_DB_SK=""
export VIKING_DB_SCHEME=""
export VIKING_DB_MODEL_NAME=""  # if vikingdb model name is not set, you need to set Embedding settings

  2. 选择你需要的向量库类型，修改对应配置项。

    • milvus：填写以下配置
      • VECTOR_STORE_TYPE 设置为 milvus。
      • MILVUS_ADDR 设置为 localhost:19530。
    • vikingdb：开通火山引擎方舟平台的知识库模块，获取火山账号的密钥（AK、SK），并填写以下配置
      • VIKING_DB_HOST：方舟知识库的域名。详细说明可参考火山官方文档。
      • VIKING_DB_REGION：方舟知识库所在地域，华北：cn-beijing，华东：cn-shanghai，柔佛：ap-southeast-1。
      • VIKING_DB_AK：火山引擎账号 AK。获取方式可参考火山官方文档。
      • VIKING_DB_SK：火山引擎账号 SK。获取方式可参考火山官方文档。
      • VIKING_DB_SCHEME：http 或 https。
      • VIKING_DB_MODEL_NAME：可选的 embedding 模型列表可参考 VikingDB 模型列表。如需选用本地部署的 embedding 模型，此处留空，并填写 Embedding 模型部分的配置。详细说明可参考下文向量化模型（Embedding）。

  3. 保存文件。

  4. 执行以下命令重启服务。

    docker compose --profile '*' up -d --force-recreate --no-deps coze-server

向量化模型（Embedding）

Coze Studio 开源版支持自定义设置知识库向量化依赖的 Embedding 模型，使知识库的向量化环节效果更符合指定场景的业务需求。

  • 如果向量化存储模块使用 milvus，则必须参考本文档设置 Embedding 模型。
  • VikingDB 向量库自带 Embedding 功能，如果向量化存储模块使用 milvus，则可以自行选择使用预置的 VikingDB 模型或者使用 OpenAI 或其他模型。

Coze Studio 支持四种方式接入向量化模型：

接入方式 说明
openai OpenAPI 向量模型协议，兼容 OpenAPI 协议的模型均可以使用该 protocol。请注意：

* base_url 通常以 /v1结尾，不包含 /embeddings。
* OPENAI_EMBEDDING_REQUEST_DIMS 为请求 API 时传递的 dimensions，用于要求输出指定维度的向量。部分模型不支持该字段调用会报错，此时请置空该字段。
ark 火山方舟向量模型协议。
ollama ollama 向量模型协议。
http 专用协议，要求用户对部署的模型服务自行封装，需要同时输出稠密+稀疏向量，具体请参考源代码。

配置流程如下：

  1. 进入docker/目录，打开文件：.env ，找到 Embedding 配置模块。

  2. 选择向量化模型类型，并填写对应的配置参数。其中 BASE_URL 的填写可参考【模型配置】-【配置参考】小节 详细配置如下：

    # Settings for Embedding
# The Embedding model relied on by knowledge base vectorization does not need to be configured
# if the vector database comes with built-in Embedding functionality (such as VikingDB). Currently,
# Coze Studio supports four access methods: openai, ark, ollama, and custom http. Users can simply choose one of them when using
# embedding type: openai / ark / ollama / http
export EMBEDDING_TYPE="ark"
export EMBEDDING_MAX_BATCH_SIZE=100


# openai embedding
export OPENAI_EMBEDDING_BASE_URL=""       # (string, required) OpenAI embedding base_url
export OPENAI_EMBEDDING_MODEL=""          # (string, required) OpenAI embedding model
export OPENAI_EMBEDDING_API_KEY=""        # (string, required) OpenAI embedding api_key
export OPENAI_EMBEDDING_BY_AZURE=false    # (bool,   optional) OpenAI embedding by_azure
export OPENAI_EMBEDDING_API_VERSION=""    # (string, optional) OpenAI embedding azure api version
export OPENAI_EMBEDDING_DIMS=1024         # (int,    required) OpenAI embedding dimensions
export OPENAI_EMBEDDING_REQUEST_DIMS=1024 # (int,    optional) OpenAI embedding dimensions in requests, need to be empty if api doesn't support specifying dimensions.


# ark embedding
export ARK_EMBEDDING_MODEL=""    # (string, required) Ark embedding model
export ARK_EMBEDDING_API_KEY=""  # (string, required) Ark embedding api_key
export ARK_EMBEDDING_DIMS="2048" # (int,    required) Ark embedding dimensions
export ARK_EMBEDDING_BASE_URL="" # (string, required) Ark embedding base_url
export ARK_EMBEDDING_API_TYPE="" # (string, optional) Ark embedding api type, should be "text_api" / "multi_modal_api". Default "text_api".


# ollama embedding
export OLLAMA_EMBEDDING_BASE_URL="" # (string, required) Ollama embedding base_url
export OLLAMA_EMBEDDING_MODEL=""    # (string, required) Ollama embedding model
export OLLAMA_EMBEDDING_DIMS=""     # (int,    required) Ollama embedding dimensions


# http embedding
export HTTP_EMBEDDING_ADDR=""   # (string, required) http embedding address
export HTTP_EMBEDDING_DIMS=1024 # (string, required) http embedding dimensions

  3. 保存文件。

  4. 执行以下命令重启服务。

    docker compose --profile '*' up -d --force-recreate --no-deps coze-server

AI 生成模型（Model）

Coze Studio 知识库提供文本转 SQL（NL2SQL）、一句话生成 Query（Message to Query）、图像标注（Image Annotation）、workflow 大模型节点召回知识库等功能，这些功能统一依赖于 Coze Studio 预配置的 AI 生成模型。在 Coze Studio 开源版中使用这些功能前，你需要先配置这个AI 生成模型。

  • 此处配置的 AI 生成模型只在 NL2SQL、Message to Query、Image Annotation、Workflow knowledge recall 四个场景中生效。
  • 如果需要在不同场景中使用不同模型，你可以通过添加前缀来针对特定场景应用特定配置，例如图片标注场景需要配置视觉模型，其余场景不需要，则可以新增 export IA_BUILTIN_CM_OPENAI_MODEL="xxx" 来配置图片标注场景专用的视觉模型。

配置步骤如下：

  1. 进入docker/目录。

  2. 打开文件：.env ，找到 Model for knowledge 配置模块。修改以下配置：

    • 设置模型类型：通过参数 BUILTIN_CM_TYPE 设置 NL2SQL 等 AI 生成场景的模型。支持设置为 openai、ark、deepseek、ollama 或 qwen。
    • 设置模型鉴权等参数：不同的模型对应不同的参数配置，你可以在配置文件中找到各个模型的配置参数区域。例如 ark 模型应设置以下参数： 
      # Settings for Model
# Model for knowledge nl2sql, messages2query (rewrite), image annotation
# add prefix to assign specific model, downgrade to default config when prefix is not configured:
# 1. nl2sql:            NL2SQL_ (e.g. NL2SQL_BUILTIN_CM_TYPE)
# 2. messages2query:    M2Q_    (e.g. M2Q_BUILTIN_CM_TYPE)
# 3. image annotation:  IA_     (e.g. IA_BUILTIN_CM_TYPE)
# 4. workflow knowledge recall: WKR_ (e.g. WRK_BUILTIN_CM_TYPE)
# supported chat model type: openai / ark / deepseek / ollama / qwen
export BUILTIN_CM_TYPE="openai"
# type openai
export BUILTIN_CM_OPENAI_BASE_URL=""
export BUILTIN_CM_OPENAI_API_KEY=""
export BUILTIN_CM_OPENAI_BY_AZURE=true
export BUILTIN_CM_OPENAI_MODEL=""

# type ark
export BUILTIN_CM_ARK_API_KEY =""
export BUILTIN_CM_ARK_MODEL =""

# type deepseek
export BUILTIN_CM_DEEPSEEK_BASE_URL = ""
export BUILTIN_CM_DEEPSEEK_API_KEY = ""
export BUILTIN_CM_DEEPSEEK_MODEL = ""

# type ollama
export BUILTIN_CM_OLLAMA_BASE_URL = ""
export BUILTIN_CM_OLLAMA_MODEL = ""

# type qwen
export BUILTIN_CM_QWEN_BASE_URL = ""
export BUILTIN_CM_QWEN_API_KEY = ""
export BUILTIN_CM_QWEN_MODEL = ""

  3. 保存文件。

  4. 执行以下命令重启服务。

    docker compose --profile '*' up -d --force-recreate --no-deps coze-server

Workflow 代码运行沙箱（Sandbox)

沙箱功能提供了一个安全隔离的沙箱环境，供 Workflow 代码节点运行用户配置的 python 代码。 默认情况下，代码会在服务环境的 Python 虚拟环境 (venv) 中直接运行。如果你有隔离需求，可以通过修改下面的环境变量来配置：

  1. 进入docker/目录。
  2. 打开文件：.env ，找到CODE_RUNNER_TYPE配置项，将其修改为sandbox，并配置sandbox的依赖配置项，保存
# CODE_RUNNER_TYPE 支持 sandbox / local，默认为 local
export CODE_RUNNER_TYPE="sandbox"

# 注意：下面的配置仅在 CODE_RUNNER_TYPE=sandbox 时生效

export CODE_RUNNER_ALLOW_ENV=""   # 限制环境变量读取，用逗号分隔，例如: "PATH,USERNAME"
export CODE_RUNNER_ALLOW_READ=""  # 读权限，用逗号分隔，例如: "/tmp,./data"
export CODE_RUNNER_ALLOW_WRITE="" # 写权限，用逗号分隔，例如："/tmp,./data"
export CODE_RUNNER_ALLOW_RUN=""   # 运行权限，用逗号分隔，例如："python,git"

# 网络访问权限，用逗号分隔，例如："api.test.com,api.test.org:8080"
# 默认配置的 CDN 支持下载运行 pyodide 所需的包，如果删除的话沙箱可能无法正常运行。
export CODE_RUNNER_ALLOW_NET="cdn.jsdelivr.net"

export CODE_RUNNER_ALLOW_FFI=""        # 外部函数接口，用逗号分隔，例如："/usr/lib/libm.so"
export CODE_RUNNER_NODE_MODULES_DIR="" # deno modules 路径，默认使用项目路径，例如："/tmp/path/node_modules"
export CODE_RUNNER_TIMEOUT_SECONDS=""  # 代码执行超时时间，默认 60s，例如："2.56"
export CODE_RUNNER_MEMORY_LIMIT_MB=""  # 代码运行内存限制，默认 100MB，例如："256"
  1. 执行以下命令重启服务。
docker compose --profile '*' up -d --force-recreate --no-deps coze-server

Home

Clone this wiki locally