监视添加语料库请求

如果语料库有效，服务会返回 201 响应代码。 然后，它以异步方式处理语料库的内容。 在服务对当前请求的语料库的分析完成之前，无法提交向定制模型添加数据或训练模型的请求。

要确定分析的状态，请使用 GET /v1/customizations/{customization_id}/corpora/{corpus_name} 方法来轮询语料库的状态。 此方法接受模型的标识和语料库的名称，如以下示例中所示：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}/corpora/corpus1"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}/corpora/corpus1"

回答包括语料库的状态。 由于定制模型基于先前生成的模型，因此响应将显示 OOV 字数。

{
  "name": "corpus1",
  "total_words": 5037,
  "out_of_vocabulary_words": 401,
  "status": "analyzed"
}

status 字段具有下列其中一个值：

• analyzed 指示服务已成功分析语料库。
• being_processed 指示服务仍在分析语料库。
• undetermined 指示服务在处理语料库时遇到错误。

使用循环每 10 秒检查一次语料库的状态，直到它变为 analyzed。 有关检查模型的语料库状态的更多信息，请参阅列出定制语言模型的语料库。

使用 POST 方法添加词

POST /v1/customizations/{customization_id}/words 方法一次添加一个或多个单词。 通过请求主体或从文件传递要添加为 JSON 数据的词。 无论哪种情况，所需的 Content-Type 标头都指定了JSON数据正在传递给该方法。

以下示例在指定ID的自定义模型中添加了两个自定义单词：HHonors 和 IEEE：

• 第一个示例通过请求主体传递有关每个单词的信息:

  IBM Cloud

  curl -X POST -u "apikey:{apikey}" \
  --header "Content-Type: application/json" \
  --data "{\"words\": [ \
     {\"word\": \"HHonors\", \"sounds_like\": [\"hilton honors\", \"H. honors\"], \"display_as\": \"HHonors\"}, \
     {\"word\": \"IEEE\", \"sounds_like\": [\"I. triple E.\"]}]}" \
  "{url}/v1/customizations/{customization_id}/words"
  

  IBM Cloud Pak for Data IBM Software Hub

  curl -X POST \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data "{\"words\": [ \
    {\"word\": \"HHonors\", \"sounds_like\": [\"hilton honors\", \"H. honors\"], \"display_as\": \"HHonors\"}, \
    {\"word\": \"IEEE\", \"sounds_like\": [\"I. triple E.\"]}]}" \
  "{url}/v1/customizations/{customization_id}/words"
  

• 第二个示例从名为 words.json 的文件添加相同的词:

  {
    "words": [
      {"word": "HHonors", "sounds_like": ["hilton honors", "H. honors"], "display_as": "HHonors"},
      {"word": "IEEE", "sounds_like": ["I. triple E."]}
    ]
  }
  

  以下请求将文件中的文字添加进来：

  IBM Cloud

  curl -X POST -u "apikey:{apikey}" \
  --header "Content-Type: application/json" \
  --data-binary @words.json \
  "{url}/v1/customizations/{customization_id}/words"
  

  IBM Cloud Pak for Data IBM Software Hub

  curl -X POST \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data-binary @words.json \
  "{url}/v1/customizations/{customization_id}/words"
  

POST 方法是非同步的。 可能需要大约几分钟时间才能完成。 完成所需的时间取决于添加的词数和服务上的当前负载。 有关检查该操作的状态的更多信息，请参阅监视添加词请求。

使用 PUT 方法添加词

PUT /v1/customizations/{customization_id}/words/{word_name} 方法可添加单个词。 您传递一个JSON对象作为请求正文，其中包含单词的相关信息。

以下示例将词 NCAA 添加到具有指定标识的模型。 所需的 Content-Type 标头再次表明JSON数据正在传递给该方法。

IBM Cloud

curl -X PUT -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"sounds_like\": [\"N. C. A. A.\", \"N. C. double A.\"]}" \
"{url}/v1/customizations/{customization_id}/words/NCAA"

IBM Cloud Pak for Data IBM Software Hub

curl -X PUT \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"sounds_like\": [\"N. C. A. A.\", \"N. C. double A.\"]}" \
"{url}/v1/customizations/{customization_id}/words/NCAA"

PUT 方法是同步的。 服务会返回响应代码，以立即报告请求是成功还是失败。

监视添加词请求

使用 POST /v1/customizations/{customization_id}/words 方法时，如果输入数据有效，服务会返回 201 响应代码。 然后，服务会异步处理这些词以将其添加到模型中。 在服务完成添加新词的请求之前，无法提交向定制模型添加数据或训练模型的请求。

要确定请求的状态，请使用 GET /v1/customizations/{customization_id} 方法来轮询模型的状态。 此方法接受模型的定制标识，如以下示例中所示:

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"

请求包含有关模型状态的信息:

{
  "customization_id": "74f4807e-b5ff-4866-824e-6bba1a84fe96",
  "created": "2016-06-01T18:42:25.324Z",
  "updated": "2016-06-01T18:45:11.737Z",
  "language": "en-US",
  "dialect": "en-US",
  "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
  "name": "Example model",
  "description": "Example custom language model",
  "base_model_name": "en-US_BroadbandModel",
  "status": "pending",
  "progress": 0
}

status 字段报告模型的当前状态。 服务处理新词期间，状态会保持为 pending。 使用循环每 10 秒检查一次状态，直到它变为 ready，这指示操作完成。 有关可能的 status 值的更多信息，请参阅监视训练模型请求。

修改定制模型中的词

您还可以使用 POST /v1/customizations/{customization_id}/words 和 PUT /v1/customizations/{customization_id}/words/{word_name} 方法修改或扩充定制模型中的词。 您可能需要使用这两个方法来更正将词添加到模型时所犯的拼写错误或其他错误。 您可能还需要为现有词添加发音相似的读法定义。

使用这两个方法可修改现有词的定义，具体做法与添加词的完全一样。 为词提供的新数据将覆盖该词的现有定义。 对于基于上一代模型的定制模型， 您还可以修改从语料库添加的词。

监视训练模型请求

如果服务成功启动训练过程，那么服务会返回 200 响应代码。 在现有请求完成之前，该服务不接受后续培训请求，也不接受添加新语料库、单词或语法的请求。

将定制词直接添加到基于大型语音模型或下一代模型的定制模型，如 将词添加到定制语言模型 中所述，这将导致模型的训练时间比其他模型长几分钟。 如果要使用使用 POST /v1/customizations/{customization_id}/words 或 PUT /v1/customizations/{customization_id}/words/{word_name} 方法添加的定制词来训练模型，请为该模型留出一些分钟的额外训练时间。

要确定训练请求的状态，请使用 GET /v1/customizations/{customization_id} 方法来轮询模型的状态。 此方法接受模型的定制标识:

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"

响应包含有关模型状态的信息:

{
  "customization_id": "74f4807e-b5ff-4866-824e-6bba1a84fe96",
  "created": "2016-06-01T18:42:25.324Z",
  "updated": "2016-06-01T18:45:11.737Z",
  "language": "en-US",
  "dialect": "en-US",
  "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
  "name": "Example model",
  "description": "Example custom language model",
  "base_model_name": "en-US_BroadbandModel",
  "status": "training",
  "progress": 0
}

响应包含用于报告定制模型状态的 status 和 progress 字段。 progress 字段的含义取决于模型的状态。 status 字段可以具有下列其中一个值：

• pending 指示模型已创建，但正在等待添加有效训练数据或等待服务完成对已添加的数据的分析。 progress 字段为 0。

• ready 指示模型包含有效数据，已准备好进行训练。 progress 字段为 0。

  如果模型包含有效和无效资源的组合（例如，有效和无效的定制词），那么除非您将 strict 查询参数设置为 false，否则模型训练会失败。 有关更多信息，请参阅定制语言模型训练失败。

• training 指示正在训练模型。 progress 字段为 0。 当训练完成时，字段将从 0 更改为 100。

• available 指示模型已训练并已准备好供使用。 progress 字段为 100。

• upgrading 指示正在升级模型。 progress 字段为 0。

• failed 指示模型训练失败。 progress 字段为 0。 有关更多信息，请参阅定制语言模型训练失败。

使用循环每 10 秒检查一次状态，直到它变为 available。 有关检查定制模型的状态的更多信息，请参阅列出定制语言模型。

定制语言模型训练失败

如果服务正在处理定制语言模型的其他请求，那么训练无法启动。 例如，服务正在执行以下操作时，训练请求无法启动，状态码为 409：

• 处理语料库或语法以生成 OOV 词的列表或抽取字符序列
• 处理定制词以验证或自动生成发音相似的读法
• 处理其他训练请求

如果定制模型存在以下情况，训练也无法启动，状态码为 400：

• 自创建或上次训练以来，不包含任何新的有效训练数据（语料库、单词或语法）
• 包含一个或多个无效语料库、单词或语法（例如，自定义单词的发音与某个单词相似，但发音无效）

如果训练请求失败且状态码为 400，那么服务会将定制模型的状态设置为 failed。 请执行下列其中一项操作：

• 使用定制接口的方法来检查模型的资源，并修正发现的任何错误：

  • 对于无效的语料库，可以更正语料库文本文件，然后使用 allow_overwrite 方法的 POST /v1/customizations/{customization_id}/corpora/{corpus_name} 参数将更正后的文件添加到模型。 有关更多信息，请参阅向定制语言模型添加语料库。
  • 对于无效的语法，可以更正语法文件，然后使用 allow_overwrite 方法的 POST /v1/customizations/{customization_id}/grammars/{grammar_name} 参数将更正后的文件添加到模型。 有关更多信息，请参阅向定制语言模型添加语法。
  • 对于无效的定制词，可以使用 POST /v1/customizations/{customization_id}/words 或 PUT /v1/customizations/{customization_id}/words/{word_name} 方法直接在模型的词资源中修改该词。 有关更多信息，请参阅修改定制模型中的词。

  有关在自定义语言模型中验证单词的更多信息，请参阅

  • 验证先前生成模型的词资源
  • 验证大型语音模型和下一代模型的词资源。

• 将 strict 方法的 POST /v1/customizations/{customization_id}/train 参数设置为 false，以从训练中排除无效的资源。 模型必须至少包含一个有效的资源（语料库、单词或语法），才能成功进行训练。 strict 参数对于训练包含有效和无效资源组合的定制模型非常有用。