Training gRPC API

The Training gRPC API contains methods for compiling wordsets.

The Training service is available to Mix users who create resources using https://mix.nuance.com  and access them using the asr.api.nuance.com ASR endpoint. It is not available in other geographies.

Proto file structure

ASRaaS provides protocol buffer (.proto) files to define Nuance’s gRPC wordset training service. These files allow you to compile and manage large wordsets for use with your ASRaaS applications. See gRPC setup to download these files.

• training.proto contains the methods and messages for working with large wordsets.
• The RPC files contain status and error messages.

You may use these proto files in conjunction with the other ASRaaS proto files described in the Recognizer API.

└── nuance
    ├── asr
    │   ├── v1
    │   │   ├── recognizer.proto
    │   │   ├── resource.proto
    │   │   └── result.proto
    │   └── v1beta1
    │       └── training.proto
    └── rpc (RPC message files)

The proto files define a Training service with several RPC methods for creating and managing compiled wordsets. Details about each component are referenced by name within the proto file.

  Fields in wordset training request  

For the RPC fields, see RPC gRPC messages.

Job status vs. request status

This API includes two types of status:

• Job status: The condition of the job that is compiling the wordset. Its values are set in JobStatus and can be JOB_STATUS_QUEUED, JOB_STATUS_PROCESSING, JOB_STATUS_COMPLETE, or JOB_STATUS_FAILED.

• Request status:The condition of the gRPC request. Its values are set in nuance.rpc.Status and can be OK, INVALID_REQUEST, NOT_FOUND, ALREADY_EXISTS, and so on.

This report on an ongoing job combines job status and request status:

2021-04-05 16:41:28,369 INFO : Received response: job_status_update {
  job_id: "c21b0be0-964e-11eb-9e4a-5fb8e278d1ad"
  status: JOB_STATUS_PROCESSING
}
request_status {
  status_code: OK
  http_trans_code: 200
}

2021-04-05 16:41:28,896 INFO : new server stream count 2
2021-04-05 16:41:28,896 INFO : Received response: job_status_update {
  job_id: "c21b0be0-964e-11eb-9e4a-5fb8e278d1ad"
  status: JOB_STATUS_COMPLETE
}
request_status {
  status_code: OK
  http_trans_code: 200
}

Training service

The Training service offers five RPC methods to compile and manage wordsets. Each method consists of a request and a response message.

For examples of using all these methods, see Sample training client.

CompileWordsetAndWatch

This RPC method submits a request to compile a wordset and returns streaming messages from the server until the job completes. It consists of CompileWordsetRequest and WatchJobStatusResponse. The response is a server stream of job progress notifications, which stays alive until the end of the compilation job, followed by a final job status.

The CompileWordsetAndWatch method consists of:

CompileWordsetRequest
  wordset
  companion_artifact_reference (ResourceReference)
  target_artifact_reference (ResourceReference)
  metadata
  client_data
WatchJobStatusResponse
  job_status_update (JobStatusUpdate)
  request_status (nuance.rpc.Status)

  CompileWordsetAndWatch process flow  

def send_compilewordsetandwatch_request(grpc_client, request, metadata=None):
    log.info("Sending CompileWordsetAndWatch request")

    metadata = []
    client_span = None
    train_span = None
    count_stream = 0

    global total_train_request
    total_train_request = total_train_request + 1

    global args

    thread_context.num_train_request = thread_context.num_train_request + 1

    if args.wsFile:
        log.info("Override the inline wordset with input file [%s]" % args.wsFile)
        request.wordset = open(args.wsFile, 'rb').read()

    if args.meta:
        with open(args.meta if type(args.meta)is str else '.metadata', 'r') as meta_file:
            for n, line in enumerate(meta_file):
                header, value = line.split(':', 1)
                metadata.append((header.strip(), value.strip()))

    if args.nmaid:
        metadata.append(('x-nuance-client-id', args.nmaid))

    if args.jaeger:
        log.debug("Injecting Jaeger span context into request")
        client_span = tracer.start_span("Client.gRPC")
        train_span = tracer.start_span(
            "Client.Training", child_of=client_span)
        carrier = dict()
        tracer.inject(train_span.context,
                      opentracing.propagation.Format.TEXT_MAP, carrier)
        metadata.append(('uber-trace-id', carrier['uber-trace-id']))

    start = time.monotonic()
    log.info("Sending request: {}".format(request))
    log.info("Sending metadata: {}".format(metadata))
    responses = grpc_client.CompileWordsetAndWatch(request=request, metadata=metadata)
    for response in responses:
      count_stream = count_stream + 1
      log.info("new server stream count {}".format(count_stream))
      log.info("Received response: {}".format(response))
    latency = time.monotonic() - start
    global total_first_chunk_latency
    total_first_chunk_latency = total_first_chunk_latency + latency

    log.info("First chunk latency: {} seconds".format(latency))

    if train_span:
        train_span.finish()
    if client_span:
        client_span.finish()

from nuance.asr.v1beta1.training_pb2 import *

list_of_requests = []

request = CompileWordsetRequest()

request.companion_artifact_reference.uri = "urn:nuance-mix:tag:model/names-places/mix.asr?=language=eng-USA"
request.target_artifact_reference.uri = "urn:nuance-mix:tag:wordset:lang/names-places/places-compiled-ws/eng-USA/mix.asr"
request.wordset = '{"cityqa":[{"literal":"La Jolla","spoken":["la hoya","la jolla"]},{"literal":"Llanfairpwllgwyngyll","spoken":["lan vire pool guin gill", "lan fair"]},{"literal":"Abington Pigotts"},{"literal":"Steeple Morden"},{"literal":"Hoyland Common"},{"literal":"Cogenhoe","spoken":["cook no"]},{"literal":"Fordoun","spoken":["forden","fordoun"]},{"literal":"Llangollen","spoken":["lan goth lin","lan gollen"]},{"literal":"Auchenblae"}]}'
request.metadata['app_os'] = 'CentOS'

#Add request to list
list_of_requests.append(request)
# ---

CompileWordsetRequest

Request to compile a wordset. The request message has a maximum size of 4 MB. See Sample training client for examples.

ResourceReference

Definition of an external resource: either a domain LM containing an entity that the wordset extends, or a compiled wordset. See also Wordsets.

The format of the URN reference depends on the message and resource. In these examples, the language is eng-USA.

• DLM in companion_artifact_reference. The DLM must exist in the Mix environment under the specified context tag.
  urn:nuance-mix:tag:model/context_tag/mix.asr?=language=eng-USA

• Wordset in target_artifact_reference, with an application-level wordset. The context tag is either an existing tag used for DLMs or wordsets, or a new tag that will be created. The wordset name is a new name for the compiled wordset being created:
  urn:nuance-mix:tag:wordset:lang/context_tag/wordset_name/eng-USA/mix.asr

• Or a user wordset:
  urn:nuance-mix:tag:wordset:lang/context_tag/wordset_name/eng-USA/mix.asr?=user_id=<user_id>

WatchJobStatusResponse

Server stream information about a compilation job in progress.

Response to CompileWordsetRequest. This response is streamed from the server, giving information about the compilation job as it progresses.

WatchJobStatusResponse returns these notifications:

• Job ID.

• Multiple responses with JOB_STATUS_QUEUED or ~PROCESSING. The same status may be returned multiple times. Repeated notifications also keep the process alive.

• Final job status (JOB_STATUS_COMPLETE or ~FAILED) with error messages when appropriate.

• Final request status, either OK for successful requests, or INVALID_REQUEST and similar for others. This status refers to the request itself, not the wordset compile job that was created. See Job status vs. request status.

Invalid requests do not create a job, so the notification stream consists only of the request status.

JobStatusUpdate

Job status update to a request.

JobStatus

Job status as a keyword. See Job status vs. request status.

JobMessage

Message about the job in progress.

GetWordsetMetadata

This RPC method requests and returns information about a compiled wordset. This method consists of GetWordsetMetadataRequest and ~Response.

The GetWordsetMetadata method consists of:

GetWordsetMetadataRequest
  artifact_reference (ResourceReference)
GetWordsetMetadataResponse
  metadata
  request_status (nuance.rpc.Status)

  GetWordsetMetadata process flow  

def send_getwordsetmetadata_request(grpc_client, request, metadata=None):
    log.info("Sending GetWordsetMetadata request")

    metadata = []

    if args.meta:
        with open(args.meta if type(args.meta)is str else '.metadata', 'r') as meta_file:
            for n, line in enumerate(meta_file):
                header, value = line.split(':', 1)
                metadata.append((header.strip(), value.strip()))

    if args.nmaid:
        metadata.append(('x-nuance-client-id', args.nmaid))

    log.info("Sending request: {}".format(request))
    log.info("Sending metadata: {}".format(metadata))
    response = grpc_client.GetWordsetMetadata(request=request, metadata=metadata)
    log.info("Received response: {}".format(response))

from nuance.asr.v1beta1.training_pb2 import *

list_of_requests = []

request = GetWordsetMetadataRequest()
request.artifact_reference.uri = "urn:nuance-mix:tag:wordset:lang/names-places/places-compiled-ws/eng-USA/mix.asr"

#Add request to list
list_of_requests.append(request)
# ---

GetWordsetMetadataRequest

Request for information about a compiled wordset.

GetWordsetMetadataResponse

Response information about a compiled wordset.

GetWordsetMetadataResponse does not return the JSON content of the wordset. It provides two types of metadata:

• Custom metadata, optionally supplied by the client as metadata in CompileWordsetRequest.

• Default metadata (reserved keys):

  x_nuance_companion_checksum_sha256: The companion DLM, SHA256 hash in hex format.

  x_nuance_wordset_content_checksum_sha256: The source wordset content, SHA256 hash in hex format.

  x_nuance_compiled_wordset_checksum_sha256: The compiled wordset, SHA256 hash in hex format.

  x_nuance_compiled_wordset_last_update: Date and time of last update as ISO 8601 UTC date.

DeleteWordset

This RPC method removes a wordset from storage. It consists of DeleteWordsetRequest and ~Response.

The DeleteWordset method consists of:

DeleteWordsetRequest
  artifact_reference (ResourceReference)
DeleteWordsetResponse
  job_status_update
  job_status

  DeleteWordset process flow  

def send_deletewordset_request(grpc_client, request, metadata=None):
    log.info("Sending DeleteWordset request")

    metadata = []

    if args.meta:
        with open(args.meta if type(args.meta)is str else '.metadata', 'r') as meta_file:
            for n, line in enumerate(meta_file):
                header, value = line.split(':', 1)
                metadata.append((header.strip(), value.strip()))

    if args.nmaid:
        metadata.append(('x-nuance-client-id', args.nmaid))

    log.info("Sending request: {}".format(request))
    log.info("Sending metadata: {}".format(metadata))
    response = grpc_client.DeleteWordset(request=request, metadata=metadata)
    log.info("Received response: {}".format(response))

from nuance.asr.v1beta1.training_pb2 import *

list_of_requests = []

request = DeleteWordsetRequest()
request.artifact_reference.uri = "urn:nuance-mix:tag:wordset:lang/names-places/places-compiled-ws/eng-USA/mix.asr"

#Add request to list
list_of_requests.append(request)
# ---

DeleteWordsetRequest

Request to delete a compiled wordset.

DeleteWordsetResponse

Response to the delete request.

Scalar value types