火山方舟
火山方舟
资源
请输入
- 文档首页
火山方舟实践教程快速入门(新手版)
复制全文
下载 pdf快速入门(新手版)
文档反馈
问问助手本教程专为零基础用户设计，无需安装任何编程环境（如 Python），直接使用操作系统内置工具即可体验方舟大模型服务。
1. 准备工作
在开始之前，请确保您已经完成以下准备：
- 注册账号：确保您拥有火山引擎账号并已 登录。
- 获取 API Key：
- 访问 API Key 管理页面。
- 点击“创建 API Key”，并复制保存您的 Key。
注意
请妥善保管您的 API Key，不要泄露给他人。
当前脚本兼容历史 UUID 格式以及新格式 ark-<uuid>-<suffix> 的 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 示例脚本，可运行：
-
- Windows 用户请运行：
-
- 生成器支持多选示例类型、修改默认 Model ID，并可在缺少 ARK_API_KEY 时提示输入并选择写入项目根目录 .env。
macOS 用户
- 打开终端，进入 scripts/init_dev_env 目录。
- 运行构建脚本：
- 脚本会自动配置好所有环境。
- 完成后，在项目根目录会生成一个 run_demo.sh。
- 运行 ./run_demo.sh 即可体验标准开发流程。
- 如果您希望按需生成 Python 示例脚本，可运行：
-
- 生成器支持多选示例类型、修改默认 Model ID，并可在缺少 ARK_API_KEY 时提示输入并选择写入项目根目录 .env。
运行说明
当您运行 setup_windows.bat 或 setup_mac.sh 后，您的项目文件夹中多了一个 .venv 文件夹。
这是一个虚拟环境 (Virtual Environment)。它包含了 Python 解释器和方舟 SDK。
- 优势：无论您系统里安装了何种 Python 版本，该目录下的环境始终是纯净、稳定、可用的。
- 后续建议：您可以下载 TRAE 编程工具，打开本项目文件夹，自动识别到该虚拟环境，您即可像专业工程师一样开始编写代码。
说明
推荐安装方舟文档 MCP，结合支持 MCP 的 Agent 或代码开发工具，可智能完成方舟代码开发与调试。
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，这样后续运行脚本时无需重复输入密钥。
- 学习更多：查看标准版 快速入门 查看更多示例代码和进阶用法。
- 浏览模型：访问 模型广场 查看更多可用的强大模型。
最近更新时间：2026.09.11 15:16:14
这个页面对您有帮助吗？
有用
有用
无用
无用