API-KEY的获取与配置

如果您需要调用通义千问或其它DashScope支持的模型API,需要首先开通DashScope。通过本文档您可以了解到获取与配置DashScopeAPI-KEY的方法。

说明

灵积(DashScope)即将升级,统一合入百炼。建议您通过百炼使用阿里云的大模型服务,具体请参见首次调用通义千问API

开通DashScope

您需要在开通DashScope后,才可以获得API-KEY。开通DashScope请参考以下步骤:

  1. 访问DashScope管理控制台:前往控制台

    image.png

  2. 在控制台“总览”页下,单击去开通

    下载.jpeg

  3. 阅读服务协议,确认无误后单击立即开通

    image..png

获取API-KEY

您可以按照以下步骤获取DashScope的API-KEY。

  1. 访问DashScope管理控制台API-KEY管理页面:前往API-KEY管理,单击创建新的API-KEY

    API-KEY.jpg

  2. 系统创建生成API-KEY,并在弹出的对话框中展示,您可以单击复制按钮将API-KEY的内容复制保存。

    查看API-KEY00.jpg

  3. 复制并在安全的地方保存API-KEY后,单击我已保存,关闭。此次创建的API-KEY可立即用于调用DashScopeAPI,对API-KEY的后续操作均可在当前的API-KEY管理页面进行。

    API-KEY.jpg

    说明

    出于安全考虑,关闭弹窗后,您可以在API KEY管理通过账号验证的方式再次查看API-KEY。

配置API的方式

在您获取到API-KEY后,可在您的业务代码中配置API-KEY值来使用DashScope的模型服务。您可以通过以下两种方式进行配置。

方式一:通过环境变量设置API-KEY(推荐)

环境变量是操作系统中用于存储有关系统环境的信息的变量。您可以通过环境变量来配置API-KEY,这样即使您的代码库被公开,API-KEY也不会泄漏。您可以根据您的操作系统与使用场景来确定添加API-KEY到环境变量中的方法。

Linux系统

当您使用Linux系统(如Ubuntu、CentOS等)中的命令行添加API-KEY为环境变量时,可以选择在当前会话添加临时性环境变量,或对当前用户添加永久性环境变量。

方式一:添加临时性环境变量

如果您仅需要在当前会话中添加并使用临时性环境变量,可以运行以下命令:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

您可以在当前会话运行以下命令检查环境变量是否生效:

echo $DASHSCOPE_API_KEY

方式二:对当前用户添加永久性环境变量

如果您需要对当前用户添加永久性环境变量,使得在该用户的新会话中也可以使用该环境变量,可以把以下命令语句复制并添加到~/.bashrc文件中:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

或直接运行以下命令将上述命令语句添加到~/.bashrc中:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc

添加完成后,您可以运行以下命令使环境变量生效:

source ~/.bashrc

您可以新建一个会话,运行以下命令检查环境变量是否生效:

echo $DASHSCOPE_API_KEY

macOS系统

当您使用macOS系统中的命令行添加API-KEY为环境变量时,可以选择在当前会话添加临时性环境变量,或对当前用户添加永久性环境变量。

方式一:添加临时性环境变量

如果您仅需要在当前会话中添加并使用临时性环境变量,可以运行以下命令:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

您可以在当前会话运行以下命令检查环境变量是否生效:

echo $DASHSCOPE_API_KEY

方式二:对当前用户添加永久性环境变量

如果您需要对当前用户添加永久性环境变量,使得在该用户的新会话中也可以使用该环境变量,您可以根据您使用的Shell类型把以下命令复制并添加到~/.zshrc~/.bash_profile文件中。

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

或直接运行以下命令将上述命令语句添加到~/.zshrc~/.bash_profile中:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
## 如果您的Shell类型是Zsh,运行以下命令
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc

## 如果您的Shell类型是Bash,运行以下命令
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bash_profile

添加完成后,您可以根据使用的Shell类型运行以下命令使得环境变量生效:

# 如果您的Shell类型是Zsh,运行以下命令
source ~/.zshrc

# 如果您的Shell类型是Bash,运行以下命令
source ~/.bash_profile

您可以新建一个会话,运行以下命令检查环境变量是否生效:

echo $DASHSCOPE_API_KEY

Windows系统

在Windows系统中,您可以使用CMD或PowerShell(推荐)运行命令。

CMD

当您使用CMD中的命令行添加API-KEY为环境变量时,可以选择在当前会话添加临时性环境变量,或对当前用户添加永久性环境变量。

方式一:添加临时性环境变量

如果您仅需要在当前会话中添加并使用临时性环境变量,可以运行以下命令:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
set DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

您可以在当前会话运行以下命令检查环境变量是否生效:

echo %DASHSCOPE_API_KEY%

方式二:对当前用户添加永久性环境变量

当您在CMD中需要为当前用户添加永久性环境变量时,可以运行以下命令:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"

您可以新建一个会话,运行以下命令检查环境变量是否生效:

echo %DASHSCOPE_API_KEY%

PowerShell

当您使用PowerShell中的命令行添加API-KEY为环境变量时,可以选择在当前会话添加临时性环境变量,或对当前用户添加永久性环境变量。

方式一:添加临时性环境变量

如果您仅需要在当前会话中添加并使用临时性环境变量,您可以运行以下命令:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
$env:DASHSCOPE_API_KEY = "YOUR_DASHSCOPE_API_KEY"

您可以在当前会话运行以下命令检查环境变量是否生效:

echo $env:DASHSCOPE_API_KEY

方式二:对当前用户添加永久性环境变量

如果您在PowerShell中需要为当前用户添加永久性环境变量,可以运行以下命令:

# 用您的 API-KEY 代替 YOUR_DASHSCOPE_API_KEY
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)

您可以新建一个会话,运行以下命令检查环境变量是否生效:

echo $env:DASHSCOPE_API_KEY

方式二:在代码中显式配置API-KEY

我们不建议您将API-KEY直接写在代码中,可能存在泄露风险。如果您没有配置环境变量,可以参考以下示例代码,在代码中配置API-KEY。

说明

请用您的API-KEY替换YOUR_DASHSCOPE_API_KEY

import dashscope
dashscope.api_key="YOUR_DASHSCOPE_API_KEY"
import com.alibaba.dashscope.utils.Constants;

# 以下赋值语句请放在类或方法中运行
Constants.apiKey="YOUR_DASHSCOPE_API_KEY";

保护并正确使用API-KEY

重要

API-KEY是访问DashScope的密钥,请务必妥善保存。不要以任何方式公开到外部渠道,避免因未经授权的使用造成安全风险或资金损失。

DashScope通过API-KEY进行调用鉴权和计量计费,而API-KEY是基于主账号的维度生成和管理的。目前支持主账号或者得到主账号授权的子账号进行API-KEY的管理,每个主账号最多同时可以拥有3个有效的API-KEY,因此不论是主账号还是得到授权的子账号登录,实际管理的API-KEY都是关联对应的主账号的。API-KEY不应被分享给未经授权的开发者。

为了防止API-KEY的创建功能被滥用,每个主账号(含对应子账号操作)每天仅可进行10次API-KEY新建操作。

为了保护API-KEY不被泄露,API调用应该仅发起于服务端。任何发起自客户端的API调用,例如浏览器、app、小程序等,均有可能造成API-KEY的泄露。

如怀疑API-KEY可能已经被泄露,可以通过DashScope的管理控制台删除该API-KEY。API-KEY被删除后,采用该API-KEY的后续调用均会被拒绝。

子账号赋权步骤

DashScope也支持通过子账号登录控制台进行相关的API-KEY管理、调用量查询等日常管理工作,前提是子账号得到了主账号的赋权。主账号登录阿里云的RAM管控平台就可以看到相关的子账号信息,在用户页面,主账号通过点击添加权限就可以给目标子账号进行赋权操作。

image.png

点击添加权限之后,在弹出的操作栏中搜索dashscope就可以看到相关的权限。对于DashScope来说,有两种类型的权限,一种是“管理DashScope大模型的权限”,这意味这得到赋权的子账号在DashScope拥有和主账号同等级别的管理权限;另一种是“只读访问DashScope大模型的权限”,这个权限限制了子账号只能在DashScope的管理控制台上进行查看的权限,而不能对API-KEY等具体设置进行更改。

image.png

需要指出的是,DashScope的API-KEY关联的是您的主账号,也就是说,在一个主账号之下只有一套API-KEY,主账号之下所有的子账号登录之后管理或者查看的都是同样一套API-KEY,不存在关联某个子账号的专属API-KEY。所以即使是子账号登录,在操作API-KEY的时候也需要小心谨慎,因为这个操作是会在整个主账号级别产生影响的。

在完成了上述赋权操作之后,得到相应权限的子账号就可以独立的登录DashScope的管理控制台完成相应的操作了。