Model Studio PrivateLink private network endpoint VPC - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Para chamar as APIs do Model Studio a partir de uma VPC sem rotear o tráfego pela internet pública, adicione uma conexão PrivateLink no console do Model Studio e associe-a ao seu workspace.

Como funciona

O gateway do Model Studio oferece os dois métodos de acesso a seguir:

Acesso por rede pública: chame as APIs do Model Studio pelo nome de domínio MaaS público {WorkspaceId}.{RegionId}.maas.aliyuncs.com. O tráfego é roteado pela internet pública.
Conexão privada via PrivateLink: adicione uma conexão PrivateLink para sua VPC no console do Model Studio e chame as APIs do Model Studio pelo nome de domínio privado. O tráfego permanece na rede da Alibaba Cloud e não atravessa a internet pública.

Após adicionar uma conexão PrivateLink no console do Model Studio, o PrivateLink estabelece uma conexão privada (conexão de endpoint) entre sua VPC e o Model Studio. Essa conexão é unidirecional: os recursos da sua VPC podem acessar o Model Studio, mas o Model Studio não consegue acessar sua VPC por meio dessa conexão.

Quando os recursos da sua VPC acessam o nome de domínio privado, o PrivateLink roteia o tráfego para o Model Studio sem passar pela internet pública.

O Model Studio está disponível nas seguintes regiões:

Nuvem pública: China (Beijing) e China (Hong Kong).

O acesso por rede privada ainda não tem suporte em outras regiões.

Acesse as APIs do Model Studio com uma conexão PrivateLink

Etapa 1: Adicione uma conexão PrivateLink no console do Model Studio

Faça login no console do Model Studio. No painel de navegação à esquerda, escolha Settings > Network configuration.
Na primeira utilização, conclua os preparativos a seguir no painel Add PrivateLink:
- Authorize service-linked role for PrivateLink: clique em Authorize Now e depois em Confirm Authorization para criar a função vinculada ao serviço AliyunServiceRoleForBackrouterAccessNet.
- Activate PrivateLink: clique em Enable Now para ativar o serviço PrivateLink.
Na seção VPC private network access, clique em Add e configure os parâmetros a seguir. Mantenha os demais parâmetros com os valores padrão.
- Region: selecione a região do seu serviço Model Studio, por exemplo, China (Hong Kong).
- VPC: selecione a VPC a partir da qual você deseja acessar o Model Studio. A conexão PrivateLink é criada nessa VPC, e somente recursos dessa VPC, como instâncias ECS e contêineres, conseguem alcançar o Model Studio pelo nome de domínio privado. Se nenhuma VPC estiver disponível, clique em Create VPC para criar uma no console de VPC. Para usar uma VPC compartilhada por outra conta, selecione a VPC compartilhada. Para obter mais informações, consulte Acesso entre contas.
- Zones and Switches: selecione uma zona compatível com o Model Studio que contenha um vSwitch e, em seguida, selecione o vSwitch. A conexão PrivateLink ocupa um endereço IP interno do vSwitch selecionado em cada zona como endereço de resolução DNS interna do nome de domínio privado. É possível adicionar até duas combinações de zona e vSwitch. Adicione duas para obter alta disponibilidade, de modo que o tráfego possa ser transferido se uma zona ficar indisponível. Se nenhum vSwitch estiver disponível, clique em Create Switch para criar um no console de VPC.
- Security Group: selecione o grupo de segurança a associar à conexão PrivateLink. O grupo de segurança controla quais recursos podem acessar a conexão. Verifique se o grupo de segurança permite tráfego de entrada na porta 443 (HTTPS). Se nenhum grupo de segurança estiver disponível, clique em Create Security Group para criar um no console do ECS.
Clique em Confirm e aguarde até que o Status da conexão mude para Created. A conexão entra em vigor em cerca de 1 a 3 minutos. Depois disso, qualquer servidor cloud na VPC pode usar o nome de domínio privado para acessar o Model Studio.

Etapa 2: Associe a conexão PrivateLink a um workspace

Um workspace que precisa acessar o Model Studio pela rede privada deve ser associado a uma conexão PrivateLink.

No painel de navegação à esquerda do console do Model Studio, escolha Workspaces e crie um workspace ou edite o workspace desejado.
Em Advanced Configuration, defina PrivateLink como a conexão PrivateLink desejada. Cada opção mostra o ID do endpoint com sua região e VPC. Se a conexão desejada não estiver listada, clique em Create PrivateLink na lista suspensa para criá-la. Após a associação, o workspace pode acessar o Model Studio pela conexão privada da VPC correspondente.
Para remover a associação, edite o workspace, limpe o campo PrivateLink e salve as alterações. Como alternativa, na página Network configuration, expanda a linha da conexão PrivateLink desejada e clique em Unbind na coluna Associated workspace para concluir no workspace correspondente. Uma conexão PrivateLink associada a workspaces não pode ser excluída antes de ser desassociada.

Etapa 3: Obtenha o nome de domínio privado

Após concluir a Etapa 2, um nome de domínio privado é gerado para cada workspace associado. Na página Network configuration, expanda a linha da conexão PrivateLink desejada na lista VPC private network access e copie o nome de domínio privado na coluna Endpoint. A coluna Associated workspace mostra o ID do workspace ao qual o nome de domínio pertence. O nome de domínio privado tem o formato {WorkspaceId}-{VpcId}.{region-id}.maas.aliyuncs.com, em que WorkspaceId é o ID do workspace e VpcId é o ID da VPC à qual a conexão PrivateLink pertence.

Você também pode encontrar o nome de domínio privado na coluna API Host do workspace desejado, na página Workspaces. Após a associação, essa coluna lista o nome de domínio público e o privado.

O nome de domínio privado só pode ser resolvido e acessado dentro da VPC selecionada. Use HTTPS (porta 443) para chamar as APIs do Model Studio. Se nenhum workspace estiver associado, a coluna Endpoint da linha expandida ficará vazia.

Etapa 4: Verifique a conexão

Substitua o nome de domínio no base_url da sua requisição de API pelo nome de domínio privado obtido na etapa anterior e faça a chamada a partir da VPC.

Por exemplo, para chamar o Qwen text model no modo compatível com OpenAI:

Antes da substituição: https://{WorkspaceId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Depois da substituição: https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1/chat/completions

Exemplo de chamada:

http

# Replace the original domain name with the private domain name from the previous step.
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": "Who are you?"
        }
    ]
}'

OpenAI Python SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Replace the original domain name with the private domain name from the previous step.
    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': 'Who are you?'}],
)
print(completion.model_dump_json())

DashScope Python SDK

import os
# Recomendamos usar o SDK do DashScope versão 2.0.1 ou posterior.
import dashscope
from dashscope.v2 import DashScopeError
# Configure o endpoint privado: substitua o domínio original pelo domínio privado obtido na etapa anterior.
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': 'Who are you?'
}]
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

// We recommend that you use DashScope SDK v2.12.0 or later.
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 {
        // Replace the original domain name with the private domain name from the previous step.
        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("Who are you?")
                .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) {
            // Print the error message.
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
    }
}

Antes de fazer a chamada, você deve get an API key . Para passar a chave de API diretamente no código, substitua $DASHSCOPE_API_KEY pela sua chave de API.

Acesso entre contas

Por padrão, uma conexão PrivateLink só pode ser criada em uma VPC pertencente à conta atual, e somente os recursos dessa VPC podem acessar o Model Studio pelo nome de domínio privado. Se a VPC que contém os recursos de chamada pertencer a outra conta da Alibaba Cloud, você pode usar qualquer um dos métodos a seguir:

Método 1: compartilhamento de VPC: compartilhe o vSwitch da VPC de chamada com a conta do Model Studio. A conexão PrivateLink é criada diretamente na VPC de chamada.
Método 2: interconexão de VPCs: a conexão PrivateLink é criada na VPC da própria conta do Model Studio. A VPC de chamada é interconectada a essa VPC por meio de uma conexão de emparelhamento de VPC ou do CEN e, em seguida, acessa a conexão PrivateLink.

Nenhum dos métodos exige o compartilhamento da própria conexão PrivateLink entre contas. Se o chamador não for a conta do Model Studio, a conta do Model Studio fornece o nome de domínio privado e a chave de API do espaço de trabalho ao chamador.

Método 1: compartilhamento de VPC

O compartilhamento de VPC envolve duas contas:

Conta proprietária da VPC: possui a VPC e o vSwitch e compartilha o vSwitch.
Conta do Model Studio: aceita o compartilhamento, adiciona a conexão PrivateLink no console do Model Studio e associa o espaço de trabalho.

A conexão PrivateLink é criada na VPC compartilhada, e os recursos dessa VPC pertencentes a qualquer conta podem usar a conexão. A conta proprietária da VPC também pode criar ela mesma uma conexão PrivateLink nessa VPC para uso de outras contas na VPC compartilhada. Em qualquer caso, as taxas do PrivateLink são cobradas da conta que cria a conexão PrivateLink. As etapas a seguir usam como exemplo a criação da conexão PrivateLink pela conta do Model Studio.

Etapa 1: a conta proprietária da VPC compartilha o vSwitch

No console Resource Sharing, clique em Create Sharing Unit e conclua Configure Basic Information and Add Resources (adicione o vSwitch a ser compartilhado), Associate Permissions (selecione AliyunRSDefaultPermissionVSwitch), Associate Resource Users (insira o UID da conta do Model Studio) e Confirm and Submit. O compartilhamento de VPC compartilha um vSwitch, não a VPC inteira. Para obter mais informações, consulte Compartilhar uma VPC.

Etapa 2: a conta do Model Studio aceita o compartilhamento

Faça login no console Resource Sharing com a conta do Model Studio e aceite o compartilhamento na página Shared with Me. Se a unidade de compartilhamento já estiver associada, ignore esta etapa.

Etapa 3: a conta do Model Studio adiciona uma conexão PrivateLink

Faça login no console do Model Studio e adicione uma conexão PrivateLink conforme descrito na Etapa 1 deste tópico. Observe as seguintes configurações:

Region: selecione a região em que a VPC compartilhada está localizada. A região deve oferecer suporte ao acesso de rede privada do Model Studio, por exemplo, China (Beijing) ou China (Hong Kong).
VPC: selecione a VPC compartilhada.
Zones and Switches: selecione o vSwitch compartilhado na VPC compartilhada.
Security Group: selecione um grupo de segurança disponível na VPC compartilhada e verifique se as regras de entrada permitem que os recursos de chamada acessem a porta 443.

Os demais parâmetros são iguais aos do fluxo para a mesma conta.

Etapa 4: conclua as configurações restantes e faça as chamadas

Depois que a conexão PrivateLink for criada, associe o espaço de trabalho e obtenha o nome de domínio privado conforme descrito na Etapa 2, Etapa 3 e Etapa 4 deste tópico. O chamador usa esse nome de domínio privado e a chave de API do espaço de trabalho para fazer chamadas na VPC compartilhada.

Método 2: interconexão de VPCs

A interconexão de VPCs envolve duas contas:

Conta do Model Studio: cria a conexão PrivateLink na própria VPC (doravante denominada VPC do Model Studio) e associa o espaço de trabalho.
Conta chamadora: possui a VPC em que os recursos de chamada estão localizados (doravante denominada VPC de chamada).

Após a interconexão, a rede entre as duas VPCs é bidirecional. Qualquer uma das contas pode criar uma conexão PrivateLink na própria VPC para que a outra conta faça chamadas, ou seja, ambas as contas podem atuar como a conta do Model Studio.

Etapa 1: conecte as redes

Conecte a VPC do Model Studio e a VPC de chamada usando qualquer um dos métodos a seguir. Os blocos CIDR das duas VPCs não podem se sobrepor. Para uma comparação de seleção e cobrança entre os dois métodos, consulte Visão geral da interconexão de VPCs.

Conexão de emparelhamento de VPC
1. Qualquer uma das contas cria uma conexão de emparelhamento no console de VPC, define Acceptor Account Type como Cross-account e insere o UID da conta par e o ID da VPC par.
2. A conta par aceita a conexão na página de conexões de emparelhamento de VPC do console de VPC.
3. Cada conta adiciona uma rota à tabela de rotas da própria VPC, com o bloco CIDR da VPC par como destino e a conexão de emparelhamento como próximo salto.
Para obter mais informações, consulte Conexões de emparelhamento de VPC.
CEN
1. Qualquer uma das contas cria uma instância do CEN e cria um transit router na região em que a VPC está localizada.
2. A conta par autoriza a própria VPC para essa instância do CEN.
3. No transit router, crie uma conexão de VPC para cada uma das duas VPCs, conectando ambas ao mesmo transit router.
Para obter mais informações, consulte Usar transit routers da Enterprise Edition para conectar VPCs entre regiões e contas.

Etapa 2: permita o tráfego no grupo de segurança da conexão PrivateLink

Depois que as redes forem conectadas, o chamador ainda precisa ser permitido pelo grupo de segurança da conexão PrivateLink para acessá-la. A conta do Model Studio adiciona a seguinte regra de entrada ao grupo de segurança associado à conexão PrivateLink:

Parâmetro	Valor
Política de autorização	Permitir
Tipo de protocolo	TCP personalizado
Intervalo de portas	443
Objeto de autorização	Bloco CIDR da VPC de chamada, por exemplo, `192.168.0.0/16`. Você pode visualizá-lo na página de detalhes da VPC no console de VPC

Se o tráfego não for permitido, as chamadas atingirão o tempo limite de conexão mesmo que as redes estejam conectadas.

Etapa 3: faça as chamadas

A conta do Model Studio fornece o nome de domínio privado e a chave de API do espaço de trabalho à conta chamadora, e os recursos na VPC de chamada fazem chamadas conforme descrito na Etapa 4 deste tópico. Se for retornado um erro de tempo limite de conexão, como Failed to connect to <private domain name> port 443, verifique a configuração de rede da Etapa 1 e as regras do grupo de segurança da Etapa 2.

Faturamento

O uso do PrivateLink gera custos adicionais. Para estimativas de custos, consulte Billing of PrivateLink.

As taxas do PrivateLink e as taxas de invocação de modelos são cobradas da conta que cria a conexão PrivateLink, independentemente de qual conta possui a VPC. Para a cobrança das conexões de emparelhamento de VPC e do CEN, consulte Conexões de emparelhamento de VPC e Regras de cobrança do CEN.

Perguntas frequentes

Por que minha instância ECS não consegue acessar as APIs do Model Studio por uma rede privada?
Verifique os itens a seguir:
1. Confirme se a instância ECS e a conexão PrivateLink estão na mesma VPC.
  
  Se a instância ECS estiver em uma VPC diferente, ela não poderá acessar o Model Studio pela rede privada. Nesse caso, configure primeiro as VPC connections, por exemplo, uma conexão de emparelhamento de VPC ou o CEN, e permita o tráfego no grupo de segurança da conexão PrivateLink. Para obter mais informações, consulte Método 2: interconexão de VPCs.
2. Verifique se o grupo de segurança associado à conexão PrivateLink permite tráfego de entrada do bloco CIDR da instância ECS na porta 443 (HTTPS).
3. Verifique o status da conexão PrivateLink.
  
  O nome de domínio privado só pode ser usado depois que o status da conexão for Created e a conexão entrar em vigor (cerca de 1 a 3 minutos após a criação).
4. Verifique se o workspace está associado.
  
  Um nome de domínio privado só é gerado depois que um workspace é associado à conexão PrivateLink. Se a coluna Endpoint da linha expandida estiver vazia, associe o workspace conforme descrito na Etapa 2.
Um endpoint pode ser acessado pela internet pública?
Não. O PrivateLink estabelece conexões privadas apenas dentro da rede interna da Alibaba Cloud. Endpoints não podem ser acessados pela internet pública, e não é possível associar um EIP a uma ENI de endpoint.
Uma conexão PrivateLink legada precisa ser associada a um workspace?
Não. Uma conexão PrivateLink legada, criada como endpoint de interface no console do PrivateLink (VPC), é associada a todos os workspaces por padrão. Você pode usá-la para acessar as APIs do Model Studio pela rede privada sem executar a Etapa 2.

Ao expandir uma conexão legada na página Network configuration, a coluna Endpoint mostra vpc-{region-id}.dashscope.aliyuncs.com (por exemplo, vpc-ap-southeast-1.dashscope.aliyuncs.com), e a coluna Associated workspace indica que a conexão está associada a todos os workspaces. Isso difere do fluxo atual, que lista {WorkspaceId}-{VpcId}.{region-id}.maas.aliyuncs.com para cada workspace associado.

Não é mais possível criar uma conexão PrivateLink dessa forma. Para adicionar uma, siga a Etapa 1 para criá-la no console do Model Studio e a Etapa 2 para associar os workspaces que precisam de acesso pela rede privada.