Alibaba Cloud Model Studio:Référence du SDK Java pour les mots chauds personnalisés

Utilisez le SDK Java pour créer, interroger, mettre à jour et supprimer des vocabulaires personnalisés destinés à la reconnaissance vocale.

Guide d'utilisation : Améliorer la précision de la reconnaissance.

Endpoint

Le SDK utilise l'endpoint Chine (Pékin) par défaut. Pour changer de région, modifiez Constants.baseHttpApiUrl avant l'initialisation.

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

Remplacez {WorkspaceId} par votre ID d'espace de travail.

China (Beijing)

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

Remplacez {WorkspaceId} par votre ID d'espace de travail.

Pour utiliser la région Singapour, définissez Constants.baseHttpApiUrl avant l'initialisation :

import com.alibaba.dashscope.utils.Constants;

// Set this at the beginning of your code
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Remarque :

• Les clés API diffèrent selon les régions. Utilisez la clé API correspondant à votre région.
• Le paramètre de région est global et s'applique à tous les appels API DashScope.

VocabularyService

Package : com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService

Description : crée, interroge, met à jour et supprime des vocabulaires personnalisés.

Constructeur

public VocabularyService(String apiKey)

Paramètres :

Paramètre	Type	Description
apiKey	String	Clé API DashScope

createVocabulary() - Créer un vocabulaire personnalisé

Signature de la méthode :

public Vocabulary createVocabulary(String targetModel,String prefix,JsonArray vocabulary) throws NoApiKeyException, InputRequiredException

Paramètres :

Paramètre	Type	Obligatoire	Description
targetModel	String	Oui	Modèle de reconnaissance vocale utilisant ce vocabulaire. Cette valeur doit correspondre au modèle spécifié lors de l'appel à l'API de reconnaissance vocale.
prefix	String	Oui	Préfixe personnalisé pour le vocabulaire. Seules les lettres minuscules et les chiffres sont autorisés, avec une longueur maximale de 10 caractères.
vocabulary	JsonArray	Oui	Liste des mots chauds. Chaque JsonObject contient des champs tels que text, weight et lang. Pour plus d'informations, consultez Structure de l'objet mot chaud.

Valeur de retour :

Type	Description
Vocabulary	Objet de vocabulaire personnalisé contenant l'ID du vocabulaire et d'autres métadonnées.

Exceptions :

Exception	Description
NoApiKeyException	La clé API est vide.
InputRequiredException	Un paramètre obligatoire est vide.

listVocabulary() - Lister les vocabulaires personnalisés

Signature de la méthode :

public Vocabulary[] listVocabulary(String prefix) throws NoApiKeyException, InputRequiredException

public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

Paramètres :

Paramètre	Type	Obligatoire	Description
prefix	String	Non	Préfixe personnalisé du vocabulaire. Si spécifié, seuls les vocabulaires portant ce préfixe sont retournés.
pageIndex	int	Non	Numéro de page, commençant à 0. Valeur par défaut : 0.
pageSize	int	Non	Nombre d'entrées par page. Valeur par défaut : 10.

Valeur de retour :

Type	Description
Vocabulary[]	Tableau d'objets de vocabulaire personnalisé.

Champs retournés par listVocabulary() :

Champ	Type	Description
vocabularyId	String	ID du vocabulaire.
gmtCreate	String	Date de création.
gmtModified	String	Date de dernière modification.
status	String	État du vocabulaire : OK : Prêt. UNDEPLOYED : Non disponible.

Exceptions :

Exception	Description
NoApiKeyException	La clé API est vide.
InputRequiredException	Un paramètre obligatoire est vide.

queryVocabulary() - Interroger un vocabulaire personnalisé

Signature de la méthode :

public Vocabulary queryVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

Paramètres :

Paramètre	Type	Obligatoire	Description
vocabularyId	String	Oui	ID du vocabulaire personnalisé à interroger.

Valeur de retour :

Type	Description
Vocabulary	Objet Vocabulary contenant les entrées de mots chauds et les métadonnées.

Champs retournés par queryVocabulary() :

Champ	Type	Description
vocabulary	JsonArray	Contenu du vocabulaire personnalisé.
targetModel	String	Modèle de reconnaissance vocale utilisant ce vocabulaire. Cette valeur doit correspondre au modèle spécifié lors de l'appel à l'API de reconnaissance vocale.
gmtCreate	String	Date de création.
gmtModified	String	Date de dernière modification.
status	String	État du vocabulaire : OK : Prêt. UNDEPLOYED : Non disponible.

Exceptions :

Exception	Description
NoApiKeyException	La clé API est vide.
InputRequiredException	Un paramètre obligatoire est vide.

updateVocabulary() - Mettre à jour un vocabulaire personnalisé

Signature de la méthode :

public void updateVocabulary(String vocabularyId,JsonArray vocabulary) throws NoApiKeyException, InputRequiredException

Paramètres :

Paramètre	Type	Obligatoire	Description
vocabularyId	String	Oui	ID du vocabulaire à mettre à jour.
vocabulary	JsonArray	Oui	Nouveau vocabulaire. Ce contenu remplace intégralement les entrées existantes.

Valeur de retour : Aucune

Exceptions :

Exception	Description
NoApiKeyException	La clé API est vide.
InputRequiredException	Un paramètre obligatoire est vide.

deleteVocabulary() - Supprimer un vocabulaire personnalisé

Signature de la méthode :

public void deleteVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

Paramètres :

Paramètre	Type	Obligatoire	Description
vocabularyId	String	Oui	ID du vocabulaire à supprimer.

Valeur de retour : Aucune

Exceptions :

Exception	Description
NoApiKeyException	La clé API est vide.
InputRequiredException	Un paramètre obligatoire est vide.

Classe Vocabulary

Package : com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary

Description : stocke les métadonnées et le contenu d'un vocabulaire personnalisé.

Méthodes

Méthode	Type de retour	Description
getVocabularyId()	String	Retourne l'ID du vocabulaire.
getTargetModel()	String	Retourne le modèle cible.
getVocabulary()	JsonArray	Retourne le contenu du vocabulaire personnalisé.
getStatus()	String	Retourne l'état.
getGmtCreate()	String	Retourne la date de création.
getGmtModified()	String	Retourne la date de dernière modification.
getData()	JsonObject	Retourne les données complètes au format JSON.

Structure de l'objet mot chaud

Champs de chaque JsonObject de mot chaud :

Champ	Type	Obligatoire	Description
text	String	Oui	Texte de l'entrée du vocabulaire. La langue du texte doit être prise en charge par le modèle sélectionné. Les langues compatibles varient selon le modèle. Utilisez des mots réels plutôt que des combinaisons de caractères arbitraires afin d'améliorer la précision de la reconnaissance. Longueur maximale : 15 caractères pour un texte contenant des caractères non ASCII, ou 7 mots séparés par des espaces pour un texte exclusivement ASCII.
weight	int	Oui	Poids de l'entrée du vocabulaire. Valeur recommandée : 4. Valeurs valides : de 1 à 5. Si la précision de la reconnaissance ne s'améliore pas, augmentez le poids. Un poids excessivement élevé risque de réduire la précision de reconnaissance des autres mots.
lang	String	Non	Code de langue de l'audio à reconnaître. Lorsque ce paramètre est défini, le système améliore la reconnaissance des entrées de vocabulaire dans la langue spécifiée. Si vous ne pouvez pas déterminer la langue à l'avance, laissez ce paramètre vide. Le modèle détecte alors la langue automatiquement. Valeurs valides (variables selon le modèle) : Paraformer : zh : Chinois en : Anglais ja : Japonais yue : Cantonais ko : Coréen de : Allemand fr : Français ru : Russe Fun-ASR : zh : Chinois en : Anglais ja : Japonais

Exemples de code

Créer un vocabulaire personnalisé

import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.util.ArrayList;
import java.util.List;

public class Main {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio API key: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        String targetModel = "fun-asr";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        wordList.add(new Hotword("Wu yi gong", 4));
        wordList.add(new Hotword("A Family in Queli", 4));

        for (Hotword word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("weight", word.weight);
            vocabularyJson.add(jsonObject);
        }

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary vocabulary = service.createVocabulary(targetModel, "testpfx", vocabularyJson);
        System.out.println("Custom vocabulary ID: " + vocabulary.getVocabularyId());
    }
}

class Hotword {
    String text;
    int weight;

    public Hotword(String text, int weight) {
        this.text = text;
        this.weight = weight;
    }
}

Lister les vocabulaires personnalisés

import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class Main {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio API key: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary[] vocabularies = service.listVocabulary("testpfx");
        Gson gson = new GsonBuilder()
                .setPrettyPrinting()
                .create();
        System.out.println("Custom vocabularies: " + gson.toJson(vocabularies));
    }
}

Interroger un vocabulaire personnalisé

import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class Main {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio API key: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        // Replace with the actual custom vocabulary ID when querying
        Vocabulary vocabulary = service.queryVocabulary("vocab-testpfx-xxxx");
        Gson gson = new GsonBuilder()
                .setPrettyPrinting()
                .create();
        System.out.println("Custom vocabulary: " + gson.toJson(vocabulary.getData()));
    }
}

Mettre à jour un vocabulaire personnalisé

import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.util.ArrayList;
import java.util.List;

public class Main {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio API key: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        wordList.add(new Hotword("Wu yi gong", 4, "en"));
        wordList.add(new Hotword("A Family in Queli", 4, "en"));

        for (Hotword word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("weight", word.weight);
            jsonObject.addProperty("lang", word.lang);
            vocabularyJson.add(jsonObject);
        }

        VocabularyService service = new VocabularyService(apiKey);
        // Replace with the actual custom vocabulary ID
        service.updateVocabulary("vocab-testpfx-xxx", vocabularyJson);
    }
}

class Hotword {
    String text;
    int weight;
    String lang;

    public Hotword(String text, int weight, String lang) {
        this.text = text;
        this.weight = weight;
        this.lang = lang;
    }
}

Supprimer un vocabulaire personnalisé

import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    // The API keys for the Singapore and Beijing regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If no environment variable is configured, replace the following line with your Model Studio API key: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        // Replace with the actual vocabulary ID when deleting
        service.deleteVocabulary("vocab-testpfx-xxxx");
    }
}