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