Skip to content

5. Basic component configuration

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

After deploying the open-source version of Coze Studio, if you need to use the image upload functionality or knowledge base-related functionality, you should refer to this document to configure the required basic components for these features. These components typically rely on third-party services such as Volcengine. When configuring components, you need to provide authentication settings for the third-party service, such as the account, token, and other authentication configurations.

Upload components

In multimodal chat scenarios, it is often necessary to upload images, files, and other information during the conversation. For example, sending an image message in the agent debugging area:

Image

This functionality is provided by the upload component. Coze Studio currently supports the following three types of upload components. You can choose any one to use as the upload component.

  • (default) minio: Images and files are automatically uploaded to the minio service on the local host and can be accessed via a specified port. However, the local host must be configured with a public domain name; otherwise, uploaded images and files will only have internal network access links and cannot be read or recognized by large models.
  • Volcengine TOS: Images and files are automatically uploaded to the specified Volcengine TOS, and a publicly accessible URL is generated. If you select TOS, you must first enable TOS and configure the Volcengine token in Coze Studio.
  • Volcengine ImageX: Images and files are automatically uploaded to the specified Volcengine ImageX, and a publicly accessible URL is generated. If you choose ImageX, you must first enable ImageX and configure the Volcengine token in Coze Studio.

The configuration methods for the upload component are as follows:

  1. Set the upload component type. Open the .env file in the docker directory. The value of the configuration item "FILE_UPLOAD_COMPONENT_TYPE" specifies the type of upload component.

    • storage (default): Uses the storage component configured by STORAGE_TYPE. STORAGE_TYPE defaults to minio, but can also be configured as tos.
    • imagex: Indicates the use of the Volcengine ImageX component.
    # 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. Add a secret key and other configurations for the upload component. Likewise, in the .env file in the docker directory, enter the following configuration based on the component type.

    Component types Configure the authentication method Example
    minio
    (Default)    		 1. In the docker/.env file of the Coze Studio project, set FILE_UPLOAD_COMPONENT_TYPE to storage.
    2. In the Storage component area, set STORAGE_TYPE to minio.
    3. In the MiniO area, simply keep the default configuration.

    If you choose to deploy Coze Studio on public clouds such as Volcengine, you must configure your cloud server in advance to allow access to ports 8888 and 8889.
    		Image
    tos 1. Enable the Volcengine TOS product.
    2. In the docker/.env file of the Coze studio project, FILE_UPLOAD_COMPONENT_TYPE is set to storage.
    3. In the Storage component area, set STORAGE_TYPE to tos.
    4. In the TOS area, enter the following parameters:
    * TOS_ACCESS_KEY: Volcengine access key AK. For information on how to obtain it, refer to Obtain a Volcengine API token.
    * TOS_SECRET_KEY: Volcengine secret key SK. To learn how to obtain it, refer to Obtain Volcengine API token.
    * TOS_ENDPOINT: The Endpoint of the TOS service. For information on how to obtain it, see Regions and access domain names.
    * TOS_REGION: The region where the TOS service is located. For information on how to obtain the region value, see Regions and access endpoints.
    Image
    imagex 1. Activate the Volcengine veImageX product and create the Asset Hosting service. You can refer to the Volcengine veImageX official documentation. Please note that when creating the Asset Hosting service, you need to provide a domain name. We recommend obtaining a publicly available domain name in advance.
    2. In the docker/.env file of the Coze studio project, FILE_UPLOAD_COMPONENT_TYPE is set to imagex.
    3. In the VolcEngine ImageX area, fill in the following parameters:
    * VE_IMAGEX_AK: Volcengine Access Key (AK). For information on how to obtain it, refer to Obtain a Volcengine API token.
    * VE_IMAGEX_SK: Volcengine secret key (SK). Refer to Obtain a Volcengine API token for how to obtain it.
    * VE_IMAGEX_SERVER_ID: The service ID displayed on the Service Management page of the Volcengine veImageX product.
    * VE_IMAGEX_DOMAIN: The domain name specified when creating the service.
    * VE_IMAGEX_TEMPLATE: The name of the template for image processing configuration.
    Image

  3. Run the following command to restart the service so that the above configuration takes effect.

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

Knowledge base-related components

Document Parser

Document parsing is a necessary preliminary step for information storage and serves as the starting point of the entire process. The document parser can extract core content, such as text and tables, from various types of documents including PDF and DOCX. After being processed by subsequent components, this content is ultimately stored in the knowledge base.

Coze Studio allows users to customize the document parser by modifying configurations. Currently, the supported types of document parsers are as follows:

  • Built-in Document Parser: Provides basic document parsing capabilities and supports a variety of file types, including PDF, TXT, Markdown, DOCX, CSV, XLSX, and JSON.
  • PaddleOCR Document Parser: For PDF files, it uses the PP-StructureV3 layout parsing solution provided by PaddleOCR, offering more advanced document parsing capabilities. It can extract text, tables, formulas, images, stamps, and other layout elements, while preserving the original reading order of the layout—making it especially suitable for scanned documents. For other file types, its functionality is currently the same as the built-in document parser.

If you want to use the built-in document parser, no configuration adjustments are needed.

If you want to use the PaddleOCR document parser, you can adjust the configuration according to the following steps:

  1. Please refer to the PaddleOCR installation documentation to install the PaddlePaddle framework and the PaddleOCR inference package. To achieve optimal accuracy, the default configuration of PP-StructureV3 requires relatively high computational resources. It is recommended to use a GPU with more than 16 GB of memory and install the GPU version of the PaddlePaddle framework. If you wish to use fewer computational resources, such as deploying the service on a CPU, you can refer to the following steps to adjust the production configuration.
  2. Run the following command to install the serving dependencies:
paddlex --install serving
  1. Run the following command to start the PP-StructureV3 pipeline inference service with the default configuration:
paddlex --serve --pipeline PP-StructureV3 --port <PORT_NUMBER>

If you want to adjust the pipeline configuration (for example, to use a lightweight model and reduce computational resources), you can follow these steps:

  1. Obtain the default pipeline configuration file by running: paddlex --get_pipeline_config PP-StructureV3.
  2. Modify the pipeline configuration file as needed. For example:
    • Disable unnecessary features, such as setting use_formula_recognition to False to turn off formula recognition.
    • Use lightweight models, such as replacing the OCR model with the mobile version or switching to a lighter formula recognition model like PP-FormulaNet-S.
  3. Run the pipeline inference service with the modified configuration:：paddlex --serve --pipeline <CONFIG_FILE_PATH> --port <PORT_NUMBER>.

For more details about the PaddleOCR pipeline, please refer to the PP-StructureV3 pipeline usage documentation and the PaddleOCR serving documentation.

  1. Fill in the document parser configuration in your local project.
    1. Navigate to the docker directory.
    2. Open the .env file, set PARSER_TYPE to paddleocr , and set PADDLEOCR_STRUCTURE_API_URL to the API URL of the PP-StructureV3 pipeline inference service started in the previous step, e.g. http://localhost:9999/layout-parsing.
    3. Save the configuration.

After completing the configuration changes, run the following command to restart the Coze Studio backend service.

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

Text recognition (OCR)

Coze Studio allows users to configure the underlying services that provide OCR capabilities. Currently, the following types of underlying OCR services are supported:

  • Volcengine OCR: A commercial OCR product provided by Volcengine.
  • PaddleOCR: An open-source leading OCR solution developed by Baidu PaddlePaddle, using the latest PP-OCRv5 model by default.

Volcengine OCR

If you want to use the Volcengine OCR solution, follow these configuration steps:

  1. Enable the Volcengine General Text Recognition product. You can complete the activation by following the on-page instructions. After the product is activated, the General Text Recognition product page displays the connection status as officially activated, as shown below:

  1. Obtain the AK and SK for your Volcengine account; these will be required in the next steps. You can refer to the volcengine official documentation for instructions on obtaining it.

  2. Enter the OCR configuration in the local project.

    1. Navigate to the docker directory.
    2. Open the .env file and modify the VE_OCR_AK and VE_OCR_SK configuration items.
      • VE_OCR_AK: Set to the AK obtained from the Volcengine account in Step 2.
      • VE_OCR_SK: Set to the Volcengine account SK obtained in Step 2.
    3. Save the configuration. 
      # 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 volcengine OCR.
# ocr_type: default type `ve`
export OCR_TYPE="ve"
# ve ocr
export VE_OCR_AK=""
export VE_OCR_SK=""

  3. Run the following commands to restart the service.

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

PaddleOCR

If you want to use the PaddleOCR solution, you can adjust the configuration according to the following steps:

  1. Please refer to the PaddleOCR installation documentation to install the PaddlePaddle framework and the PaddleOCR inference package. To achieve optimal accuracy, the default configuration of PP-OCRv5 requires relatively high computational resources. It is recommended to use a GPU with more than 8 GB of memory and install the GPU version of the PaddlePaddle framework. If you wish to use fewer computational resources, such as deploying the service on a CPU, you can refer to the following steps to adjust the production configuration.
  2. Run the following command to install the serving dependencies:
paddlex --install serving
  1. Run the following command to start the general OCR pipeline inference service with the default configuration:
paddlex --serve --pipeline OCR --port <PORT_NUMBER>

If you want to adjust the pipeline configuration (for example, to use a lightweight model and reduce computational resources), you can follow these steps:

  1. Obtain the default pipeline configuration file by running:
paddlex --get_pipeline_config OCR
  1. Modify the pipeline configuration file as needed. For example:
    • Use lightweight models, such as replacing the text detection model (SubModules.TextDetection.model_name) and the text recognition model (SubModules.TextRecognition.model_name) with PP-OCRv5_mobile_det and PP-OCRv5_mobile_rec, respectively.

For more details about the PaddleOCR pipeline, please refer to the general OCR pipeline usage documentation and the PaddleOCR serving documentation.

  1. Fill in the OCR configuration in your local project.
    1. Navigate to the docker directory.
    2. Open the .env file, set OCR_TYPE to paddleocr , and set PADDLEOCR_OCR_API_URL to the API URL of the general OCR pipeline inference service started in the previous step, e.g. http://localhost:8999/ocr.
    3. Save the configuration.

After completing the configuration changes, run the following command to restart the Coze Studio backend service.

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

Vector storage (VectorStore)

The knowledge base functionality in Coze Studio relies on vectorized storage components and currently supports the following two components:

  • milvus: An open-source, high-performance vector database focused on solving large-scale vector similarity search problems, such as semantic retrieval for images, videos, and text. Milvus does not include a built-in embedding model; you need to add a locally deployed embedding model separately.
  • vikingdb: A new-generation distributed vector database provided by Volcengine, specifically designed for managing and retrieving ultra-large-scale vector data. VikingDB includes several optional vectorization models. For the current list of available embedding models, see VikingDB model list. You can also choose to use a locally deployed embedding model.

The configuration process is as follows:

  1. Go to the docker/ directory, open the .env file, and locate the vectorstore configuration module. The following section is the vectorstore configuration module.

    # 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. Choose the type of vector database you need, and modify the corresponding configuration items.

    • Milvus: Enter the following configuration settings
      • Set VECTOR_STORE_TYPE to milvus.
      • Set MILVUS_ADDR to localhost:19530.
    • vikingdb: Enable the knowledge base module of the Volcengine Ark Platform, obtain the Volcengine account keys (AK, SK), and complete the following configuration.
      • VIKING_DB_HOST: The domain name of the Ark knowledge base. For more details, refer to the official volcengine documentation.
      • VIKING_DB_REGION: The region where the Ark knowledge base is located. North China: cn-beijing, East China: cn-shanghai, Johor: ap-southeast-1.
      • VIKING_DB_AK: Volcengine account AK. Refer to the official Volcengine documentation for how to obtain it.
      • VIKING_DB_SK: Volcengine account SK. For information on how to obtain it, refer to the Volcengine official documentation.
      • VIKING_DB_SCHEME: http or https.
      • VIKING_DB_MODEL_NAME: For a list of available embedding models, refer to the VikingDB model list. If you want to use a locally deployed embedding model, leave this field blank and complete the configuration in the embedding model section. For more details, refer to the vectorization model (Embedding) described below.

  3. Save a file.

  4. Run the following command to restart the service.

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

A vectorization model (embedding)

The open-source version of Coze Studio supports customizing the embedding model used for knowledge base vectorization, enabling the vectorization process to better meet the business requirements of specific scenarios.

  • If the vector storage module uses milvus, you must refer to this document to configure the Embedding model.
  • The VikingDB vector database comes with built-in embedding functionality. If the vector storage module uses milvus, you can choose to use the preset VikingDB model or use OpenAI or other models.

Coze Studio supports four methods to integrate vectorization models:

Access methods Note
openai The OpenAPI vector model protocol can be used by any model that is compatible with the OpenAPI protocol. Note:

* The base_url usually ends with /v1 and does not include /embeddings.
* OPENAI_EMBEDDING_REQUEST_DIMS is the dimensions parameter passed when making an API request, used to request output vectors of specified dimensions. Some models do not support this field, and using this field will result in an error. In this case, please leave this field empty.
ark Volcengine Ark vector model protocol.
ollama The Ollama vector model protocol.
http A custom protocol requires users to implement their own wrapper for the deployed model service, and to output both dense and sparse vectors simultaneously. For details, refer to the source code.

The configuration process is as follows:

  1. Go to the docker/ directory, open the .env file, and locate the Embedding configuration module.

  2. Select the vectorization model type and enter the corresponding configuration parameters. You can refer to the "Configuration reference" subsection under "Model configuration" for BASE_URL. The detailed configuration is as follows:

    # 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. Save a file.

  4. Run the following commands to restart the service.

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

AI generative model (Model)

The Coze Studio knowledge base provides features such as text-to-SQL (NL2SQL), one-sentence query generation (Message to Query), image annotation, a knowledge base for recalling large model nodes in workflows, and other features. All of these features rely on AI generative models preconfigured in Coze Studio. Before you can use these features in the open-source version of Coze Studio, you need to first configure this AI generation model.

  • The AI-generated model configured here is only effective in the following four scenarios: NL2SQL, Message to Query, Image Annotation, and Workflow Knowledge Recall.
  • If you need to use different models in different scenarios, you can apply specific configurations for each scenario by adding a prefix. For example, if the image annotation scenario requires a visual model while other scenarios do not, you can add export IA_BUILTIN_CM_OPENAI_MODEL="xxx" to configure a dedicated visual model for the image annotation scenario.

The configuration steps are as follows:

  1. Go to the docker/ directory.

  2. Open the file: .env, and find the Model for knowledge configuration module. Modify the following configuration:

    • Set model type: Set the model for AI-generated scenarios, such as NL2SQL, using the BUILTIN_CM_TYPE parameter. Can be set to openai, ark, deepseek, ollama, or qwen.
    • Set model authentication and other parameters: Different models have different parameter configurations; you can find the configuration parameter section for each model in the configuration file. For example, the Ark model should be configured with the following parameters: 
      # 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. Save the file.

  4. Run the following command to restart the service.

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

Workflow code execution sandbox (Sandbox)

The sandbox feature provides a secure, isolated sandbox environment for Workflow code nodes to run user-configured Python code. By default, the code runs directly in the Python virtual environment (venv) of the service environment. If you need isolation, you can configure it by modifying the following environment variables:

  1. Enter the docker/ directory.
  2. Open the file: .env, locate the CODE_RUNNER_TYPE configuration item, change its value to sandbox, configure the dependency settings for sandbox, and save.
# CODE_RUNNER_TYPE supports sandbox and local; the default is local
export CODE_RUNNER_TYPE="sandbox"

Note: The following configuration is effective only when CODE_RUNNER_TYPE=sandbox.

export CODE_RUNNER_ALLOW_ENV=""   Restrict environment variable reading

Separate multiple variables with commas, for example: "PATH,USERNAME"
export CODE_RUNNER_ALLOW_READ=""  Read permission, separated by commas, for example: "/tmp,./data"
export CODE_RUNNER_ALLOW_WRITE="" Write permission. Separate multiple entries with commas. For example: "/tmp,./data"
export CODE_RUNNER_ALLOW_RUN=""   Runtime permission, separated by commas, for example: "python,git"

Network access permissions
Separate multiple entries with commas. For example: "api.test.com,api.test.org:8080"
The default CDN configuration supports downloading the packages required to run pyodide. If the default CDN configuration is removed, the sandbox may not function properly.
export CODE_RUNNER_ALLOW_NET="cdn.jsdelivr.net"

export CODE_RUNNER_ALLOW_FFI=""        External function API
Separate multiple entries with commas, for example: "/usr/lib/libm.so"
export CODE_RUNNER_NODE_MODULES_DIR="" Deno modules path
By default, the project path is used. For example: "/tmp/path/node_modules"
export CODE_RUNNER_TIMEOUT_SECONDS=""  Code execution timeout (default: 60 seconds), for example: "2.56"
export CODE_RUNNER_MEMORY_LIMIT_MB=""  # Code execution memory limit (default: 100MB), for example: "256"
  1. Run the following command to restart the service.
docker compose --profile '*' up -d --force-recreate --no-deps coze-server

Home

Clone this wiki locally