LLM intelligent routing workbench - Platform For AI: Central de Documentação do Alibaba Cloud

O workbench WebUI é uma interface de gerenciamento visual para o roteamento inteligente de LLM. Oferece gerenciamento de usuários baseado em funções, alocação independente de API Key, monitoramento em tempo real e atualizações de configuração a quente. Esses recursos garantem isolamento de identidade e auditoria de acesso, reduzindo a complexidade operacional.

Visão geral dos recursos

Ative o gerenciamento de usuários no workbench conforme necessário. Com esse recurso desativado, o workbench disponibiliza os seguintes módulos:

Monitoramento em tempo real: Exibe métricas de desempenho quase em tempo real, como throughput, latência e TTFT, além da distribuição de códigos de status e do estado operacional do gateway, do agendador e das instâncias de inferência. Facilita a detecção rápida de anomalias e a identificação de gargalos de desempenho.
Centro de configuração: Permite atualizações a quente de parâmetros essenciais, incluindo proxy de divisão de tráfego, política de agendamento, limitação de requisições e espelhamento de tráfego. As alterações entram em vigor imediatamente sem reinicialização do serviço, sendo ideais para ajustes dinâmicos em produção. Para mais informações, consulte centro de configuração.
Chat inteligente: Oferece uma interface visual para testes de chat. Envie requisições de texto ou imagem diretamente ao serviço de roteamento inteligente de LLM e utilize logs HTTP para depuração, validando rapidamente o comportamento do proxy de divisão de tráfego.

A ativação do gerenciamento de usuários cria um sistema abrangente, ideal para empresas com várias equipes compartilhando um serviço de LLM. Os seguintes módulos são adicionados:

Visão geral de dados: Mostra o consumo de tokens e a distribuição do volume de requisições por usuário e departamento. Filtre os dados por intervalo de tempo e dimensão de usuário para ajudar administradores a identificar quem mais consome recursos.
Gerenciamento de usuários: Crie, consulte, atualize e exclua usuários, além de ativá-los ou desativá-los e gerenciar suas API Keys. Também é possível realizar essas operações via API. Para mais detalhes, consulte referência da API de gerenciamento de usuários.
Log de auditoria: Registra operações de gerenciamento, como logins, logouts, modificações de usuários, redefinições de API Key e alterações de configuração. Cada ação registra horário, operador e objeto de recurso. Filtre logs por tempo, tipo de operação e operador para auditorias de conformidade e rastreamento de problemas.
Central do usuário: Os próprios usuários gerenciam seus perfis, visualizam e redefinem suas API Keys, além de revisar estatísticas pessoais de requisições e registros de consumo de tokens.

Os módulos disponíveis para cada função são:

Função	Permissões
usuário comum	chat inteligente, central do usuário (visualizar estatísticas pessoais)
administrador	Todas as permissões de um usuário comum, mais: visão geral de dados (visualizar estatísticas de todos os usuários), Monitoramento em tempo real, centro de configuração (somente leitura)
administrador do sistema	Todas as permissões de um administrador, mais: gerenciamento de usuários, log de auditoria, centro de configuração (leitura e escrita)

Acesse o workbench

Pré-requisitos: Implante um serviço de roteamento inteligente de LLM ou um serviço agregado que inclua esse componente.

Procedimento:

Faça login no PAI console e acesse a aba de serviços de inferência EAS.
Localize o serviço de roteamento inteligente de LLM desejado.
Na coluna Invocation / Logs / Monitoring do serviço, clique em ícone web app.
Na janela pop-up, localize o workbench WebUI e abra o workbench de administração.

Após um administrador criar um usuário na página de gerenciamento de usuários, esse usuário poderá fazer login no workbench WebUI pelo User Login portal usando sua API Key.

Centro de configuração

O centro de configuração permite atualizações a quente nas configurações principais do roteamento inteligente de LLM, que entram em vigor imediatamente sem reinicialização do serviço. O diagrama abaixo ilustra as etapas em que cada configuração é aplicada.

Tipo de configuração	Descrição
política de agendamento	Define a política para agendar requisições em uma instância de inferência. No modo de separação PD, configure políticas distintas para as fases Prefill e Decode.
roteamento de modelo	Direciona requisições para a instância correspondente com base no campo `model` da requisição. Caso não haja correspondência para o modelo, o modelo padrão configurado processará a requisição.
proxy de divisão de tráfego	Encaminha requisições para serviços de API upstream externos configurados, com base em um prefixo de modelo ou peso.
limitação de requisições	Limita a concorrência de requisições de backend. Ao exceder o limite, escolha entre rejeitar as requisições imediatamente ou colocá-las em fila. Defina limites de concorrência separados para o ciclo de vida geral, a fase Prefill e a fase Decode. Serviços externos especificados no proxy de divisão de tráfego, como o DashScope, seguem suas próprias regras de limitação e não sofrem impacto desta configuração.
espelhamento de tráfego	Copia uma porcentagem do tráfego de produção para um endereço de destino. Utilize essa função para validação canário, comparação de desempenho ou coleta de dados, sem afetar a resposta normal.
agendamento global	Quando os recursos de inferência na região atual forem insuficientes, o agendador direcionará o tráfego para instâncias de serviço de inferência em outras regiões ociosas. Isso possibilita o pool de computação global e a reutilização eficiente de recursos.

Referência da API de gerenciamento de usuários

Autenticação: Inclua a API Key do administrador do sistema no cabeçalho de todas as chamadas de API: Authorization: Bearer <admin_api_key>.

Nas chamadas, substitua https://gateway.example.com nos exemplos pelo seu endpoint de roteamento inteligente de LLM, como http://xxx.cn-shanghai.pai-eas.aliyuncs.com/api/predict/ai_assistant.ai_gw.

1. Verificar usuário

Verifica se um usuário existe com base no ID do funcionário.

Requisição: GET /api/users/check?employee_id={employee_id}

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
employee_id	string	Sim	ID do funcionário.

Exemplo:

curl -X GET "https://gateway.example.com/api/users/check?employee_id=12345" \
-H "Authorization: Bearer <admin_api_key>"

2. Criar usuário

Cria um novo usuário e retorna sua API Key.

Requisição: POST /api/users

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do usuário.
email	string	Não	Endereço de e-mail.
employee_id	string	Não	ID do funcionário.
department	string	Não	Departamento.
role	string	Não	Função do usuário. Padrão: `user`. Valor opcional: `admin`.
metadata	object	Não	Informações estendidas.

Exemplo:

curl -X POST "https://gateway.example.com/api/users" \
-H "Authorization: Bearer <admin_api_key>" \
-H "Content-Type: application/json" \
-d '{"name":"John Doe","email":"john.doe@company.com","employee_id":"12345","department":"Engineering"}'

3. Consultar usuários

Recupera informações sobre todos os usuários ou um único usuário.

Requisição:

GET /api/users (recupera todos os usuários)
GET /api/users/{user_id} (recupera um único usuário)

Exemplo:

# Retrieve all users
curl -X GET "https://gateway.example.com/api/users" \
-H "Authorization: Bearer <admin_api_key>"

# Retrieve a single user
curl -X GET "https://gateway.example.com/api/users/user_xxx" \
-H "Authorization: Bearer <admin_api_key>"

4. Redefinir API key

Redefine a API Key de um usuário e retorna a nova chave.

Requisição: POST /api/users/{user_id}/regenerate-key

Exemplo:

curl -X POST "https://gateway.example.com/api/users/user_xxx/regenerate-key" \
-H "Authorization: Bearer <admin_api_key>"

5. Atualizar usuário

Atualiza as informações de um usuário.

Requisição: PUT /api/users/{user_id}

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do usuário.
email	string	Não	Endereço de e-mail.
employee_id	string	Não	ID do funcionário.
department	string	Não	Departamento.
role	string	Não	Função do usuário. Padrão: `user`. Valor opcional: `admin`.
enabled	boolean	Não	Especifica se o usuário está ativo.
metadata	object	Não	Informações estendidas.

Exemplo:

curl -X PUT "https://gateway.example.com/api/users/user_xxx" \
-H "Authorization: Bearer <admin_api_key>" \
-H "Content-Type: application/json" \
-d '{"department":"New Product","email":"john.doe@newcompany.com"}'

6. Excluir usuário

Exclui um usuário específico.

Requisição: DELETE /api/users/{user_id}

Exemplo:

curl -X DELETE "https://gateway.example.com/api/users/user_xxx" \
-H "Authorization: Bearer <admin_api_key>"

7. Provisionamento de usuário

A API de provisionamento cria um novo usuário ou redefine uma API Key e gera um link de provisionamento de uso único. O usuário utiliza esse link para recuperar sua API Key. Em comparação com a criação direta de usuário (POST /api/users), o método de provisionamento oferece maior segurança:

Os usuários recuperam sua API Key por meio de um link dedicado, evitando a transmissão da chave em texto simples.
O link expira automaticamente após 24 horas.
O link pode ser usado apenas uma vez e torna-se inválido após o uso.

7,1 Provisionar um novo usuário

Requisição: POST /api/provision

Exemplo:

curl -X POST "https://gateway.example.com/api/provision" \
  -H "Authorization: Bearer <admin_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john.doe@company.com",
    "employee_id": "12345",
    "department": "Engineering"
  }'

7,2 Redefinir chave via provisionamento

Utilize este método quando um usuário já existir, mas precisar de uma nova API Key.

Requisição: POST /api/provision/reset

Exemplo:

curl -X POST "https://gateway.example.com/api/provision/reset" \
-H "Authorization: Bearer <admin_api_key>" \
-H "Content-Type: application/json" \
-d '{"employee_id":"12345"}'

7,3 Verificar link de provisionamento

Após o usuário abrir o provision_url, a página da web chama este endpoint para verificar o token e recuperar as informações do usuário e a API Key.

Requisição: GET /api/provision/verify?token={token}

8. Fluxos de trabalho típicos

Registro de novo usuário (provisionamento)

O método de provisionamento entrega a API Key por meio de um link de uso único, oferecendo maior segurança.

# 1. Create a user and get the provisioning link.
curl -X POST "https://gateway.example.com/api/provision" \
-H "Authorization: Bearer <admin_api_key>" \
 -H "Content-Type: application/json" \
 -d '{"name":"John Doe","email":"john.doe@company.com","employee_id":"12345","department":"Engineering"}'
# 2. Send the returned provision_url to the user (for example, by email or instant message).

# 3. The user opens the link, and the page automatically calls /api/provision/verify to retrieve the API Key.

Registro de novo usuário (criação direta)

# 1. Check if the user already exists.
curl -X GET "https://gateway.example.com/api/users/check?employee_id=12345" \
-H "Authorization: Bearer <admin_api_key>"

# 2. If the user does not exist, create the user.
curl -X POST "https://gateway.example.com/api/users" \
-H "Authorization: Bearer <admin_api_key>" \
-H "Content-Type: application/json" \
-d '{"name":"John Doe","employee_id":"12345","department":"Engineering"}'

# 3. Send the returned api_key to the user.

Desligamento de usuário (desativar ou excluir)

# Disable the user (recommended).
curl -X PUT "https://gateway.example.com/api/users/user_xxx" \
-H "Authorization: Bearer <admin_api_key>" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'

# Alternatively, delete the user.
curl -X DELETE "https://gateway.example.com/api/users/user_xxx" \
-H "Authorization: Bearer <admin_api_key>"

Recuperar API key (provisionamento)

# Reset the key by employee ID and send a new provisioning link.
curl -X POST "https://gateway.example.com/api/provision/reset" \
-H "Authorization: Bearer <admin_api_key>" \
-H "Content-Type: application/json" \
-d '{"employee_id":"12345"}'

# Send the returned provision_url to the user.

Recuperar API key (redefinição direta)

# Check for the user by employee ID.
curl -X GET "https://gateway.example.com/api/users/check?employee_id=12345" \
-H "Authorization: Bearer <admin_api_key>"

# Use the returned user_id to reset the API Key.
curl -X POST "https://gateway.example.com/api/users/user_xxx/regenerate-key" \
-H "Authorization: Bearer <admin_api_key>"

Perguntas frequentes

P: Por que a taxa de acerto de cache está em 0% no workbench?

R: Essa métrica exige que o serviço de inferência reporte dados de acerto de cache durante a execução. Verifique se o comando de inicialização do serviço EAS alvo inclui o parâmetro --enable-cache-report. Sem esse parâmetro, o workbench não consegue coletar os dados, fazendo com que a taxa de acerto de cache seja exibida como 0%, mesmo que ocorram acertos de cache.