VolcengineVolcengine ADK
配置

环境变量

环境变量是最主要的配置方式，提供密钥、连接信息与服务地址。变量名按领域前缀分组：火山引擎账号、模型、内置工具、数据库、可观测各成一类。每个环境变量都能在 config.yaml 中以对应层级结构表达，两者等价。

密钥统一通过环境变量或 config.yaml 提供。下表按领域列出常用变量，仅需配置实际用到的能力对应项。

火山引擎账号

统一前缀 VOLCENGINE_，用于访问火山引擎各类云服务。

环境变量释义
VOLCENGINE_ACCESS_KEY火山引擎 Access Key
VOLCENGINE_SECRET_KEY火山引擎 Secret Key
config.yaml
volcengine:
  access_key:
  secret_key:

模型

统一前缀 MODEL_，区分推理、向量化（embedding）、评测三类模型。

子类环境变量释义
推理模型MODEL_AGENT_NAME模型名称
MODEL_AGENT_PROVIDER符合 LiteLLM 规范的模型提供商
MODEL_AGENT_API_BASE访问地址
MODEL_AGENT_API_KEY访问密钥
向量化模型MODEL_EMBEDDING_NAMEEmbedding 模型名称
MODEL_EMBEDDING_DIMEmbedding 维度
MODEL_EMBEDDING_API_BASE访问地址
MODEL_EMBEDDING_API_KEY访问密钥
评测模型MODEL_JUDGE_NAME模型名称
MODEL_JUDGE_API_BASE访问地址
MODEL_JUDGE_API_KEY访问密钥

内置工具

统一前缀 TOOL_，仅在使用对应工具时配置。

子类环境变量释义
VeSearchTOOL_VESEARCH_ENDPOINT火山引擎搜索机器人 ID
TOOL_VESEARCH_API_KEY火山引擎搜索服务密钥
WebScraperTOOL_WEB_SCRAPER_ENDPOINTWebScraper 端点
TOOL_WEB_SCRAPER_API_KEYWebScraper 密钥
LarkTOOL_LARK_ENDPOINTLark 应用 ID
TOOL_LARK_API_KEYLark 应用密钥
TOOL_LARK_TOKENLark 用户 token
Feishu ChannelTOOL_FEISHU_CHANNEL_APP_ID飞书机器人应用 ID
TOOL_FEISHU_CHANNEL_APP_SECRET飞书机器人应用密钥
TOOL_FEISHU_CHANNEL_TRANSPORT传输模式，默认 ws
LASTOOL_LAS_URLLAS SSE 服务地址（含 token）
TOOL_LAS_DATASET_IDLAS 数据集 ID
VODTOOL_VOD_GROUPS视频编辑能力组
TOOL_VOD_TIMEOUT连接超时时长

Harness Extension

统一前缀 HARNESS_，用于给 HarnessApp Runtime 或 Runner 挂载可选的 Harness 插件能力。Harness Extension 随 VeADK 安装；只有当选择 headroom 压缩 provider 时，才需要安装 veadk-python[harness] 额外依赖。

环境变量释义
HARNESS_ENHANCE_ENABLED是否启用 Harness 插件，支持 true / false。
HARNESS_ENHANCE_COMPONENTS启用的组件，逗号分隔；常用值为 invocation_context,compactor,response_verification。
HARNESS_PROFILE插件运行 profile，用于区分运行策略；默认 default。
HARNESS_COMPRESSION_PROVIDER工具结果压缩 provider，默认 builtin；可选 headroom。
HARNESS_MAX_CONTEXT_CHARS上下文压缩阈值，默认 24000。
HARNESS_MAX_TOOL_RESULT_CHARS单个工具结果压缩阈值，默认 4000。
HARNESS_VERIFIER_MODE最终回答校验模式，observe 或 block，默认 observe。
HARNESS_STORE_PATH可选 JSONL 事件存储路径；不设置时使用内存存储。

harness_enhance 配置块会在 HarnessApp Runtime 部署时映射为这些环境变量。推荐开发者优先通过 harness.yaml 或 veadk agentkit invoke 参数启用，环境变量适合平台集成和镜像运行时。

数据库

统一前缀 DATABASE_，按存储类型分组。记忆与知识库按所选后端读取对应配置。

子类环境变量释义
OpenSearchDATABASE_OPENSEARCH_HOST主机地址（不含协议头）
DATABASE_OPENSEARCH_PORT端口，默认 9200
DATABASE_OPENSEARCH_USERNAME用户名
DATABASE_OPENSEARCH_PASSWORD密码
DATABASE_OPENSEARCH_CERT_PATH证书路径（生产环境建议配置）
DATABASE_OPENSEARCH_USE_SSL是否启用 SSL，默认 True
MySQLDATABASE_MYSQL_HOST主机地址
DATABASE_MYSQL_USER用户名
DATABASE_MYSQL_PASSWORD密码
DATABASE_MYSQL_DATABASE数据库名
DATABASE_MYSQL_CHARSET字符集，默认 utf8
RedisDATABASE_REDIS_HOST主机地址
DATABASE_REDIS_PORT端口，默认 6379
DATABASE_REDIS_PASSWORD密码
DATABASE_REDIS_DB数据库编号，默认 0
MilvusDATABASE_MILVUS_URIMilvus 地址；可为本地 Milvus Lite 文件路径或远程 URI
DATABASE_MILVUS_TOKEN鉴权 token；优先级高于 user/password（可选）
DATABASE_MILVUS_USER用户名（可选）
DATABASE_MILVUS_PASSWORD密码（可选）
DATABASE_MILVUS_DB_NAME数据库名，默认 default
DATABASE_MILVUS_OVERWRITE是否覆盖 collection，默认 false
DATABASE_MILVUS_TIMEOUT连接/请求超时时间（可选）
DATABASE_MILVUS_OUTPUT_FIELDS检索输出字段，逗号分隔（可选）
VikingDB 知识库DATABASE_VIKING_API_KEYAPI Key，用于搜索已有知识库；管理操作仍需 AK/SK/IAM
VikingDBDATABASE_VIKING_PROJECT项目名称
DATABASE_VIKING_REGION区域
VikingDB 记忆库DATABASE_VIKINGMEM_API_KEYAPI Key，用于访问已有记忆 collection；管理操作仍需 AK/SK/IAM
DATABASE_VIKINGMEM_PROJECT项目名称，默认 default
DATABASE_VIKINGMEM_MEMORY_TYPE记忆类型，逗号分隔
TOSDATABASE_TOS_ENDPOINT访问端点
DATABASE_TOS_REGION区域
DATABASE_TOS_BUCKET桶名称
OpenVikingDATABASE_OPENVIKING_URLOpenViking HTTP 服务地址
DATABASE_OPENVIKING_API_KEYOpenViking service owner API Key
DATABASE_OPENVIKING_USER_IDOpenViking owner/context 标识，默认 default；对应 backend_config["openviking_user_id"]，未配置 target_uri 时用于知识库目录，也用于长期记忆 owner/context
DATABASE_OPENVIKING_MEMORY_POLICY长期记忆 memory_policy JSON；未配置时使用默认 policy
DATABASE_OPENVIKING_ACCOUNT多租户或 trusted gateway 场景使用（可选）
DATABASE_OPENVIKING_USER多租户或 trusted gateway 场景使用（可选）
DATABASE_OPENVIKING_ACTOR_PEER_ID调用方 agent 或 peer 标识（可选）
DATABASE_OPENVIKING_TARGET_URI知识库资源目录；未配置时使用 viking://user/{openviking_user_id or default}/resources/{index}/
DATABASE_OPENVIKING_WAIT导入资源时是否等待解析与索引，默认 true
DATABASE_OPENVIKING_IMPORT_TIMEOUT导入等待超时时间，单位秒，默认 300
DATABASE_OPENVIKING_HYDRATE_RESULTS搜索命中后是否读取正文或概览，默认 true
DATABASE_OPENVIKING_READ_LIMIT读取文件正文的最大行数，默认 200
DATABASE_OPENVIKING_SCORE_THRESHOLD检索最低分阈值（可选）
DATABASE_OPENVIKING_USE_CONTEXT_SEARCH是否使用上下文增强搜索，默认 false
config.yaml
database:
  milvus:
    uri: ./milvus.db
    # token:
    # user:
    # password:
    # db_name: default
    # overwrite: false
    # timeout: 5.0
    # output_fields: text,metadata
config.yaml
database:
  openviking:
    url: http://127.0.0.1:1933
    api_key: your-openviking-api-key
    # user_id: default
    # memory_policy: '{"self":{"enabled":false},"peer":{"enabled":true},"memory_types":["entities","events","preferences"]}'
    # Optional for KnowledgeBase(backend="openviking"):
    # target_uri: viking://user/default/resources/my_app/
    # wait: true
    # import_timeout: 300
    # hydrate_results: true
    # read_limit: 200
    # score_threshold: 0.3
    # use_context_search: false

KnowledgeBase(backend="openviking") 会优先使用显式配置的 target_uri；未配置时使用 viking://user/{openviking_user_id or default}/resources/{index}/，其中 openviking_user_id 来自 backend_config["openviking_user_id"] 或 DATABASE_OPENVIKING_USER_ID。如果未传 backend_config，index 来自 KnowledgeBase(index=...) 或 app_name；如果传了 backend_config，请在该字典内提供 index。LongTermMemory(backend="openviking") 的 memory_policy 未配置时保持 VeADK 默认 policy；如需覆盖，请传入合法 JSON。

可观测

统一前缀 OBSERVABILITY_，配置追踪与指标的上报目标。

子类环境变量释义
APMPlusOBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT上报地址
OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY鉴权密钥
OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME服务名称
CozeLoopOBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT上报地址
OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY鉴权密钥
OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME服务空间 ID
TLSOBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT上报地址
OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAMEtopic_id
OBSERVABILITY_OPENTELEMETRY_TLS_REGION区域
PrometheusOBSERVABILITY_PROMETHEUS_PUSHGATEWAY_URLPushgateway 地址
OBSERVABILITY_PROMETHEUS_USERNAME用户名
OBSERVABILITY_PROMETHEUS_PASSWORD密码

其他

环境变量释义
PROMPT_PILOT_API_KEYPrompt Pilot 产品密钥
VEIDENTITY_REGION身份认证服务区域，默认 cn-beijing
VEIDENTITY_ENDPOINT身份认证服务端点（可选，不填自动生成）
config.yaml
veidentity:
  region: cn-beijing
  endpoint:  # 可选，不提供时自动生成

本页导航

火山引擎账号模型内置工具Harness Extension数据库可观测其他