IBM Cloud Docs
使用 Code Engine 进行文本分析

使用 Code Engine 进行文本分析

本教程可能会发生成本。 使用 成本估算器 根据您的预计使用量生成成本估算。

在本教程中,您将通过使用 Natural Language Understanding 应用程序部署文本分析来了解 IBM Cloud® Code Engine。 您将创建 Code Engine 项目,选择该项目并将 Code Engine 实体 (应用程序和作业) 部署到该项目。 您将学习如何将 IBM Cloud 服务绑定到 Code Engine 实体。 此外,您还将了解 Code Engine 的自动缩放功能,其中实例根据传入工作负载向上或向下扩展 (到零)。

IBM Cloud Code Engine 是一个完全受管的无服务器平台,用于运行容器化工作负载,包括 Web 应用程序,微服务,事件驱动的函数或批处理作业。Code Engine 甚至通过源代码为您构建容器映像。 由于这些工作负载都托管在同一 Kubernetes 基础架构中,因此所有工作负载都可以无缝协作。 Code Engine旨在让您专注于编写代码,而无需考虑托管代码所需的基础设施。

该平台旨在满足只想让其代码运行的开发人员的需求。Code Engine 将在 Kubernetes 中构建,部署和管理工作负载的操作负担抽象化,以便开发者可以关注对他们最重要的内容: 源代码。

目标

  • 了解 IBM Cloud® Code Engine 以及它如何简化开发者体验。
  • 了解如何使用 Code Engine轻松部署和扩展应用程序。
  • 了解如何使用作业来执行运行以完成工作负载。

架构*" caption-side="bottom"}{: caption="*

  1. 开发者创建 Code Engine 项目,并部署前端和后端 Code Engine 应用程序。
  2. 开发者通过修改前端应用程序以将环境变量值设置为指向后端应用程序的端点,将前端 (UI) 应用程序连接到后端。
  3. 开发者供应必需的云服务,并通过创建私钥和配置映射将其绑定到后端应用程序和作业。
  4. 用户通过前端应用程序上载文本文件,该应用程序通过后端应用程序存储在 Object Storage 中。
  5. 用户通过后端运行 Code Engine 作业,以通过将文本推送到 Natural Language Understanding来分析文本。 然后,结果将保存到 Object Storage,并在用户单击刷新按钮时显示在前端应用程序中。

您可以使用 Code Engine 控制台 在完成本教程时查看进度。

准备工作

本教程需要:

  • IBM Cloud CLI-此 CLI 工具将使您能够与 IBM Cloud进行交互。
    • code-engine/ce plugin (code-engine/ce)-Plugins 使用特定于服务的命令扩展 IBM Cloud CLI 的功能。 Code Engine 插件将使您能够访问 IBM Cloud上的 Code Engine 命令。
    • 可选 Container Registry 插件 (container-registry)

您可以在 教程入门 指南中找到有关为操作环境下载和安装这些工具的指示信息。 为了避免安装这些工具,本教程将使用 IBM Cloud 控制台中的 Cloud Shell

开始新的 IBM Cloud Shell

从浏览器中的 IBM Cloud 控制台,单击右上角的按钮以创建新的 Cloud Shell

创建一个 IBM Cloud Code Engine 项目

在本部分中,您将创建Code Engine。 项目是 Code Engine 实体 (例如应用程序,作业和构建) 的分组。 项目用于管理资源并提供对其实体的访问权。

通过将实体放入单个项目中,您可以更轻松地管理访问控制。 项目中的实体共享相同的专用网络,这使它们能够安全地相互通信。 有关更多详细信息,请阅读 有关 Code Engine 项目的文档

  1. 浏览至 IBM Cloud Code Engine 概述 页面。

  2. 在左侧面板中,点击 “项目”,然后点击 “创建”。

    • 选择位置。
    • 提供项目名称。
    • 选择将在其中创建项目的资源组以及后续步骤中所需的云服务。 资源组是一种将您的账户资源按自定义分组进行组织的方式。
    • 单击创建
    • 等待项目 status 更改为 活动
  3. 切换到先前启动的 Cloud Shell 会话,并在要求您运行 CLI 命令时在本教程中使用该会话。

  4. 创建具有项目名称和资源组名称的 shell 变量

    PROJECT_NAME=YourProjectName
    RESOURCE_GROUP_NAME=YourResourceGroupName
    
  5. 将创建项目的资源组作为目标。

    ibmcloud target -g $RESOURCE_GROUP_NAME
    
  6. 通过 选择 命令行工具,使其指向您的项目。

    ibmcloud code-engine project select --name $PROJECT_NAME
    

将前端和后端应用程序部署为 Code Engine 应用程序

Code Engine 应用程序 运行您的代码,以响应 HTTP 请求,自动扩展和缩减至零,并提供多版本流量路由。 在本节中,您将把前端和后端应用程序部署到 Code Engine。 前端 Web应用程序允许用户上传文本文件,而后端应用程序会将文件写入 IBM Cloud Object Storage。

我们已经为这两个应用程序构建了映像,并将它们推送到公共 Container Registry。 您将使用这些预先构建的容器映像来部署相应的应用程序。 您自己的应用程序的创建将在稍后的步骤中进行。

部署前端应用程序

  1. 要部署新的 Code Engine 应用程序,请运行以下命令; 提供服务名称 frontend 和预先构建的容器映像作为 --image 标志的参数。

    ibmcloud code-engine application create --name frontend --image icr.io/solution-tutorials/tutorial-text-analysis-code-engine-frontend
    

    运行该命令后,您应该会看到一些URL输出。 它应该类似于: https://frontend.305atabsd0w.us-south.codeengine.appdomain.cloud。 复制或记录此应用程序URL,以便下一步操作。 仅凭这两个数据(应用程序名称和图片名称 Code Engine 就部署了您的应用程序,并为您处理配置和管理应用程序的复杂工作。

    用于构建容器映像的应用程序源代码在 GitHub 存储库 中提供,供您参考。 如果要从源代码构建容器映像并将这些映像推送到专用 Container Registry,请遵循 此处的指示信息

  2. 在浏览器中打开上一步骤中的URL,即可看到类似以下内容的输出:

    前端正在运行
    前端正在运行

    运行 ibmcloud code-engine application get -n frontend 命令以查看应用程序的详细信息。 您应该查看ID、项目信息、应用程序的年龄、访问应用程序URL、访问应用程序配置URL、图像、资源分配以及应用程序的各种修订、条件和运行时间等详细信息。 由于您只有一个修订版,因此应该会看到 100% 的流量将进入最新修订版。 您还可以检查实例数及其状态。

  3. 要进行故障诊断并 检查应用程序的日志,请通过从 ibmcloud code-engine application get -n frontend 命令将 <INSTANCE_NAME> 替换为其中一个实例的 name 来运行以下命令。

    如果您没有看到正在运行的实例,请确保再次打开步骤2中的URL。

    ibmcloud code-engine application logs --instance <INSTANCE_NAME>
    

    如果应用程序正在运行,那么您应该会看到 backend URL: undefined 和应用程序在端口 8080 上侦听。 稍后在教程中,您将把这个前端应用程序连接到我们的后端应用程序

祝贺您!! 您刚刚使用简单的命令将 Web 应用程序部署到 Code Engine,而无需了解 Kubernetes 的复杂性,例如 pod,部署,服务和入口。

扩展应用程序

使用 application create 命令创建应用程序时,仅在要使用的映像中传递了应用程序的名称。 虽然这是用于部署应用程序的最小信息量,但有 个您可以控制的其他旋钮。 除其他外,您可以设置每个实例可并发处理的请求数,应用程序实例的 CPU 量,为应用程序实例设置的内存量,应用程序的环境变量,可用于此应用程序的最大和最小实例数以及应用程序侦听请求的端口。

如果在创建应用程序时未提供任何内容作为选项,那么这些值中的大多数值都具有缺省设置。 由于未提供值,因此 Code Engine 部署了我们的应用程序,缺省最大规模为 10,这意味着它只会将我们的应用程序扩展至最多 10 个实例。 缺省最小小数位为零,因此当我们的应用程序不再使用时,它会将自身缩减为零。

  1. 要检查 Code Engine的自动缩放功能,可以使用负载生成器对服务执行请求。 以下 shell 脚本模拟 3000 个请求的基本负载。

    1. 打开本地终端窗口 (shell)。

    2. 根据上一步骤为前URL 创建一个外壳变量。

      export APPURL=<frontend-application-url>
      
    3. 运行以下脚本以生成一些装入。 您可以重复此操作以创建更多流量。

      seq 1 3000 | xargs -n1 -P300  curl -s  $APPURL -o /dev/null
      
  2. 在先前部分中的 Cloud Shell 会话中,运行以下命令以查看在自动缩放过程中递增的实例 (pod) 计数。

    ibmcloud code-engine application get -n frontend
    

    缺省情况下,每个实例可并发处理的最大请求数为 10,这将导致自动缩放,并且可以使用带有 --concurrency or -cn 标志的 application update 命令来更改此值。

  3. 如果您不想允许创建多达 10 个实例,那么可以将最大小数位调整为较小的数字。 虽然无服务器应用程序可以轻松扩展,但您可能依赖于下游服务 (例如 SQL DB),该服务只能处理有限数量的连接或其他速率有限的 API。 让我们尝试限制此前端应用程序的实例数。

    ibmcloud code-engine application update --name frontend --max-scale 5
    
  4. 停止装入生成后,请等待几分钟以查看实例正在终止,最终缩减为零个实例。

  5. 在具有装入生成器命令的本地窗口中,再次运行该脚本以针对应用程序创建请求。 在 Cloud Shell 会话中,运行 ibmcloud code-engine application get -n frontend 命令以查看增加到 5 的实例计数。

    预期的输出:

    Name                                        Revision        Running  Status   Restarts  Age
    frontend-00002-deployment-77d5fbfb5d-7zpfl  frontend-00002  3/3      Running  0         70s
    frontend-00002-deployment-77d5fbfb5d-kv6rn  frontend-00002  3/3      Running  0         69s
    frontend-00002-deployment-77d5fbfb5d-mhlwn  frontend-00002  3/3      Running  0         68s
    frontend-00002-deployment-77d5fbfb5d-qkjmd  frontend-00002  3/3      Running  0         67s
    frontend-00002-deployment-77d5fbfb5d-zpr9n  frontend-00002  3/3      Running  0         85s
    

部署后端应用程序并测试连接

  1. 要部署新的后端应用程序以将文本文件存储到 IBM Cloud Object Storage中,请运行此命令

    ibmcloud code-engine application create --name backend --image icr.io/solution-tutorials/tutorial-text-analysis-code-engine-backend --cluster-local
    

    --cluster-local 标志将指示 Code Engine 使此应用程序的端点保持为专用,这意味着它仅在项目中可用。 这通常用于安全目的。 在这种情况下,没有理由使用公共端点来公开后端应用程序,因为不会从集群外部访问该应用程序。

  2. 复制并保存输出中的内部终端 URL ),以便在下一个命令中使用。 大致如下:

    BACKEND_PRIVATE_URL=http://backend.xxxxxx
    

    您可以运行 ibmcloud code-engine application get -n backend 命令来检查后端应用程序的状态和详细信息,其中包含 URL

  3. 前端应用程序使用环境变量 (BACKEND_URL) 来了解后端应用程序的托管位置。 现在需要更新前端应用程序以将此值设置为指向后端应用程序的端点。

    ibmcloud code-engine application update --name frontend --env BACKEND_URL=$BACKEND_PRIVATE_URL
    

    如果需要设置多个环境变量,那么 --env 标志的出现次数可能与您所希望的次数相同。 如果您当时知道前端应用程序的值,那么也可以在 ibmcloud code-engine application create 命令上使用此选项。 通过阅读 使用环境变量 文档主题来了解更多信息。

  4. 在浏览器中硬刷新前端 URL,以测试与后端应用程序的连接。 您应该会看到一个页面,其中有一个选项用于上传文本文件(.txt),以及来自后端应用程序的错误消息,因为后端尚未连接所需IBM Cloud来存储和处理文本文件。 单击 上载文本文件 还应显示类似的错误消息。

将后端应用程序连接到 Object Storage 服务

在此部分中,您将供应所需的 Object Storage 和 Natural Language Understanding 服务,并将 Object Storage 服务绑定到后端应用程序。 后端应用程序将把文本文件存储到 Object Storage中,而 Natural Language Understanding 将在教程中稍后用于对上载的文本文件执行文本分析。

通过 IBM Watson® Natural Language Understanding,开发者可以分析文本输入的语义特征,包括类别、概念、情绪、实体、关键字、元数据、关系、语义角色和观点。

供应 Object Storage 和 Natural Language Understanding 服务

  1. 创建 Object Storage 的实例

    1. 如果帐户中已有 Object Storage 服务实例,请选择轻量套餐或标准套餐。
    2. 服务名称 设置为 your-initials-code-engine-cos
    3. 选择在其中创建了 Code Engine 项目的资源组。
    4. 单击创建
    5. 捕获 shell 变量中的服务名称:
      COS_INSTANCE_NAME=your-initials-code-engine-cos
      
  2. 在“创建存储区”下,单击 创建存储区,然后在 创建定制存储区 下选择 创建

    创建存储区或添加对象时,请确保避免使用个人可标识信息 (PII)。注 :PII 是可以通过名称,位置或任何其他方法识别任何用户 (自然人) 的信息。

    1. 输入 唯一存储区名称,例如 <your-initials>-bucket-code-engine
    2. 选择 位置,您在其中创建了 Code Engine 项目。
    3. 选择 智能层 存储类。
    4. 单击创建存储区
    5. 捕获 shell 变量中的存储区名称:
      COS_BUCKETNAME=your-initials-bucket-code-engine
      
  3. 在存储区页面上。

    1. 点击配置选项卡
    2. Direct 端点将在 IBM Cloud中保留数据。 捕获 shell 变量中的直接端点。 在美国南部的达拉斯地区可能是这样:
      COS_ENDPOINT=s3.direct.us-south.cloud-object-storage.appdomain.cloud
      
  4. 创建 Natural Language Understanding 的实例

    1. 选择位置并选择 轻量 套餐。
    2. 服务名称 设置为 code-engine-nlu,并选择在其中创建 Code Engine 项目的资源组。
    3. 阅读许可协议,然后选中 我已阅读并同意以下许可协议:
    4. 单击创建
    5. 捕获 shell 变量中的服务名称:
      NLU_INSTANCE_NAME=YourServiceName
      

将 Object Storage 服务绑定到后端应用程序

现在,您需要将刚刚创建的 IBM Cloud Object Storage 实例的凭证传递到后端应用程序。 您将通过将 Object Storage 服务 绑定 到应用程序来执行此操作,这会自动将服务的凭证添加到应用程序或作业的环境变量。

  1. 使用前缀 COS 为 Object Storage 服务创建绑定,以便于在应用程序中使用。 bind 命令在服务实例中创建服务凭证,并从中使用凭证初始化应用程序的环境变量。 可以通过使用 --prefix 标志将每个服务绑定配置为使用定制环境变量前缀。

    ibmcloud code-engine application bind --name backend --service-instance $COS_INSTANCE_NAME --role Writer --prefix COS
    
  2. 您还需要向应用程序提供要在其中存储文本文件的存储区名称以及 COS 端点。 这两个步骤都是在先前的步骤中定义的。 智能层 的 us-south 端点为 s3.direct.us-south.cloud-object-storage.appdomain.cloud

    定义 configmap 以保存存储区名称和端点,因为信息不敏感。 ConfigMaps 是一个 Kubernetes 对象,它允许您将配置工件与映像内容分离,以保持容器化应用程序可移植。 您可以从文件或键值对创建此 configmap-现在,我们将使用带有 --from-literal 标志的键值对。 验证先前是否已捕获这些内容并创建 configmap:

    echo bucket $COS_BUCKETNAME endpoint $COS_ENDPOINT
    
    ibmcloud code-engine configmap create --name backend-configuration --from-literal=COS_BUCKETNAME=$COS_BUCKETNAME --from-literal=COS_ENDPOINT=$COS_ENDPOINT
    
  3. 通过定义 configmap,现在可以通过请求 Code Engine 根据 configmap 中的值在应用程序运行时中设置环境变量来更新后端应用程序。 使用以下命令更新后端应用程序

    ibmcloud code-engine application update --name backend --env-from-configmap backend-configuration
    

    要创建私钥,需要使用 --env-from-secret 标志。 私钥和 configmap 都是“映射”; 因此环境变量集将具有对应于这些映射中每个条目的“键”的名称,而环境变量值将是该“键”的值。

  4. 验证是否使用绑定和 configmap 更新后端应用程序。 您可以运行以下命令并在输出中查找 Service BindingsEnvironment Variables 部分

    ibmcloud code-engine application get --name backend
    
  5. 转至前端 UI 和 上载文本文件 以进行文本分析。 您应该会看到上载的文件上带有 Not analyzed 标记。

使用自动化作业处理文本文件

现在,您已将后端应用程序连接到前端应用程序。 您已通过服务绑定和上载的文件提供所有必需凭证以进行文本分析。 要完成测试,您将创建一个作业以指定每次运行作业以使用 Natural Language Understanding 服务分析文本时使用的工作负载配置信息。

创建作业

与响应传HTTP 请求的应用不同 ,Job 用于运行包含可执行文件的容器镜像,该可执行文件设计为运行一次后退出。 创建 job 时,可以指定每次运行作业时使用的工作负载配置信息。 您可以通过控制台或CLI创建一个作业。

此作业将从 IBM Cloud Object Storage读取文本文件,然后使用 Natural Language Understanding 服务对其进行分析。 它将需要具有对这两个服务的服务凭证的访问权。

  1. 运行以下命令创建一个作业,
    ibmcloud code-engine job create --name backend-job --image icr.io/solution-tutorials/tutorial-text-analysis-code-engine-backend-job --env-from-configmap backend-configuration
    
    您可以使用 --env 标志来设置 Natural Language Understanding 服务的版本。 对于版本控制,请检查此 链接

将 IBM Cloud 服务绑定到作业

  1. 让我们为 Object Storage 服务创建一个带有前缀 COS_JOB 的绑定,以便与作业配合使用来读取上载的文件并存储结果,
    ibmcloud code-engine job bind --name backend-job --service-instance $COS_INSTANCE_NAME --role Writer --prefix COS_JOB
    
  2. 同样,让我们使用前缀 NLU_JOB 绑定 Natural Language Understanding 服务以分析上载的文本文件,
    ibmcloud code-engine job bind --name backend-job --service-instance $NLU_INSTANCE_NAME --role Writer --prefix NLU_JOB
    
  3. 验证是否使用绑定和 configmap 更新了作业。 您可以运行以下命令并在输出中查找 Service BindingsEnvironment Variables 部分
    ibmcloud code-engine job get --name backend-job
    

运行作业

  1. 要使用上面创建的配置 运行作业,请使用 jobrun submit 命令,

    ibmcloud code-engine jobrun submit --name backend-jobrun --job backend-job
    

    运行作业时,可以覆盖在作业配置中设置的许多变量。 要检查变量,请运行 ibmcloud code-engine jobrun submit --help

  2. 要检查 jobrun 的状态,请运行以下命令

    ibmcloud code-engine jobrun get --name backend-jobrun
    
  3. 可以显示日志:

    ibmcloud code-engine jobrun logs --follow --name backend
    
  4. 在前端 UI 中,单击 刷新 按钮 (上载文本文件旁边) 以查看每个已上载文本文件的 关键字JSON。 每个文件上的标记现在应更改为 Analyzed

  5. 通过单击 删除 图标上载新文件或删除单个文件,使用以下命令重新提交 jobrun,然后单击 刷新 按钮以查看结果。

    ibmcloud code-engine jobrun resubmit --jobrun backend-jobrun
    

自动执行作业运行

您可以通过创建用于侦听 Object Storage 存储区更改的 IBM Cloud Object Storage 预订来自动运行作业,而不是手动运行作业。 当您创建对存储区的 预订 时,对于对该存储区的每次成功更改,您的作业都会收到单独的事件。

  1. 必须先将 Notifications Manager 角色分配给 Code Engine,然后才能创建 Object Storage 预订。 作为通知管理器,Code Engine 可以查看,修改和删除 Object Storage 存储区的通知。 遵循此处的指示信息 将通知管理器角色分配给 Code Engine 项目。
  2. 运行以下命令以将 backend-job 连接到 IBM Cloud Object Storage 事件生产者。 在运行命令之前检查并更新 bucket name
    ibmcloud code-engine subscription cos create --name backend-job-cos-event --destination-type job --destination backend-job --bucket $COS_BUCKETNAME --prefix files --event-type write
    
  3. 现在,只需上载新文件并单击 刷新 按钮即可查看结果。 展望未来,您不必重新提交 jobrun,因为预订会对其进行处理。

可选: 构建容器映像并将其推送到 IBM Cloud Container Registry

有几个选项可用于 使用独立构建命令构建容器映像运行从本地目录中拉取源的单个构建 用于创建新的前端应用程序:

git clone https://github.com/IBM-Cloud/code-engine-text-analysis
cd code-engine-text-analysis/frontend
echo $BACKEND_PRIVATE_URL

您可以更改一些要验证的源代码。 第二次出现在 public/index.html 和 public/501.html 的 body 中的 Text analysis with Code Engine 可以更改为添加到您的名称中。 在代码引擎名称空间中创建容器映像,并在一个命令中创建应用程序:

ibmcloud ce application create --name frontend-fromsource --build-source . --env BACKEND_URL=$BACKEND_PRIVATE_URL

除去资源

  1. 使用以下命令,删除项目以删除其所有组件 (应用程序,作业等)。
    ibmcloud code-engine project delete --name $PROJECT_NAME
    
  2. 浏览至 资源列表,然后删除您创建的服务:
    • IBM Cloud® Object Storage
    • IBM Watson® Natural Language Understanding

根据资源的不同,可能不会立即将其删除,但会保留 (缺省情况下为 7 天)。 您可以通过永久删除该资源或在保留期内将其复原来回收该资源。 请参阅本文档,以了解如何 使用资源回收