> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装

安装 VeADK 后，可以使用 Python 创建和运行智能体。首次使用建议安装 PyPI 已发布版本；需要验证未发布能力或修改 SDK 时，再使用源码安装

## 前置条件

* Python 3.10 至 3.13，以及对应环境中的 pip
* 调用模型时需要可用的模型和 API Key；安装软件包本身不需要模型凭证。火山引擎和 BytePlus 的配置见[快速开始](/productions/veadk/preview/zh/get-started/quickstart)

## 安装已发布版本

在项目目录中创建虚拟环境，避免与其他项目的依赖冲突：

```bash lines theme={null}
python -m venv .venv
```

激活该环境：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash lines theme={null}
    source .venv/bin/activate
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell lines theme={null}
    .venv\Scripts\Activate.ps1
    ```
  </Tab>
</Tabs>

从 [PyPI](https://pypi.org/project/veadk-python/) 安装最新已发布版本，并检查安装结果：

```bash lines theme={null}
python -m pip install --upgrade veadk-python
python -c "from importlib.metadata import version; print(version('veadk-python'))"
```

第二条命令输出当前 Python 环境中的 VeADK 版本号。本页的 Python 版本要求和可选依赖组按已发布的 1.1.13 核对；生产项目应固定经过验证的版本

<Note>
  Preview 还包含[更新日志](/productions/veadk/preview/zh/changelog)中标记为「未发布」的能力。使用这些能力前，查看对应页面的版本条件和源码安装说明，不能仅凭 Preview 中存在说明就认定 PyPI 版本已经支持
</Note>

## 可选依赖组

根据需要安装可选依赖组。例如，接入飞书、Cozeloop 或 LlamaIndex 时安装 `extensions`：

```bash lines theme={null}
python -m pip install --upgrade "veadk-python[extensions]"
```

固定主包版本时，可选依赖组也应使用相同版本，例如 `veadk-python[extensions]==1.1.13`

| 依赖组 | 包含的能力或依赖 |
| - | - |
| `github-cicd` | PyNaCl，用于 Studio 持续交付时加密 GitHub Actions Secret |
| `extensions` | 飞书渠道 SDK、飞书 OpenAPI SDK、Cozeloop、LlamaIndex 及其 OpenAI 兼容模型与嵌入适配、Redis / OpenSearch / Milvus 检索适配与客户端 |
| `codex` | OpenAI Codex SDK、Codex CLI 二进制文件、FastAPI 和 Uvicorn，用于 Codex 运行时 |
| `database` | Redis、PyMySQL、火山引擎 SDK 和 Mem0 存储依赖 |
| `eval` | DeepEval、Google ADK 评测依赖和 Prometheus 指标客户端 |
| `a2ui` | A2UI Agent SDK，用于生成 A2UI 界面内容 |
| `harness` | Headroom 集成依赖 |
| `harness-sidecar` | Harness Sidecar 受控运行时所需的 AgentKit Python SDK |
| `sandbox` | 自建沙箱示例所需的 Anthropic SDK、python-dotenv 和 httpx SOCKS 代理支持 |
| `dev` | pre-commit、pytest、pytest-asyncio、pytest-cov 和 pytest-xdist，用于开发与测试 |
| `pdf`、`speech`、`cli` | 兼容已有安装命令的空依赖组，不增加额外依赖；PDF 页面渲染依赖自 1.0.5 起随主包安装 |

## 安装 Preview 源码

需要 Git 和 [uv](https://docs.astral.sh/uv/)。克隆公开仓库，在仓库目录中创建独立环境并以可编辑模式安装：

```bash lines theme={null}
git clone https://github.com/volcengine/veadk-python.git
cd veadk-python
```

如果目标页面指定了提交或 tag，先执行 `git checkout <ref>` 切换到该版本，再创建环境并安装：

```bash lines theme={null}
uv venv --python 3.12
uv pip install -e .
```

需要可选依赖组时，将安装命令改为 `uv pip install -e ".[extensions]"`

使用前激活仓库中的 `.venv`，激活方式与上文相同，再执行版本检查命令。可编辑安装后，对仓库中 Python 源码的修改会作用于该环境

主线源码会继续变化。验证特定未发布能力时，使用对应页面指定的源码版本；运行第一个智能体见[快速开始](/productions/veadk/preview/zh/get-started/quickstart)