配置終端節點私網調用百鍊API-大模型服務平台百鍊-阿里雲_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

為了在 VPC 內直接調用阿里雲百鍊的模型或應用 API，且確保流量不經過公網，可以在百鍊控制台添加私網連接並關聯業務空間，將通訊完全限制在阿里雲內網。

工作原理

百鍊網關支援以下兩種接入方式：

公網調用：直接存取公網 MaaS 網域名稱 {WorkspaceId}.{RegionId}.maas.aliyuncs.com，流量經公網到達百鍊。
PrivateLink 私網串連：在百鍊控制台為 VPC 添加私網連接後，通過私網網域名稱訪問百鍊，流量全程走阿里雲內網，不經過公網。

在百鍊控制台添加私網連接後，阿里雲私網串連服務（PrivateLink）將為您的 VPC 與阿里雲百鍊建立一條私網串連（終端節點串連）。該串連為單向設計，僅允許您的 VPC 內的資源主動訪問阿里雲百鍊，阿里雲百鍊無法通過此串連反向訪問您 VPC 內的資源。

VPC 內的計算資源訪問私網網域名稱時，流量將通過 PrivateLink 轉寄至阿里雲百鍊服務端，不經過公網。

阿里雲百鍊服務所在地區：

公用云：華北2（北京）、中國香港。

其他地區暫不支援私網訪問。

通過私網連接訪問阿里雲百鍊 API

步驟一：在百鍊控制台添加私網連接

登入百鍊控制台，在左側導覽列選擇管理 > 网络配置。
首次使用時，在添加私网连接面板中按照指引完成以下準備：
- 授权私网连接服务关联角色：單擊立即授权，自動建立服務關聯角色 AliyunServiceRoleForBackrouterAccessNet。
- 开通私网连接：單擊立即开通，開通私網連接（PrivateLink）服務。
在VPC私网访问區域單擊添加，配置以下各項參數，其他參數保持預設即可。
- 地域：根據阿里雲百鍊服務地區選擇，例如「中國香港」。
- VPC：選擇計劃用於訪問阿里雲百鍊服務的 VPC。私網連接將被建立到該 VPC 內，僅該 VPC 內的 ECS、容器等資源才能通過私網網域名稱訪問阿里雲百鍊服務。如無可用 VPC，可單擊创建VPC跳轉至专有网络控制台建立。如需使用其他帳號共享的 VPC，直接選擇該共享 VPC，具體參見跨帳號存取。
- 可用区与交换机：選擇阿里雲百鍊支援且包含交換器的可用性區域及對應交換器。私網連接會佔用所選可用性區域下交換器的一個內網 IP 地址，作為百鍊私網網域名稱的內網解析地址。最多可添加 2 個可用性區域與交換器組合，建議添加 2 個以實現高可用：當某個可用性區域發生故障時，流量可自動切換至其他可用性區域，避免服務中斷。如無可用交換器，可單擊创建交换机跳轉至专有网络控制台建立。
- 安全组：選擇關聯到私網連接的安全性群組，用於控制誰可以訪問該私網連接。因此請確保安全性群組在入方向允許 443（https）訪問。如無可用安全性群組，可單擊创建安全组跳轉至云服务器 ECS 控制台建立。
單擊确认，等待狀態變為创建成功。添加完成後預計延遲 1～3min 生效，生效期間該 VPC 下任意云服务器均可使用私網網域名稱訪問百鍊服務。

步驟二：關聯業務空間

需要通過私網訪問阿里雲百鍊的業務空間，須與私網連接建立關聯。

在百鍊控制台左側導覽列選擇业务空间管理，新建業務空間或編輯目標業務空間。
在高级配置中，將私网连接設定為目標私網連接。下拉選項展示終端節點 ID 及其所屬地區和 VPC；如無目標選項，可在下拉框中單擊新建私网连接建立。關聯後，該業務空間可通過對應 VPC 的私網連接訪問百鍊服務。
如需解除關聯：編輯業務空間並清空私网连接後儲存；或在网络配置頁面展開目標私網連接行，在关联业务空间中單擊解绑，跳轉至對應業務空間處理。已關聯業務空間的私網連接需先解綁才能刪除。

步驟三：擷取私網網域名稱

完成步驟二的關聯後，系統為每個已關聯的業務空間產生私網網域名稱。在网络配置頁面的VPC私网访问列表中展開目標私網連接，在 Endpoint 欄擷取私網網域名稱，关联业务空间欄展示該網域名稱所屬的業務空間 ID。私網網域名稱格式為 {WorkspaceId}-{VpcId}.{地區ID}.maas.aliyuncs.com，其中 WorkspaceId 為業務空間 ID，VpcId 為私網連接所屬的 VPC ID。

您也可以在左側導覽列選擇业务空间管理，在目標業務空間的 API Host 欄檢視私网網域名稱。

私網網域名稱僅在所選 VPC 內可解析和訪問，通過 HTTPS（443 連接埠）調用阿里雲百鍊 API。未關聯業務空間時，展開行的 Endpoint 欄為空。

步驟四：調用驗證

將阿里雲百鍊 API base_url 中的網域名稱，替換為上一步驟中擷取到的私網網域名稱，然後在對應 VPC 發起調用即可。

以 OpenAI 相容模式調用通義千問文本模型為例：

替換前：https://{WorkspaceId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1/chat/completions
替換後：https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1/chat/completions

調用樣本：

HTTP

# 將原始網域名稱替換為上一步驟中擷取到的私網網域名稱
curl -X POST https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-flash",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "你是誰？"
        }
    ]
}'

OpenAI Python SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 將原始網域名稱替換為上一步驟中擷取到的私網網域名稱
    base_url="https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-flash",
    messages=[
        {'role': 'system', 'content': 'You are a helpful assistant.'},
        {'role': 'user', 'content': '你是誰？'}],
)
print(completion.model_dump_json())

DashScope Python SDK

import os
# 建議dashscope SDK 的版本 >= 2.0.1
import dashscope
from dashscope.v2 import DashScopeError

# 將原始網域名稱替換為上一步驟中擷取到的私網網域名稱
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/api/v1",
)
messages = [{
    'role': 'user', 'content': '你是誰？'
}]
try:
    response = client.chat.completions.create(
        model="qwen-flash",
        messages=messages,
    )
    print(response)
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("See: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

DashScope Java SDK

// 建議DashScope SDK的版本 >= 2.12.0
import java.util.Arrays;

import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.protocol.Protocol;
import com.alibaba.dashscope.utils.JsonUtils;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        // 將原始網域名稱替換為上一步驟中擷取到的私網網域名稱
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/api/v1");
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant.")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("你是誰？")
                .build();
        GenerationParam param = GenerationParam.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-flash")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();
        return gen.call(param);
    }
    public static void main(String[] args) {
        try {
            GenerationResult result = callWithMessage();
            System.out.println(JsonUtils.toJson(result));
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // 列印錯誤資訊
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
    }
}

調用前，需要您已完成擷取與配置 API Key。如需要直接傳入 API Key，請將$DASHSCOPE_API_KEY 替換為您的 API Key。

跨帳號存取

預設情況下，私網連接只能建立在目前帳號的 VPC 內，且僅該 VPC 內的資源可以透過私網網域名稱訪問百鍊。如果調用方資源所在 VPC 屬於其他阿里雲帳號，可以選擇以下任一方式：

方式一：VPC 共享：將調用方 VPC 的交換器共享給百鍊帳號，私網連接直接建立在調用方 VPC 內。
方式二：VPC 互聯：私網連接建立在百鍊帳號自己的 VPC 內，調用方 VPC 透過 VPC 對等連接或雲企業網與該 VPC 互聯後訪問該私網連接。

兩種方式都不需要在帳號之間共享私網連接本身。調用方不是百鍊帳號時，由百鍊帳號將私網網域名稱和業務空間 API Key 提供給調用方。

方式一：VPC 共享

VPC 共享涉及兩個帳號：

VPC 所有者帳號：擁有 VPC 和交換器，負責共享交換器。
百鍊帳號：接受共享，在百鍊控制台添加私網連接並關聯業務空間。

私網連接建立在共享 VPC 內，該 VPC 內屬於任一帳號的資源都可以使用這條連接。也可以由 VPC 所有者帳號自行在該 VPC 內建立私網連接，供共享 VPC 內的其他帳號使用。無論哪種情況，PrivateLink 費用都由建立私網連接的帳號承擔。以下以百鍊帳號建立私網連接為例。

步驟一：VPC 所有者帳號共享交換器

登入資源共享控制台，單擊创建共享单元，依次完成配置基本信息并添加资源（添加需要共享的交換器）、关联权限（選擇 AliyunRSDefaultPermissionVSwitch）、关联资源使用者（輸入百鍊帳號的 UID）和确认并提交。共享的是交換器而不是整個 VPC，詳細操作參見共享 VPC。

步驟二：百鍊帳號接受共享

使用百鍊帳號登入資源共享控制台，在共享给我頁面接受共享。如果共享單元已自動關聯，可跳過此步。

步驟三：百鍊帳號添加私網連接

登入百鍊控制台，按本文步驟一添加私網連接。配置時注意：

地域：選擇共享 VPC 所在地區，且該地區需支援百鍊私網訪問，例如中國香港。
VPC：選擇共享過來的 VPC。
可用区与交换机：選擇共享 VPC 下的共享交換器。
安全组：選擇共享 VPC 內可用的安全性群組，並確保入方向允許調用方資源存取 443 連接埠。

其他參數與同帳號流程一致。

步驟四：完成後續配置並調用

私網連接建立成功後，按本文步驟二、步驟三、步驟四關聯業務空間並取得私網網域名稱。調用方在共享 VPC 內使用該私網網域名稱和業務空間 API Key 發起調用。

方式二：VPC 互聯

VPC 互聯涉及兩個帳號：

百鍊帳號：在自己的 VPC（下稱百鍊 VPC）內建立私網連接並關聯業務空間。
調用方帳號：擁有調用方資源所在的 VPC（下稱調用方 VPC）。

VPC 互聯後兩個 VPC 的網路是雙向連通的，任一帳號都可以在自己的 VPC 內建立私網連接供另一帳號調用，即兩個帳號都可以作為百鍊帳號。

步驟一：打通網路

透過以下任一方式連通百鍊 VPC 與調用方 VPC，兩端 VPC 網段不能重疊。兩種方式的選型和計費對比參見VPC 互聯概述。

VPC 對等連接
1. 任一帳號在专有网络控制台建立對等連接，接收端账号类型選擇跨账号，並填寫對端帳號 UID 和對端 VPC ID。
2. 對端帳號在专有网络控制台的 VPC 對等連接頁面接收該連接。
3. 兩端帳號分別在各自 VPC 的路由表中添加路由，目標網段為對端 VPC 網段，下一跳為該對等連接。
詳細操作參見VPC 對等連接。
雲企業網
1. 任一帳號建立雲企業網執行個體，並在 VPC 所在地區建立轉送路由器。
2. 對端帳號將自己的 VPC 授權給該雲企業網執行個體。
3. 在轉送路由器中為兩個 VPC 分別建立 VPC 連接，將兩個 VPC 接入同一個轉送路由器。
詳細操作參見使用企業版轉送路由器實現跨地區跨帳號 VPC 互通。

步驟二：放行私網連接安全性群組

網路打通後，調用方仍需經過私網連接安全性群組的放行才能訪問私網連接。百鍊帳號在私網連接關聯的安全性群組中添加以下入方向規則：

參數	取值
授權策略	允許
協議類型	自訂 TCP
連接埠範圍	443
授權對象	調用方 VPC 網段，例如 `192.168.0.0/16`。可在专有网络控制台的 VPC 詳情頁查看

未放行時，即使網路已打通，調用也會連線逾時。

步驟三：發起調用

百鍊帳號將私網網域名稱和業務空間 API Key 提供給調用方帳號，調用方 VPC 內的資源按本文步驟四發起調用。如果返回 Failed to connect to <私網網域名稱> port 443 等連線逾時錯誤，請檢查步驟一的網路配置和步驟二的安全性群組規則。

計費說明

使用私網連接（PrivateLink）會產生額外費用，可參考私網連接計費說明來瞭解和評估成本。

私網連接和模型調用費用由建立該私網連接的帳號承擔，與 VPC 屬於哪個帳號無關。VPC 對等連接和雲企業網計費參見VPC 對等連接和雲企業網計費規則。

常見問題

為什麼我的 ECS 執行個體無法通過私網連接訪問阿里雲百鍊 API？
請按照以下步驟排查：
1. 確認是否在同一 VPC。
  
  如果 ECS 執行個體的 VPC，與配置私網連接的 VPC 不同，則無法通過私網訪問阿里雲百鍊 API，需要先配置 VPC互連，例如 VPC 對等連接或雲企業網，並放行私網連接安全性群組，具體參見方式二：VPC 互聯。
2. 檢查私網連接關聯的安全性群組，確認已添加入方向規則，允許來自發起端 ECS 執行個體所在網段對 443（HTTPS）連接埠的訪問。
3. 確認私網連接狀態。
  
  私網連接狀態為创建成功且已生效（添加完成後預計延遲 1～3min）後，才能通過私網網域名稱訪問阿里雲百鍊 API。
4. 確認業務空間已關聯。
  
  私網網域名稱在業務空間與私網連接關聯後才產生。如果展開行的 Endpoint 欄為空，請先按步驟二關聯業務空間。
終端節點能否從公網訪問？
不可以。私網連接（PrivateLink）僅用於在阿里雲內網建立私人連接。終端節點不具備公網訪問能力，終端節點網卡也無法綁定 Elastic IP Address (EIP)。
通過舊方式建立的存量私網連接，還需要關聯業務空間嗎？
不需要。此前在私網連接（专有网络 VPC）控制台建立介面終端節點所產生的存量私網連接，預設關聯所有業務空間，可直接用於私網訪問阿里雲百鍊 API，無需執行步驟二。

在网络配置頁面展開存量私網連接，Endpoint 欄展示 vpc-{地區ID}.dashscope.aliyuncs.com（例如 vpc-ap-southeast-1.dashscope.aliyuncs.com），关联业务空间欄顯示所有业务空间；這與新流程依業務空間逐條展示 {WorkspaceId}-{VpcId}.{地區ID}.maas.aliyuncs.com 不同。

舊方式已不再支援建立新的私網連接。如需新增，請按步驟一在百鍊控制台建立，並按步驟二關聯需要私網訪問的業務空間。