【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载Amazon Comprehend 是 AWS 的 NLP自然语言处理服务提供语言检测、情感分析、实体识别、关键短语提取、语法分析和 PII个人身份信息检测等能力。本文基于 Context Hub 仓库中维护的 AWS 官方文档content/aws/docs/comprehend/javascript/DOC.md完整讲解如何通过 AWS SDK for JavaScript v3 的aws-sdk/client-comprehend包在 Node.js 中完成实时文本分析同步 API与基于 S3 的异步批量任务。读完本文你将掌握客户端初始化、凭据配置、client.send(new Command(input))调用模式、六大常用工作流以及异步任务的状态轮询方法并能在实际项目中直接复制运行。本文档面向aws-sdk/client-comprehend版本3.1007.0由 Context Hub 维护frontmatter 中source: maintainer。在 Context Hub 中这篇文档的条目 ID 为aws/comprehend语言变体为javascript可通过chub get aws/comprehend --lang js拉取详见 CLI 参考 与 SKILL.md。安装使用 npm 安装 Comprehend 客户端包npm install aws-sdk/client-comprehend如果你的代码需要显式加载 AWS 命名配置文件named profile例如通过fromIni读取~/.aws/credentials中的特定 profile还需要安装凭据辅助包npm install aws-sdk/credential-providers该包提供fromIni、fromEnv、fromSSO、fromTemporaryCredentialsassume-role 流程等显式凭据加载工具是aws-sdk/client-comprehend之外最常用的配套依赖。前置条件基本凭据与区域在创建客户端之前先通过环境变量设置 AWS 凭据与区域export AWS_REGIONus-east-1 export AWS_ACCESS_KEY_ID... export AWS_SECRET_ACCESS_KEY... export AWS_SESSION_TOKEN... # 可选仅在使用临时凭据时需要如果本地使用共享 AWS 配置文件~/.aws/config与~/.aws/credentialsAWS_PROFILE也能被 AWS SDK for JavaScript v3 的标准凭据链识别export AWS_PROFILEmy-dev-profile export AWS_REGIONus-east-1在 Node.js 环境中默认的凭据提供链credential provider chain通常已足够它会依次检查环境变量、共享配置文件、ECS 任务凭据、EC2 实例元数据以及 IAM Identity CenterSSO。也就是说如果你的 AWS 访问权限来自上述任一渠道通常无需手动注入凭据。异步任务所需的 IAM 角色与 S3 位置调用异步检测任务如StartSentimentDetectionJobCommand时Amazon Comprehend 需要代为读取 S3 输入并写入 S3 输出因此你必须提供一个 Comprehend 可以代入assume的 IAM 角色以及输入、输出桶位置export COMPREHEND_DATA_ACCESS_ROLE_ARNarn:aws:iam::123456789012:role/ComprehendDataAccessRole export COMPREHEND_INPUT_S3_URIs3://my-input-bucket/comprehend/input/ export COMPREHEND_OUTPUT_S3_URIs3://my-output-bucket/comprehend/output/注意DataAccessRoleArn与你的应用用来调用 AWS 的凭据是两回事——前者是服务侧角色授予 Comprehend 访问你的 S3 数据的权限后者是你自己的 SDK 凭据。初始化客户端最小化 Node.js 客户端import { ComprehendClient } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: process.env.AWS_REGION ?? us-east-1, });显式凭据当你不希望依赖凭据链而是直接在代码中传入凭据时import { ComprehendClient } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: us-east-1, credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY, sessionToken: process.env.AWS_SESSION_TOKEN, }, });通过fromIni加载命名 profileimport { fromIni } from aws-sdk/credential-providers; import { ComprehendClient } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: us-east-1, credentials: fromIni({ profile: my-dev-profile }), });核心调用模式AWS SDK v3 的客户端统一采用client.send(new Command(input))模式每个 API 对应一个*Command类通过send方法发送返回 Promise。例如情感检测import { ComprehendClient, DetectSentimentCommand, } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: process.env.AWS_REGION ?? us-east-1, }); const response await client.send( new DetectSentimentCommand({ Text: The delivery was fast and the packaging was excellent., LanguageCode: en, }), ); console.log(response.Sentiment, response.SentimentScore);Sentiment返回POSITIVE、NEGATIVE、NEUTRAL或MIXEDSentimentScore是包含Positive、Negative、Neutral、Mixed四个 0~1 概率值的对象四个值之和为 1可用于阈值判断。常见工作流先检测语言再分析情感大多数 Comprehend 同步文本分析 API 都要求提供LanguageCode。如果语言未知先用DetectDominantLanguageCommand检测再把返回的语言代码传入后续请求import { ComprehendClient, DetectDominantLanguageCommand, DetectSentimentCommand, } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: process.env.AWS_REGION ?? us-east-1, }); const text The delivery was fast and the packaging was excellent.; const languageResult await client.send( new DetectDominantLanguageCommand({ Text: text, }), ); const languageCode languageResult.Languages?.[0]?.LanguageCode; if (!languageCode) { throw new Error(Comprehend did not return a dominant language); } const sentimentResult await client.send( new DetectSentimentCommand({ Text: text, LanguageCode: languageCode, }), ); console.log(sentimentResult.Sentiment); console.log(sentimentResult.SentimentScore);DetectDominantLanguage返回Languages数组每项包含LanguageCode与Score置信度按得分降序排列取第一项即为最可能的语言。对多篇短文本批量执行情感分析单一语言码当你已经知道请求中的每篇文档都使用同一种语言时使用批量 API 减少请求次数import { BatchDetectSentimentCommand, ComprehendClient, } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: process.env.AWS_REGION ?? us-east-1, }); const response await client.send( new BatchDetectSentimentCommand({ LanguageCode: en, TextList: [ This product solved the problem quickly., Setup was confusing and took too long., Support answered within five minutes., ], }), ); for (const result of response.ResultList ?? []) { console.log(result.Index, result.Sentiment, result.SentimentScore); } for (const error of response.ErrorList ?? []) { console.error(error.Index, error.ErrorCode, error.ErrorMessage); }注意批量 API 对整批请求只接受一个LanguageCode且TextList中每篇文档有长度上限单文档约 5,000 字符。ResultList中的Index对应TextList中的原始下标失败的条目会出现在ErrorList中含Index、ErrorCode、ErrorMessage因此结果与错误要按Index对应处理。从文档中提取实体import { ComprehendClient, DetectEntitiesCommand, } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: process.env.AWS_REGION ?? us-east-1, }); const response await client.send( new DetectEntitiesCommand({ Text: Jane Doe from Example Corp met the AWS team in Seattle on Tuesday., LanguageCode: en, }), ); for (const entity of response.Entities ?? []) { console.log(entity.Text, entity.Type, entity.Score); }Entities中每项包含Text实体原文、Type如PERSON、ORGANIZATION、LOCATION、DATE、QUANTITY等、Score及起止偏移量。同样的调用模式适用于其他同步文本 API例如DetectKeyPhrasesCommand关键短语与DetectSyntaxCommand语法标注返回SyntaxTokens及其PartOfSpeech当它们更契合你的应用场景时直接替换即可。先判断是否含 PII再按需获取精确偏移ContainsPiiEntitiesCommand只回答文本中是否包含 PII、包含哪些类型的 PII 标签适合作为前置门控gateDetectPiiEntitiesCommand才返回实体的精确起止偏移适合脱敏场景import { ComprehendClient, ContainsPiiEntitiesCommand, DetectPiiEntitiesCommand, } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: process.env.AWS_REGION ?? us-east-1, }); const text Contact me at janeexample.com or 206-555-0100.; const contains await client.send( new ContainsPiiEntitiesCommand({ Text: text, LanguageCode: en, }), ); console.log(contains.Labels); const detailed await client.send( new DetectPiiEntitiesCommand({ Text: text, LanguageCode: en, }), ); for (const entity of detailed.Entities ?? []) { console.log(entity.Type, entity.BeginOffset, entity.EndOffset, entity.Score); }ContainsPiiEntities的Labels是形如{ Name: EMAIL, Score: 0.99 }的标签列表DetectPiiEntities的Entities中每项包含Type如EMAIL、PHONE、NAME、CREDIT_DEBIT_NUMBER、BeginOffset、EndOffset字符偏移可直接用于切片脱敏与Score。注意DetectPiiEntities本身不返回实体原文Text为空只提供偏移与类型脱敏时需自行根据偏移截取原文本。启动并轮询异步情感检测任务当输入数据已经存放在 S3 中或数据集规模超出实时文本 API 的限制同步 API 单次Text约 5,000 字符时改用异步任务 APIimport { ComprehendClient, DescribeSentimentDetectionJobCommand, StartSentimentDetectionJobCommand, } from aws-sdk/client-comprehend; const client new ComprehendClient({ region: process.env.AWS_REGION ?? us-east-1, }); const roleArn process.env.COMPREHEND_DATA_ACCESS_ROLE_ARN; const inputS3Uri process.env.COMPREHEND_INPUT_S3_URI; const outputS3Uri process.env.COMPREHEND_OUTPUT_S3_URI; if (!roleArn || !inputS3Uri || !outputS3Uri) { throw new Error(Set COMPREHEND_DATA_ACCESS_ROLE_ARN, COMPREHEND_INPUT_S3_URI, and COMPREHEND_OUTPUT_S3_URI); } const start await client.send( new StartSentimentDetectionJobCommand({ JobName: support-ticket-sentiment, LanguageCode: en, DataAccessRoleArn: roleArn, InputDataConfig: { S3Uri: inputS3Uri, InputFormat: ONE_DOC_PER_LINE, }, OutputDataConfig: { S3Uri: outputS3Uri, }, }), ); const jobId start.JobId; if (!jobId) { throw new Error(Comprehend did not return a JobId); } for (;;) { const detail await client.send( new DescribeSentimentDetectionJobCommand({ JobId: jobId, }), ); const properties detail.SentimentDetectionJobProperties; const status properties?.JobStatus; console.log(status); if (status COMPLETED) { console.log(properties?.OutputDataConfig?.S3Uri); break; } if (status FAILED || status STOPPED) { throw new Error(Sentiment job ended with status ${status}); } await new Promise((resolve) setTimeout(resolve, 10000)); }要点说明InputDataConfig.InputFormat支持ONE_DOC_PER_LINE每行一篇文档推荐用于大批量文本与ONE_DOC_PER_FILE每个文件一篇文档。输出结果会写入OutputDataConfig.S3Uri指向的位置DescribeSentimentDetectionJob返回的SentimentDetectionJobProperties.OutputDataConfig.S3Uri可能包含任务 ID 子路径如s3://bucket/output/1234567890abcdef/。轮询间隔为 10 秒实际生产代码可改用指数退避如 10s → 20s → 40s…并设置最大重试次数。任务终态为COMPLETED、FAILED、STOPPED及STOP_REQUESTED过渡态SUBMITTED、IN_PROGRESS属于进行中状态。Comprehend 的其他异步任务 API 遵循完全相同的模式Start*JobCommand启动 S3 任务Describe*JobCommand轮询状态。可替换的对应关系包括StartEntitiesDetectionJobCommand/DescribeEntitiesDetectionJobCommand、StartKeyPhrasesDetectionJobCommand/DescribeKeyPhrasesDetectionJobCommand、StartDominantLanguageDetectionJobCommand/DescribeDominantLanguageDetectionJobCommand、StartPiiEntitiesDetectionJobCommand/DescribePiiEntitiesDetectionJobCommand、StartTopicsDetectionJobCommand/DescribeTopicsDetectionJobCommand等。重要注意事项Gotchas大多数同步文本 API 强制要求LanguageCode如果你的应用事先不知道语言务必先用DetectDominantLanguageCommand检测再将结果代码传给后续请求。批量 API 只接受单个LanguageCode批量请求内所有文档必须同语言发送前先按语言对文本分组。同步 API 接收原始Text异步 API 读写 S3前者请求体中直接携带文本后者输入输出均通过 S3 URI 传递且需要DataAccessRoleArn。异步任务必须提供DataAccessRoleArn这是服务侧 IAM 角色与你的 SDK 凭据相互独立缺少时任务会以FAILED结束或启动即报权限错误。ContainsPiiEntitiesCommand与DetectPiiEntitiesCommand职责不同前者只返回存在哪些 PII 标签类型Labels后者才返回精确偏移Entities中的BeginOffset/EndOffset脱敏场景必须用后者。StartSentimentDetectionJobCommand只负责启动任务它不等待任务完成必须配合DescribeSentimentDetectionJobCommand轮询到终态并读取输出 S3 路径。Comprehend 是区域化服务regional客户端region与数据、IAM 角色必须同区域区域不匹配时错误往往表现为权限问题或资源不存在排查时先核对区域。何时使用其他配套包aws-sdk/credential-providers需要显式加载凭据时使用包括fromIni、assume-rolefromTemporaryCredentials以及其他基于 profile 的配置方式。其他 AWS SDK v3 服务客户端当你的 Comprehend 工作流依赖 S3上传/下载输入输出、IAM角色管理或周边基础设施自动化时组合使用对应的 v3 客户端如aws-sdk/client-s3、aws-sdk/client-iam。版本说明本指南针对aws-sdk/client-comprehend版本3.1007.0见文档 frontmatter 的versions字段。当前包面使用标准的 AWS SDK v3 命令模式client.send(new Command(input))所有示例均基于该模式编写。若你使用的是 Python 侧的 Comprehend 类型桩可参考仓库中对应的 mypy-boto3-comprehend 指南两篇文档由 Context Hub 分别维护为javascript与python语言变体。在 Context Hub 中获取与使用本文档本文档是 Context Hub 仓库中面向 LLM/Agent 优化的文档条目之一。编码 Agent 在写 Comprehend 相关代码前可通过chubCLI 拉取最新版本而非依赖训练数据中可能过时的 API 记忆npm install -g aisuite/chub chub search aws/comprehend --lang js # 检索条目 chub get aws/comprehend --lang js # 拉取本文档JavaScript 变体完整的命令说明见 CLI Reference 与 get-api-docs 技能仓库总览见 README。该文档本身以 YAML frontmatter 标记元信息条目名comprehend、语言javascript、版本3.1007.0、来源maintainer与仓库的 内容规范 保持一致。赞分享【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载相关推荐使用 AWS SDK for Java 2.x 调用 Amazon Comprehend文本分析实战指南使用 AWS SDK for Java 2.x 调用 Amazon Comprehend文本分析实战指南 Amazon Comprehend 是基于自然语言处示例工程教程后端使用 AWS SDK for .NET 调用 Amazon Comprehend 自然语言处理 API 完整指南使用 AWS SDK for .NET 调用 Amazon Comprehend 自然语言处理 API 完整指南 导读 本文以 dotnetv3/Compreh示例工程教程后端使用 AWS SDK for Kotlin 调用 Amazon Comprehend六个 NLP 检测与文档分类实战示例使用 AWS SDK for Kotlin 调用 Amazon Comprehend六个 NLP 检测与文档分类实战示例 导读 本文以 kotlin/serv示例工程教程后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考