Skip to main content

Referência do SDK Python para palavras-chave personalizadas

Use o SDK Python para criar, listar, consultar, atualizar e excluir vocabulários personalizados de reconhecimento de fala.

O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Pequim) e Singapura. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade nas solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Pequim): de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Substitua {WorkspaceId} pelo seu ID do Workspace real. Os domínios existentes permanecem totalmente funcionais.
Guia do usuário: Melhorar a precisão do reconhecimento.
Vocabulários personalizados são compatíveis apenas no workspace principal. Sub-workspaces não oferecem suporte a esse recurso.

Endpoint

Por padrão, o SDK conecta-se ao endpoint da China (Pequim). Para usar outra região, especifique o parâmetro region ao construir o dashscope.Client (por exemplo, ap-southeast-1 para a região de Singapura).
  • China (Pequim)
  • Singapura
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1Substitua {WorkspaceId} pelo seu ID do workspace real.
  • Singapura
  • China (Pequim)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Substitua {WorkspaceId} pelo seu ID do Workspace real.
Para alternar para a região de Singapura:
import os
import dashscope

# Especifique a região ao construir o Client
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)
Nota:
  • As chaves de API variam conforme a região. Use a chave correspondente à sua região.
  • A configuração de região é uma definição em nível de instância do dashscope.Client e afeta apenas as chamadas de API feitas por esse client.

client.audio.vocabularies

Entrada do recurso: recurso client.audio.vocabularies da instância dashscope.Client Descrição: gerencie o ciclo de vida dos vocabulários personalizados (criação, consulta, atualização e exclusão).

Construção

import os
import dashscope

client = dashscope.Client(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)
Se api_key não for passado, o SDK lerá automaticamente o valor da variável de ambiente DASHSCOPE_API_KEY.

create() - Criar um vocabulário personalizado

Assinatura do método:
def create(
    self,
    *,
    target_model: str,
    prefix: str,
    vocabulary: List[dict]) -> Vocabulary
Parâmetros:

Parâmetro

Tipo

Obrigatório

Descrição

target_model

str

Sim

Modelo de reconhecimento de fala que usa este vocabulário. Este valor deve corresponder exatamente ao modelo especificado na chamada da API de reconhecimento de fala.

prefix

str

Sim

Prefixo personalizado para o vocabulário. Aceita apenas letras minúsculas e dígitos, com limite de 10 caracteres.

vocabulary

List[dict]

Sim

Lista de palavras-chave. Cada entrada é um dicionário com os campos text, weight e lang.

Para mais detalhes, consulte Estrutura do dicionário de palavras-chave.

Valor de retorno:

Tipo

Descrição

Vocabulary

Objeto de vocabulário; obtenha o ID do vocabulário criado pelo campo vocabulary_id.

list() - Listar vocabulários personalizados

Corresponde à ação da API HTTP action: list_vocabulary. Assinatura do método:
def list(
    self,
    *,
    prefix: str = None,
    page_index: int = 0,
    page_size: int = 10) -> VocabularyList
Parâmetros:

Parâmetro

Tipo

Obrigatório

Descrição

prefix

str

Não

Prefixo personalizado do vocabulário. Se especificado, a resposta incluirá apenas vocabulários com este prefixo.

page_index

int

Não

Número da página, começando em 0.

Valor padrão: 0.

page_size

int

Não

Quantidade de itens por página.

Valor padrão: 10.

Valor de retorno:

Tipo

Descrição

VocabularyList

Objeto de paginação de vocabulários; o campo vocabularies é uma matriz com as informações dos vocabulários, contendo vocabulary_id, gmt_create, gmt_modified e status.

Campos retornados por list():

Campo

Tipo

Descrição

vocabulary_id

str

ID do vocabulário.

gmt_create

str

Data e hora de criação.

gmt_modified

str

Data e hora da última modificação.

status

str

Status:

  • OK: Pronto.

  • UNDEPLOYED: Indisponível.

get() - Consultar um vocabulário personalizado

Corresponde ao query_vocabulary() do SDK 1.x. Assinatura do método:
def get(
    self,
    vocabulary_id: str) -> Vocabulary
Parâmetros:

Parâmetro

Tipo

Obrigatório

Descrição

vocabulary_id

str

Sim

ID do vocabulário personalizado a consultar.

Valor de retorno:

Tipo

Descrição

Vocabulary

Objeto com os detalhes do vocabulário, contendo vocabulary, target_model, gmt_create, gmt_modified e status.

Campos retornados por get():

Campo

Tipo

Descrição

vocabulary

List[dict]

Conteúdo da lista de palavras-chave.

target_model

str

Modelo de reconhecimento de fala que usa este vocabulário. Este valor deve corresponder exatamente ao modelo especificado na chamada da API de reconhecimento de fala.

gmt_create

str

Data e hora de criação.

gmt_modified

str

Data e hora da última modificação.

status

str

Status:

  • OK: Pronto.

  • UNDEPLOYED: Indisponível.

update() - Atualizar um vocabulário personalizado

Assinatura do método:
def update(
    self,
    vocabulary_id: str,
    *,
    vocabulary: List[dict]) -> JobStatus
Parâmetros:

Parâmetro

Tipo

Obrigatório

Descrição

vocabulary_id

str

Sim

ID do vocabulário a atualizar.

vocabulary

List[dict]

Sim

Novo vocabulário. Esta lista substitui integralmente as entradas existentes.

Valor de retorno: objeto JobStatus; o campo status indica o estado da operação.

delete() - Excluir um vocabulário personalizado

Assinatura do método:
def delete(
    self,
    vocabulary_id: str) -> JobStatus
Parâmetros:

Parâmetro

Tipo

Obrigatório

Descrição

vocabulary_id

str

Sim

ID do vocabulário a excluir.

Valor de retorno: objeto JobStatus; o campo status indica o estado da operação.

Estrutura do dicionário de palavras-chave

Campos em cada dicionário de vocabulário:

Campo

Tipo

Obrigatório

Descrição

text

str

Sim

Texto da entrada do vocabulário.

O idioma do texto deve ser compatível com o modelo selecionado. Os idiomas suportados variam conforme o modelo.

Use palavras reais em vez de combinações arbitrárias de caracteres para aumentar a precisão do reconhecimento.

Limite máximo: 15 caracteres para textos com caracteres não ASCII ou 7 palavras separadas por espaços para textos exclusivamente ASCII.

weight

int

Sim

Peso da entrada do vocabulário. Valor recomendado: 4.

Valores válidos: 1 a 5.

Se a precisão do reconhecimento não melhorar, aumente o peso. Um peso excessivamente alto pode reduzir a precisão no reconhecimento de outras palavras.

lang

str

Não

Código do idioma do áudio a reconhecer. Quando definido, o sistema aprimora o reconhecimento das entradas do vocabulário no idioma especificado. Caso não seja possível determinar o idioma antecipadamente, deixe este parâmetro indefinido. O modelo detecta o idioma automaticamente.

Valores válidos (variam conforme o modelo):

  • Paraformer:

    • zh: Chinês

    • en: Inglês

    • ja: Japonês

    • yue: Cantonês

    • ko: Coreano

    • de: Alemão

    • fr: Francês

    • ru: Russo

  • Fun-ASR:

    • zh: Chinês

    • en: Inglês

    • ja: Japonês

Exemplos de código

Todos os exemplos leem a chave de API de uma variável de ambiente.

Criar um vocabulário personalizado

import os
import dashscope

# As API Keys das regiões Singapura e China (Pequim) não são intercambiáveis. Obtenha sua API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # A configuração abaixo refere-se à região Singapura (ap-southeast-1). Ao chamar, substitua {WorkspaceId} pelo ID real do seu workspace. A configuração varia conforme a região.
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

prefix = 'testpfx'
target_model = "fun-asr"

my_vocabulary = [
    {"text": "Seediq Bale", "weight": 4}
]

# Crie o vocabulário
vocabulary = client.audio.vocabularies.create(
    prefix=prefix,
    target_model=target_model,
    vocabulary=my_vocabulary)

print(f"ID do vocabulário: {vocabulary.vocabulary_id}")

Listar vocabulários personalizados

import json
import os
import dashscope

# As API Keys das regiões Singapura e China (Pequim) não são intercambiáveis. Obtenha sua API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # A configuração abaixo refere-se à região Singapura (ap-southeast-1). Ao chamar, substitua {WorkspaceId} pelo ID real do seu workspace. A configuração varia conforme a região.
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

result = client.audio.vocabularies.list()
print(f"Vocabulários: {json.dumps(result.vocabularies)}")

Consultar um vocabulário personalizado

import json
import os
import dashscope

# As API Keys das regiões Singapura e China (Pequim) não são intercambiáveis. Obtenha sua API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # A configuração abaixo refere-se à região Singapura (ap-southeast-1). Ao chamar, substitua {WorkspaceId} pelo ID real do seu workspace. A configuração varia conforme a região.
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

# Substitua pelo ID real do vocabulário ao consultar
vocabulary = client.audio.vocabularies.get("vocab-testpfx-xxx")
print(f"Vocabulário: {json.dumps(vocabulary.vocabulary, ensure_ascii=False)}")

Atualizar um vocabulário personalizado

import os
import dashscope

# As API Keys das regiões Singapura e China (Pequim) não são intercambiáveis. Obtenha sua API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # A configuração abaixo refere-se à região Singapura (ap-southeast-1). Ao chamar, substitua {WorkspaceId} pelo ID real do seu workspace. A configuração varia conforme a região.
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

my_vocabulary = [
    {"text": "Seediq Bale", "weight": 4, "lang": "en"}
]
# Substitua pelo ID real do vocabulário
result = client.audio.vocabularies.update("vocab-testpfx-xxx", vocabulary=my_vocabulary)
print(f"Status da atualização: {result.status}")

Excluir um vocabulário personalizado

import os
import dashscope

# As API Keys das regiões Singapura e China (Pequim) não são intercambiáveis. Obtenha sua API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # A configuração abaixo refere-se à região Singapura (ap-southeast-1). Ao chamar, substitua {WorkspaceId} pelo ID real do seu workspace. A configuração varia conforme a região.
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

# Substitua pelo ID real do vocabulário
result = client.audio.vocabularies.delete("vocab-testpfx-xxxx")
print(f"Status da exclusão: {result.status}")