本教程专为 **零基础用户** 设计，无需安装任何编程环境（如 Python），直接使用操作系统内置工具即可体验方舟大模型服务。 ## 1. 准备工作在开始之前，请确保您已经完成以下准备： 1. **注册账号** ：确保您拥有火山引擎账号并已 [登录](https://console.volcengine.com/)。 2. **获取 API Key** ： * 访问 [API Key 管理页面](https://console.volcengine.com/ark/region:ark+cn-beijing/apikey)。 * 点击“创建 API Key”，并复制保存您的 Key。

注意

请妥善保管您的 API Key，不要泄露给他人。

当前脚本兼容历史 UUID 格式以及新格式 ark-- 的 Key。

3. **开通模型（可选）** ：所有新用户可使用免费额度体验模型服务。如额度使用完毕需要 [开通模型](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement)，以继续使用方舟模型服务。

注意

开通 Seedance 2.0 模型，需要保证账户余额超过 200元或者购买资源包，详细请参见Doubao Seedance 2.0 系列教程。

4. 下载并解压文件：点击下载下方附件，将其解压到您的本地目录（如桌面或"下载"文件夹）。 ark_quickstart_package.zip ## 2. 一键体验模型服务（零门槛）打开我们为您准备的文件。请根据您的操作系统选择对应的操作。 ### Windows 用户 **适用系统** ：Windows 7 SP1 及以上（推荐 Windows 10/11） 1. 找到项目文件夹中的 `scripts/zero_dependency/windows` 目录。 2. 双击运行 **`run_windows.bat`** 文件。 > 提示：如果这是您第一次运行，可能会弹出权限询问窗口，请输入 `Y` 或允许运行。 3. 脚本会自动启动 PowerShell 环境。 4. 根据提示输入您的 **API Key** 并回车。 5. 稍等片刻，您将看到 AI 的回复内容。 ### macOS 用户 **适用系统** ：macOS 10.15及以上版本 1. 找到项目文件夹中的 `scripts/zero_dependency/mac` 目录。 2. 双击运行 **`run_mac.command`** 文件。 > 提示：如果系统提示“无法打开，因为它来自未验证的开发者” > 1. 按住 `Control` 键点击文件，选择“打开”，然后在弹出的对话框中再次点击“打开”。 > 2. 如果还是无法打开，直接在终端窗口运行脚本。可以打开终端（terminal），将 quickstart.sh 拖入窗口，回车运行。 3. 终端窗口会自动打开。 4. 根据提示输入您的 **API Key** 并回车。 5. 等待片刻，您将看到 AI 的回复内容。 ### 运行说明当您看到“调用成功”时，说明您已经完成了第一次 API 调用。脚本自动完成了以下步骤： 1. **构造请求** ：按照方舟平台的规范，打包了一段问候语：“你好！请用一句话介绍一下你自己。” 2. **发送请求** ：使用系统自带的网络工具（Windows 的 PowerShell 或 Mac 的 Curl）向方舟服务器发送消息。 3. **解析回复** ：自动处理服务器返回的数据，并提取出 AI 生成的文本展示给您。 ## 3. 一键搭建开发环境如果您已经成功体验了 API 调用，并希望开始真正的 Python 编程开发，但又不想被复杂的环境配置（Python 版本、pip、虚拟环境）所困扰，请尝试我们的 **自动化环境构建工具** 。我们将使用轻量、快速的现代化 Python 包管理器 `uv`（无需预安装Python即可使用），为您在项目内部自动下载并配置一个隔离的、纯净的、标准的 Python 开发环境，完全不会干扰您系统中已有的Python配置。 ### Windows 用户 1. 进入 `scripts/init_dev_env` 目录。 2. 双击运行 **`setup_windows.bat`** 。 3. 脚本会自动执行以下操作： * 下载 `uv` 工具。 * 自动下载 Python 3.12（如果不干扰您的系统 Python）。 * 创建虚拟环境 `.venv`。 * 安装方舟 SDK。 4. 完成后，在项目根目录会生成一个 `run_demo.bat`。 5. 双击 `run_demo.bat`，即可运行标准的 Python SDK 示例代码 (`python/``demo_standard.py`)。 6. 如果您希望按需生成 Python 示例脚本，可运行： ```Bash .venv/bin/python python/gen_example.py ``` 生成器支持多选示例类型、修改默认 Model ID，并可在缺少 `ARK_API_KEY` 时提示输入并选择写入项目根目录 `.env`。 ### macOS 用户 1. 打开终端，进入 `scripts/init_dev_env` 目录。 2. 运行构建脚本： ```Bash ./setup_mac.sh ``` 3. 脚本会自动配置好所有环境。 4. 完成后，在项目根目录会生成一个 `run_demo.sh`。 5. 运行 `./run_demo.sh` 即可体验标准开发流程。 6. 如果您希望按需生成 Python 示例脚本，可运行： ```Bash .venv/bin/python python/gen_example.py ``` 生成器支持多选示例类型、修改默认 Model ID，并可在缺少 `ARK_API_KEY` 时提示输入并选择写入项目根目录 `.env`。 ### 运行说明当您运行 `setup_windows.bat` 或 `setup_mac.sh` 后，您的项目文件夹中多了一个 `.venv` 文件夹。这是一个 **虚拟环境 (Virtual Environment)** 。它包含了 Python 解释器和方舟 SDK。 * **优势** ：无论您系统里安装了何种 Python 版本，该目录下的环境始终是纯净、稳定、可用的。 * **后续建议** ：您可以下载 [TRAE](https://www.trae.ai/) 编程工具，打开本项目文件夹，自动识别到该虚拟环境，您即可像专业工程师一样开始编写代码。

说明

推荐安装方舟文档 MCP，结合支持 MCP 的 Agent 或代码开发工具，可智能完成方舟代码开发与调试。

主流编程工具支持一键安装，OpenClaw 等智能体一句话即可安装，详见方舟文档 MCP。

## 4. 常见问题 **Q: 双击** **`run_windows.bat`** **后窗口一闪而过怎么办？** A: 请尝试右键点击 `run_windows.bat`，选择“以管理员身份运行”。或者先打开 CMD 命令行，拖入 `run_windows.bat` 文件运行，查看具体报错信息。 **Q: Mac 提示“Permission denied”？** A: 请打开终端，输入 `chmod +x`（注意最后有个空格），然后将 `run_mac.command` 文件拖入终端，按回车。这会赋予文件运行权限。 **Q: 报错“API Key 无效”？** A: 请检查您输入的 Key 是否完整，是否包含多余的空格。建议直接从控制台复制粘贴。 ## 5. 下一步您已经成功迈出了第一步！接下来，您可以： * **继续体验更多能力** ：重新运行脚本，在能力菜单中切换到图片生成、视频生成、多模态向量化或工具调用。 * **修改 Prompt** ：脚本运行时会直接展示默认 Prompt，您无需编辑源码文件即可替换成自己的输入。 * **配置环境变量** ：建议先配置 `ARK_API_KEY`，这样后续运行脚本时无需重复输入密钥。 * **学习更多** ：查看标准版 [快速入门](https://www.volcengine.com/docs/82379/1399008) 查看更多示例代码和进阶用法。 * **浏览模型** ：访问 [模型广场](https://console.volcengine.com/ark/region:ark+cn-beijing/model) 查看更多可用的强大模型。

火山方舟