---
title: "环境变量"
---

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

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

## 火山引擎账号

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

| 环境变量 | 释义 |
| :- | :- |
| `VOLCENGINE_ACCESS_KEY` | 火山引擎 Access Key |
| `VOLCENGINE_SECRET_KEY` | 火山引擎 Secret Key |

```yaml title="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_NAME` | Embedding 模型名称 |
| | `MODEL_EMBEDDING_DIM` | Embedding 维度 |
| | `MODEL_EMBEDDING_API_BASE` | 访问地址 |
| | `MODEL_EMBEDDING_API_KEY` | 访问密钥 |
| 评测模型 | `MODEL_JUDGE_NAME` | 模型名称 |
| | `MODEL_JUDGE_API_BASE` | 访问地址 |
| | `MODEL_JUDGE_API_KEY` | 访问密钥 |

## 内置工具

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

| 子类 | 环境变量 | 释义 |
| :- | :- | :- |
| VeSearch | `TOOL_VESEARCH_ENDPOINT` | 火山引擎搜索机器人 ID |
| | `TOOL_VESEARCH_API_KEY` | 火山引擎搜索服务密钥 |
| WebScraper | `TOOL_WEB_SCRAPER_ENDPOINT` | WebScraper 端点 |
| | `TOOL_WEB_SCRAPER_API_KEY` | WebScraper 密钥 |
| Lark | `TOOL_LARK_ENDPOINT` | Lark 应用 ID |
| | `TOOL_LARK_API_KEY` | Lark 应用密钥 |
| | `TOOL_LARK_TOKEN` | Lark 用户 token |
| Feishu Channel | `TOOL_FEISHU_CHANNEL_APP_ID` | 飞书机器人应用 ID |
| | `TOOL_FEISHU_CHANNEL_APP_SECRET` | 飞书机器人应用密钥 |
| | `TOOL_FEISHU_CHANNEL_TRANSPORT` | 传输模式，默认 `ws` |
| LAS | `TOOL_LAS_URL` | LAS SSE 服务地址（含 token） |
| | `TOOL_LAS_DATASET_ID` | LAS 数据集 ID |
| VOD | `TOOL_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_`，按存储类型分组。记忆与知识库按所选后端读取对应配置。

| 子类 | 环境变量 | 释义 |
| :- | :- | :- |
| OpenSearch | `DATABASE_OPENSEARCH_HOST` | 主机地址（不含协议头） |
| | `DATABASE_OPENSEARCH_PORT` | 端口，默认 9200 |
| | `DATABASE_OPENSEARCH_USERNAME` | 用户名 |
| | `DATABASE_OPENSEARCH_PASSWORD` | 密码 |
| | `DATABASE_OPENSEARCH_CERT_PATH` | 证书路径（生产环境建议配置） |
| | `DATABASE_OPENSEARCH_USE_SSL` | 是否启用 SSL，默认 True |
| MySQL | `DATABASE_MYSQL_HOST` | 主机地址 |
| | `DATABASE_MYSQL_USER` | 用户名 |
| | `DATABASE_MYSQL_PASSWORD` | 密码 |
| | `DATABASE_MYSQL_DATABASE` | 数据库名 |
| | `DATABASE_MYSQL_CHARSET` | 字符集，默认 utf8 |
| Redis | `DATABASE_REDIS_HOST` | 主机地址 |
| | `DATABASE_REDIS_PORT` | 端口，默认 6379 |
| | `DATABASE_REDIS_PASSWORD` | 密码 |
| | `DATABASE_REDIS_DB` | 数据库编号，默认 0 |
| Milvus | `DATABASE_MILVUS_URI` | Milvus 地址；可为本地 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_PROJECT` | 项目名称 |
| | `DATABASE_VIKING_REGION` | 区域 |
| TOS | `DATABASE_TOS_ENDPOINT` | 访问端点 |
| | `DATABASE_TOS_REGION` | 区域 |
| | `DATABASE_TOS_BUCKET` | 桶名称 |
| OpenViking | `DATABASE_OPENVIKING_URL` | OpenViking HTTP 服务地址 |
| | `DATABASE_OPENVIKING_API_KEY` | OpenViking service owner API Key |
| | `DATABASE_OPENVIKING_ACCOUNT` | 多租户或 trusted gateway 场景使用（可选） |
| | `DATABASE_OPENVIKING_USER` | 多租户或 trusted gateway 场景使用（可选） |
| | `DATABASE_OPENVIKING_ACTOR_PEER_ID` | 调用方 agent 或 peer 标识（可选） |
| | `DATABASE_OPENVIKING_TARGET_URI` | 知识库资源目录，默认 `viking://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` |

```yaml title="config.yaml"
database:
  milvus:
    uri: ./milvus.db
    # token:
    # user:
    # password:
    # db_name: default
    # overwrite: false
    # timeout: 5.0
    # output_fields: text,metadata
```

```yaml title="config.yaml"
database:
  openviking:
    url: http://127.0.0.1:1933
    api_key: your-openviking-api-key
    # Optional for KnowledgeBase(backend="openviking"):
    # target_uri: viking://resources/my_app/
    # wait: true
    # import_timeout: 300
    # hydrate_results: true
    # read_limit: 200
    # score_threshold: 0.3
    # use_context_search: false
```

## 可观测

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

| 子类 | 环境变量 | 释义 |
| :- | :- | :- |
| APMPlus | `OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT` | 上报地址 |
| | `OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY` | 鉴权密钥 |
| | `OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME` | 服务名称 |
| CozeLoop | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT` | 上报地址 |
| | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY` | 鉴权密钥 |
| | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME` | 服务空间 ID |
| TLS | `OBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT` | 上报地址 |
| | `OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME` | topic_id |
| | `OBSERVABILITY_OPENTELEMETRY_TLS_REGION` | 区域 |
| Prometheus | `OBSERVABILITY_PROMETHEUS_PUSHGATEWAY_URL` | Pushgateway 地址 |
| | `OBSERVABILITY_PROMETHEUS_USERNAME` | 用户名 |
| | `OBSERVABILITY_PROMETHEUS_PASSWORD` | 密码 |

## 其他

| 环境变量 | 释义 |
| :- | :- |
| `PROMPT_PILOT_API_KEY` | Prompt Pilot 产品密钥 |
| `VEIDENTITY_REGION` | 身份认证服务区域，默认 cn-beijing |
| `VEIDENTITY_ENDPOINT` | 身份认证服务端点（可选，不填自动生成） |

```yaml title="config.yaml"
veidentity:
  region: cn-beijing
  endpoint:  # 可选，不提供时自动生成
```
