快速入门-调用模型服务--火山方舟大模型服务平台-火山引擎

文档中心

立即注册

导航

快速入门-调用模型服务

最近更新时间：2025.04.27 15:36:05首次发布时间：2024.12.16 20:50:13

本文帮助您了解并按照步骤完成 API 调用模型，包括如何配置环境，使用 SDK 调用模型服务，便于您了解如何通过代码使用模型能力，进而集成到您的工作或者应用中。

快速入口，供您快速跳转到需要的内容：

直接体验模型能力，访问模型广场。
有模型调用经验，查看对话(Chat)-文本 API或者模型教程文本生成。
已有模型调用业务，迁移到 Doubao 大模型，可参考兼容OpenAI API。

简介

通过代码调用模型服务，可以分为以下几步：

1.获取并配置 API Key

获取 API Key

打开并登录方舟控制台-API Key 管理。
单击创建 API Key 按钮。
在弹出框的名称文本框中确认/更改 API Key 名称，单击创建。

说明

请妥善保存好API Key，强烈建议您不要将其直接写入到调用模型的代码中。
Access Key鉴权方式，请参见Access Key 签名鉴权。

配置 API Key 到环境变量

macOS | Linux | Windows

macOS

临时环境变量

永久环境变量

您希望仅在当前会话中使用 API Key 环境变量，可以添加临时环境变量。

打开终端使用以下命令来设置环境变量，将<ARK_API_KEY>替换为您的方舟 API Key。

export ARK_API_KEY="<ARK_API_KEY>"

执行以下命令，验证该环境变量是否生效。

echo $ARK_API_KEY

您希望 API Key 环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

打开在终端，使用以下命令，查看默认 Shell 类型。

echo $SHELL

/bin/zsh：默认的 Shell 类型是 Zsh（ Z shell）。
/bin/bash：默认的 Shell 类型是 Bash。

Zsh

打开终端，使用以下命令来将环境变量设置追加到 ~/.zshrc 中。将<ARK_API_KEY>替换为您的方舟 API Key。
```
echo "export ARK_API_KEY='<ARK_API_KEY>'" >> ~/.zshrc
```
使用以下命令使更改生效。
```
source ~/.zshrc
```
验证环境变量是否设置成功，在新的终端窗口，输入以下命令，如果返回您的 API Key，则表示设置成功。
```
echo $ARK_API_KEY
```

Bash

返回的是/bin/bash。

打开终端使用以下命令来将环境变量设置追加到 ~/.bash_profile 中。将<ARK_API_KEY>替换为您的方舟 API Key。
```
echo "export ARK_API_KEY='<ARK_API_KEY>'" >> ~/.bash_profile
```
使用以下命令使更改生效。
```
source ~/.bash_profile
```
验证环境变量是否设置成功，在新的终端窗口，输入以下命令，如果返回您的 API Key，则表示设置成功。
```
echo $ARK_API_KEY
```

Linux

设置临时环境变量

设置永久环境变量

如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。

打开终端使用以下命令来设置环境变量，将<ARK_API_KEY>替换为您的方舟 API Key。

export ARK_API_KEY="<ARK_API_KEY>"

执行以下命令，验证该环境变量是否生效。

echo $ARK_API_KEY

如果您希望 API Key 环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

打开终端使用以下命令来将环境变量设置追加到 ~/.bashrc 中。将<ARK_API_KEY>替换为您的方舟 API Key。
```
echo "export ARK_API_KEY='<ARK_API_KEY>'" >> ~/.bashrc
```
使用以下命令使更改生效。
```
source ~/.bashrc
```
验证环境变量是否设置成功，在新的终端窗口，输入以下命令，如果返回您的 API Key，则表示设置成功。
```
echo $ARK_API_KEY
```

Windows

设置临时环境变量

设置永久环境变量

如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。

在CMD中

打开 CMD（命令提示符）。
输入以下命令来设置环境变量，将<ARK_API_KEY>替换为您的实际 API Key：
```
set ARK_API_KEY=<ARK_API_KEY>
```
验证环境变量是否设置成功，输入以下命令，如果返回您的 API Key，则表示设置成功。
```
echo %ARK_API_KEY%
```

在PowerShell中

打开 PowerShell 。
输入以下命令来设置环境变量，将<ARK_API_KEY>替换为您的实际 API Key：
```
$env:ARK_API_KEY = "<ARK_API_KEY>"
```
验证环境变量是否设置成功，输入以下命令，如果返回您的 API Key，则表示设置成功。
```
$env:ARK_API_KEY
```

如果您希望 API Key 环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

在 CMD 中

您可以使用setx命令为当前用户设置永久性环境变量。

打开 CMD ，输入以下命令，其中将<ARK_API_KEY>替换为您的方舟 API Key。
```
setx ARK_API_KEY "<ARK_API_KEY>"
```
验证环境变量是否设置成功，在新打开 CMD 窗口中，输入以下命令，如果返回您的 API Key，则表示设置成功。
```
echo %ARK_API_KEY%
```

在 PowerShell 中

您可以使用以下命令为当前用户设置永久性环境变量。

打开 PowerShell ，输入以下命令，其中将<ARK_API_KEY>替换为您的方舟 API Key。

[Environment]::SetEnvironmentVariable("ARK_API_KEY", "<ARK_API_KEY>", [EnvironmentVariableTarget]::User)

验证环境变量是否设置成功，在新打开PowerShell窗口中，输入以下命令，如果返回您的 API Key，则表示设置成功。
```
$env:ARK_API_KEY
```

2.获取 Model ID

通过 Model ID的方式快速调用模型。

通过模型列表选择模型并获取所需模型的 ID（Model ID）。
访问开通管理页面开通对应模型服务。

说明

您也可通过Endpoint ID来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力，具体可参考获取 Endpoint ID。

3.配置环境并发起调用

Curl |Python | Go | Java
您可挑选任意一种语言选择调用模型推理服务的语言。

Curl

您可以通过 HTTP 方式直接调用方舟模型服务。
在终端窗口中，拷贝下面命令，并替换<Model>为您的推理接入点 ID模型的Model ID。稍等您可以在终端窗口中看到模型调用的返回结果。这样您就完成了您的首次方舟平台模型服务调用。

curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "<Model>",
    "messages": [
        {
            "role": "user",
            "content": "你好"
        }
    ]
  }'

如果返回错误码 {"error":{"code":"AuthenticationError","message":"The API key or AK/SK in the request is missing or invalid. requestId: 0217***，说明API Key中没有被正确设置到环境变量中，您可以直接替换$ARK_API_KEY为您的方舟 API Key ，再次运行命令。

Python

Python 安装

检查并安装 Python 版本，Python 版本需要 3.7 或以上。

您可以在终端中输入以下命令查看 Python 安装版本。

python -V

如果运行失败，您可以尝试使用下面命令再运行。

python3 -V

如果未安装或者版本不满足，请参考 Python 安装教程安装，注意选择版本 3.7 及以上版本。

方舟 Python SDK

跳转使用OpenAI SDK

安装方舟 Python SDK。
您可以在终端中输入以下命令，安装/升级方舟 Python SDK。
```
pip install -U 'volcengine-python-sdk[ark]'
```
如果您本地安装错误，可以尝试使用方法
- 使用下面命令安装
```
pip install -U volcengine-python-sdk[ark]
```
- Windows系统安装SDK失败，ERROR: Failed building wheel for volcengine-python-sdk

创建一个文件命名为ark_example.py，将下面示例代码拷贝进文件。

import os
from volcenginesdkarkruntime import Ark
# 从环境变量中读取您的方舟API Key
client = Ark(api_key=os.environ.get("ARK_API_KEY"))
completion = client.chat.completions.create(
    # 替换 <Model>为 Model ID
    model="<Model>",
    messages=[
        {"role": "user", "content": "你好"}
    ]
)
print(completion.choices[0].message)

在终端窗口中，使用下面命令运行代码。稍等您可以在终端窗口中看到模型调用的返回结果，这样您就完成了您的首次方舟平台模型服务调用。
```
python ark_example.py
```

OpenAI SDK

跳转使用方舟 Python SDK

安装OpenAI SDK。
您可以在终端中输入以下命令，安装/升级方舟 OpenAI SDK。
```
pip install -U openai
```

创建一个文件命名为ark_example.py，将下面示例代码拷贝进文件。

import os
from openai import OpenAI

client = OpenAI(
    # 从环境变量中读取您的方舟API Key
    api_key=os.environ.get("ARK_API_KEY"), 
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    )
completion = client.chat.completions.create(
    # 将推理接入点 <Model>替换为 Model ID
    model="<Model>",
    messages=[
        {"role": "user", "content": "你好"}
    ]
)
print(completion.choices[0].message)

在终端窗口中，使用下面命令运行代码。稍等您可以在终端窗口中看到模型调用的返回结果，这样您就完成了您的首次方舟平台模型服务调用。
```
python ark_example.py
```

Go

检查并安装 Go 版本，Go 版本需要 1.18 或以上。
```
go version
```
如果未安装 Go 或者版本不满足要求，您可以访问 Go 语言官方网站下载并安装适合您操作系统的 Go 版本。请确保选择 1.18 或以上版本。
安装方舟 Go SDK。
火山方舟 Go SDK 使用 go mod 进行管理，如果本地工程没有初始化 go mod，您可以运行以下命令初始化 go mod。<your-project-name> 替换为您的项目名称。
```
# 如在文件夹 ark-example 下打开终端窗口，运行命令go mod init ark-example
go mod init <your-project-name>
```

创建一个main.go文件，将下面代码拷贝到文件中，并替换<Model>。

package main

import (
    "context"
    "fmt"
    "os"
    "github.com/volcengine/volcengine-go-sdk/service/arkruntime"
    "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model"
    "github.com/volcengine/volcengine-go-sdk/volcengine"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
        //通过 os.Getenv 从环境变量中获取 ARK_API_KEY
        os.Getenv("ARK_API_KEY"),
    )
    // 创建一个上下文，通常用于传递请求的上下文信息，如超时、取消等
    ctx := context.Background()
    // 构建聊天完成请求，设置请求的模型和消息内容
    req := model.ChatCompletionRequest{
        // 将推理接入点 <Model>替换为 Model ID
       Model: "<Model>",
       Messages: []*model.ChatCompletionMessage{
          {
             // 消息的角色为用户
             Role: model.ChatMessageRoleUser,
             Content: &model.ChatCompletionMessageContent{
                StringValue: volcengine.String("你好"),
             },
          },
       },
    }

    // 发送聊天完成请求，并将结果存储在 resp 中，将可能出现的错误存储在 err 中
    resp, err := client.CreateChatCompletion(ctx, req)
    if err!= nil {
       // 若出现错误，打印错误信息并终止程序
       fmt.Printf("standard chat error: %v\n", err)
       return
    }
    // 打印聊天完成请求的响应结果
    fmt.Println(*resp.Choices[0].Message.Content.StringValue)
}

在终端窗口中，使用下面命令更新项目的依赖项。
```
go mod tidy
```
在终端窗口中，使用下面命令运行代码。稍等您可以在终端窗口中看到模型调用的返回结果。这样您就完成了您的首次方舟平台模型服务调用。
```
go run main.go
```

Java

检查并安装 Java 版本，Java 版本需要 1.8 或以上。
```
java -version
```
如果未安装 Java 或者版本不满足要求，您可以访问 Oracle 官方网站下载并安装适合您操作系统的 Java 版本。请确保选择 1.8 或以上版本。
安装方舟 Java JDK。
火山方舟 Java SDK 支持通过 Maven 和 Gradle 两种方式安装。
- 通过 Maven 安装：在项目的pom.xml文件中添加以下依赖配置。
```
...
<dependency>
  <groupId>com.volcengine</groupId>
   
  <artifactId>volcengine-java-sdk-ark-runtime</artifactId>
  <version>LATEST</version>
</dependency>
...
```
打开终端并进入项目根目录，运行下面命令，来安装依赖项。
```
mvn clean install
```
- 通过 Gradle 安装：在项目的build.gradle文件中，在dependencies部分添加以下依赖。

// 替换'LATEST' 为 SDK 最新版本号：https://mvnrepository.com/artifact/com.volcengine/volcengine-java-sdk-ark-runtime

implementation 'com.volcengine:volcengine-java-sdk-ark-runtime:LATEST'

将下面的示例代码拷贝到您的项目中，并替换调用模型的Model ID。

package com.ark.example;

import com.volcengine.ark.runtime.model.completion.chat.ChatCompletionRequest;
import com.volcengine.ark.runtime.model.completion.chat.ChatMessage;
import com.volcengine.ark.runtime.model.completion.chat.ChatMessageRole;
import com.volcengine.ark.runtime.service.ArkService;

import java.util.ArrayList;
import java.util.List;

/**
 * 这是一个示例类，展示了如何使用ArkService来完成聊天功能。
 */
public class ChatCompletionsExample {
    public static void main(String[] args) {
        // 从环境变量中获取API密钥
        String apiKey = System.getenv("ARK_API_KEY");
        
        // 创建ArkService实例
        ArkService arkService = ArkService.builder().apiKey(apiKey).build();
        
        // 初始化消息列表
        List<ChatMessage> chatMessages = new ArrayList<>();
        
        // 创建用户消息
        ChatMessage userMessage = ChatMessage.builder()
                .role(ChatMessageRole.USER) // 设置消息角色为用户
                .content("你好") // 设置消息内容
                .build();
        
        // 将用户消息添加到消息列表
        chatMessages.add(userMessage);
        
        // 创建聊天完成请求
        ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
                .model("<Model>")// 需要替换为Model ID
                .messages(chatMessages) // 设置消息列表
                .build();
        
        // 发送聊天完成请求并打印响应
        try {
            // 获取响应并打印每个选择的消息内容
            arkService.createChatCompletion(chatCompletionRequest)
                     .getChoices()
                     .forEach(choice -> System.out.println(choice.getMessage().getContent()));
        } catch (Exception e) {
            System.out.println("请求失败: " + e.getMessage());
        } finally {
            // 关闭服务执行器
            arkService.shutdownExecutor();
        }
    }
}

编译您的Java项目并运行，稍等您可以在终端窗口中看到模型调用的返回结果。这样您就完成了您的首次方舟平台模型服务调用。