如要分析一段文字並擷取內含實體,請叫用 annotate()
方法,然後將文字字串或 EntityExtractionParams
的執行個體傳送至可以指定額外選項的其他選項,例如參照時間、時區或篩選條件,藉此限制搜尋實體類型子集。API 會傳回 EntityAnnotation
物件清單,其中包含各個實體的相關資訊。
SDK 名稱 | 實體擷取 |
---|---|
實作中 | 基本偵測工具的資產會在建構期間以靜態方式連結至您的應用程式。 |
素材資源大小影響 | 實體擷取功能的應用程式大小影響最大至 5.6 MB。 |
立即體驗
- 如要查看此 API 的範例,請搭配範例應用程式。
事前準備
- 在專案層級的
build.gradle
檔案中,確認 Google 的 Maven 存放區已包含在 buildscript 和 allprojects 區段中。 將 ML Kit 實體擷取程式庫的依附元件新增至模組的應用程式層級 Gradle 檔案 (名稱通常為
app/build.gradle
):dependencies { // … implementation 'com.google.mlkit:entity-extraction:16.0.0-beta4' }
擷取實體
建立 EntityExtractor
物件並使用 EntityExtractorOptions
進行設定
Kotlin
val entityExtractor = EntityExtraction.getClient( EntityExtractorOptions.Builder(EntityExtractorOptions.ENGLISH) .build())
Java
EntityExtractor entityExtractor = EntityExtraction.getClient( new EntityExtractorOptions.Builder(EntityExtractorOptions.ENGLISH) .build());
EntityExtractorOptions
也接受使用者定義的 Executor
,否則也會使用 ML Kit 中的預設 Executor
確認必要的模型已下載到裝置。
Kotlin
entityExtractor .downloadModelIfNeeded() .addOnSuccessListener { _ -> /* Model downloading succeeded, you can call extraction API here. */ } .addOnFailureListener { _ -> /* Model downloading failed. */ }
Java
entityExtractor .downloadModelIfNeeded() .addOnSuccessListener( aVoid -> { // Model downloading succeeded, you can call the extraction API here. }) .addOnFailureListener( exception -> { // Model downloading failed. });
確認模型下載完成後,請將字串或 EntityExtractionParams
傳遞至 annotate()
。在確定可用該模式前,請勿呼叫 annotate()
。
Kotlin
val params = EntityExtractionParams.Builder("My flight is LX373, please pick me up at 8am tomorrow.") .setEntityTypesFilter((/* optional entity type filter */) .setPreferredLocale(/* optional preferred locale */) .setReferenceTime(/* optional reference date-time */) .setReferenceTimeZone(/* optional reference timezone */) .build() entityExtractor .annotate(params) .addOnSuccessListener { // Annotation process was successful, you can parse the EntityAnnotations list here. } .addOnFailureListener { // Check failure message here. }
Java
EntityExtractionParams params = new EntityExtractionParams .Builder("My flight is LX373, please pick me up at 8am tomorrow.") .setEntityTypesFilter(/* optional entity type filter */) .setPreferredLocale(/* optional preferred locale */) .setReferenceTime(/* optional reference date-time */) .setReferenceTimeZone(/* optional reference timezone */) .build(); entityExtractor .annotate(params) .addOnSuccessListener(new OnSuccessListener<List<EntityAnnotation>>() { @Override public void onSuccess(List<EntityAnnotation> entityAnnotations) { // Annotation process was successful, you can parse the EntityAnnotations list here. } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { // Check failure message here. } });
PreferredLocale
、ReferenceTime
和 ReferenceTimeZone
只會影響 DateTime 實體。如未明確設定,則會預設為使用者裝置的值。
循環處理註解結果,以擷取擷取實體的相關資訊。
Kotlin
for (entityAnnotation in entityAnnotations) { val entities: List<Entity> = entityAnnotation.entities Log.d(TAG, "Range: ${entityAnnotation.start} - ${entityAnnotation.end}") for (entity in entities) { when (entity) { is DateTimeEntity -> { Log.d(TAG, "Granularity: ${entity.dateTimeGranularity}") Log.d(TAG, "TimeStamp: ${entity.timestampMillis}") } is FlightNumberEntity -> { Log.d(TAG, "Airline Code: ${entity.airlineCode}") Log.d(TAG, "Flight number: ${entity.flightNumber}") } is MoneyEntity -> { Log.d(TAG, "Currency: ${entity.unnormalizedCurrency}") Log.d(TAG, "Integer part: ${entity.integerPart}") Log.d(TAG, "Fractional Part: ${entity.fractionalPart}") } else -> { Log.d(TAG, " $entity") } } } }
Java
List<EntityAnnotation> entityAnnotations = /* Get from EntityExtractor */; for (EntityAnnotation entityAnnotation : entityAnnotations) { List<Entity> entities = entityAnnotation.getEntities(); Log.d(TAG, String.format("Range: [%d, %d)", entityAnnotation.getStart(), entityAnnotation.getEnd())); for (Entity entity : entities) { switch (entity.getType()) { case Entity.TYPE_DATE_TIME: DateTimeEntity dateTimeEntity = entity.asDateTimeEntity(); Log.d(TAG, "Granularity: " + dateTimeEntity.getDateTimeGranularity()); Log.d(TAG, "Timestamp: " + dateTimeEntity.getTimestampMillis()); case Entity.TYPE_FLIGHT_NUMBER: FlightNumberEntity flightNumberEntity = entity.asFlightNumberEntity(); Log.d(TAG, "Airline Code: " + flightNumberEntity.getAirlineCode()); Log.d(TAG, "Flight number: " + flightNumberEntity.getFlightNumber()); case Entity.TYPE_MONEY: MoneyEntity moneyEntity = entity.asMoneyEntity(); Log.d(TAG, "Currency: " + moneyEntity.getUnnormalizedCurrency()); Log.d(TAG, "Integer Part: " + moneyEntity.getIntegerPart()); Log.d(TAG, "Fractional Part: " + moneyEntity.getFractionalPart()); case Entity.TYPE_UNKNOWN: default: Log.d(TAG, "Entity: " + entity); } } }
當您不再需要 EntityExtractor
物件時,請呼叫 close()
方法。如果您是在 Fragment 或 AppCompatActivity 上使用 EntityExtractor
,可以在 Fragment 或 AppCompatActivity 上呼叫 LifecycleOwner.getLifecycle(),然後呼叫 Lifecycle.addObserver。例如:
Kotlin
val options = … val extractor = EntityExtraction.getClient(options); getLifecycle().addObserver(extractor);
Java
EntityExtractorOptions options = … EntityExtractor extractor = EntityExtraction.getClient(options); getLifecycle().addObserver(extractor);
明確管理實體擷取模型
如上所述,使用實體擷取 API 時,ML Kit 會視需要自動將語言特定模型下載到裝置上 (呼叫 downloadModelIfNeeded()
時)。您也可以透過 ML Kit 的模型管理 API,明確管理裝置上的模型。如果你想預先下載模型,這項功能就非常實用。你也可以透過 API 刪除不再需要的模型。
Kotlin
val modelManager = RemoteModelManager.getInstance() // Get entity extraction models stored on the device. modelManager.getDownloadedModels(EntityExtractionRemoteModel::class.java) .addOnSuccessListener { // ... } .addOnFailureListener({ // Error. }) // Delete the German model if it's on the device. val germanModel = EntityExtractionRemoteModel.Builder(EntityExtractorOptions.GERMAN).build() modelManager.deleteDownloadedModel(germanModel) .addOnSuccessListener({ // Model deleted. }) .addOnFailureListener({ // Error. }) // Download the French model. val frenchModel = EntityExtractionRemoteModel.Builder(EntityExtractorOptions.FRENCH).build() val conditions = DownloadConditions.Builder() .requireWifi() .build() modelManager.download(frenchModel, conditions) .addOnSuccessListener({ // Model downloaded. }) .addOnFailureListener({ // Error. })
Java
// Get entity extraction models stored on the device. modelManager.getDownloadedModels(EntityExtractionRemoteModel.class) .addOnSuccessListener(new OnSuccessListener<Set<EntityExtractionRemoteModel>>() { @Override public void onSuccess(Set<EntityExtractionRemoteModel> models) { // ... } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { // Error. } }); // Delete the German model if it's on the device. EntityExtractionRemoteModel germanModel = new EntityExtractionRemoteModel.Builder(EntityExtractorOptions.GERMAN).build(); modelManager.deleteDownloadedModel(germanModel) .addOnSuccessListener(new OnSuccessListener<Void>() { @Override public void onSuccess(Void v) { // Model deleted. } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { // Error. } }); // Download the French model. EntityExtractionRemoteModel frenchModel = new EntityExtractionRemoteModel.Builder(EntityExtractorOptions.FRENCH).build(); DownloadConditions conditions = new DownloadConditions.Builder() .requireWifi() .build(); modelManager.download(frenchModel, conditions) .addOnSuccessListener(new OnSuccessListener<Void>() { @Override public void onSuccess(Void v) { // Model downloaded. } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { // Error. } });