기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 개발 문제 해결 이 섹션에는 Managed Service for Apache Flink 애플리케이션의 개발 문제를 진단하고 수정하는 방법에 대한 정보가 포함되어 있습니다. **Topics** + [시스템 롤백 모범 사례](troubleshooting-system-rollback.md) + [Hudi 구성 모범 사례](troubleshooting-hudi.md) + [Apache Flink 플레임 그래프](troubleshooting-update-flamegraphs.md) + [EFO 커넥터 1.15.2의 자격 증명 공급자 문제](troubleshooting-credential-provider.md) + [지원되지 않는 Kinesis 커넥터가 있는 애플리케이션](troubleshooting-unsupported-kinesis-connectors.md) + [컴파일 오류: ‘프로젝트의 종속성을 해결할 수 없음’](troubleshooting-compile.md) + [잘못된 선택: ‘kinesisanalyticsv2’](troubleshooting-cli-update.md) + [UpdateApplication 작업에서 애플리케이션 코드가 다시 로드되지 않는 문제](troubleshooting-update.md) + [S3 StreamingFileSink FileNotFoundExceptions](troubleshooting-s3sink.md) + [저장점 사용 중지 관련 FlinkKafkaConsumer 문제](troubleshooting-FlinkKafkaConsumer.md) + [Flink 1.15 Async Sink 교착 상태](troubleshooting-async-deadlock.md) + [리샤딩 중 Amazon Kinesis Data Streams 소스 처리 순서가 잘못됨](troubleshooting-kinesis-data-streams-processing-out-of-order.md) + [실시간 벡터 임베딩 블루프린트 FAQ 및 문제 해결](troubleshooting-blueprints.md) # 시스템 롤백 모범 사례 Amazon Managed Service for Apache Flink의 자동 시스템 롤백 및 운영 가시성 기능을 사용하여 애플리케이션의 문제를 식별하고 해결할 수 있습니다. ## 시스템 롤백 코드 버그 또는 권한 문제와 같은 고객 오류로 인해 애플리케이션 업데이트 또는 규모 조정 작업이 실패하는 경우 이 기능을 옵트인하면 Amazon Managed Service for Apache Flink는 자동으로 이전 실행 버전으로 롤백을 시도합니다. 자세한 내용은 [Managed Service for Apache Flink 애플리케이션의 시스템 롤백 활성화](how-system-rollbacks.md) 단원을 참조하십시오. 이 자동 롤백이 실패하거나 옵트인 또는 옵트아웃하지 않은 경우 애플리케이션은 `READY` 상태로 전환됩니다. 애플리케이션을 업데이트하려면 다음 단계를 완료합니다. 작업이 실패한 이유에 대한 오류 설명을 확인하려면 Amazon Managed Service for Apache Flink 콘솔을 확인하거나 `DescribeApplicationOperation` API를 사용합니다. 전체 오류 스택을 확인하려면 [Cloudwatch 로그](https://docs.aws.amazon.com/managed-flink/latest/java/logging.html)를 사용합니다. 일반적인 문제는 권한 부족, 호환되지 않는 코드 변경 또는 인프라 구성 오류입니다. 근본적인 문제를 해결합니다. `UpdateApplicaton` API를 사용하여 새 애플리케이션 버전을 다시 배포합니다. ## 수동 롤백 애플리케이션이 진행되지 않고 일시적인 상태에 오래 머무르거나 `Running` 상태로 정상 전환되었지만 업데이트된 Flink 애플리케이션에서 처리 오류와 같은 다운스트림 문제가 발생하는 경우 `RollbackApplication` API를 사용하여 수동으로 롤백할 수 있습니다. 1. `RollbackApplication` 직접 호출 - 이전 실행 버전으로 되돌리고 이전 상태를 복원합니다. 1. `DescribeApplicationOperation` API를 사용하여 롤백 작업을 모니터링합니다. 1. 롤백에 실패하면 이전 시스템 롤백 단계를 사용합니다. ## 운영 가시성 `ListApplicationOperations` API는 애플리케이션의 모든 고객 기록 및 시스템 작업 기록을 보여줍니다. 1. 목록에서 실패한 작업의 *operationId*를 가져옵니다. 1. `DescribeApplicationOperation`을 직접적으로 호출하여 상태와 *statusDescription*을 확인합니다. 1. 작업이 실패한 경우 설명은 조사해야 할 잠재적 오류를 나타냅니다. **일반적인 오류 코드 버그:** 롤백 기능을 사용하여 마지막 정상 버전으로 되돌립니다. 버그를 해결하고 업데이트를 다시 시도합니다. **권한 문제:** `DescribeApplicationOperation`을 사용하여 필요한 권한을 확인합니다. 애플리케이션 권한을 업데이트한 뒤 다시 시도합니다. **Amazon Managed Service for Apache Flink 서비스 문제:**를 확인하거나 지원 사례를 AWS Health Dashboard 엽니다. # Hudi 구성 모범 사례 Managed Service for Apache Flink에서 Hudi 커넥터를 실행하려면 다음과 같이 구성을 변경할 것을 권장합니다. `hoodie.embed.timeline.server` 비활성화 Flink의 Hudi 커넥터는 작업 병렬 처리가 높을 때 성능을 향상시키기 위해 Flink jobmanager(JM)에 메타데이터를 캐시하는 임베디드 타임라인(TM) 서버를 설정합니다. Managed Service for Apache Flink에서는 JM과 TM 간의 비Flink 통신이 비활성화되어 있으므로 이 임베디드 서버를 비활성화할 것을 권장합니다. 이 서버가 활성화되는 경우 Hudi 쓰기 작업은 먼저 JM의 임베디드 서버에 연결을 시도한 뒤 Amazon S3에서 메타데이터를 읽는 방식으로 돌아갑니다. 이는 연결 시간 초과를 유발하여 Hudi 쓰기 작업이 지연되고 Managed Service for Apache Flink의 성능에 영향을 미칩니다. # Apache Flink 플레임 그래프 플레임 그래프는 플레임 그래프를 지원하는 Managed Service for Apache Flink버전의 애플리케이션에서 기본적으로 활성화됩니다. [Flink 설명서](https://nightlies.apache.org/flink/flink-docs-release-1.15//docs/ops/debugging/flame_graphs/)에 나와 있는 것처럼 그래프를 열어 두면 플레임 그래프가 애플리케이션 성능에 영향을 미칠 수 있습니다. 애플리케이션에 대해 플레임 그래프를 비활성화하려면 애플리케이션 ARN에서 플레임 그래프를 비활성화하도록 요청하는 케이스를 생성하십시오. 자세한 내용을 알아보려면 [AWS 지원 센터](https://console.aws.amazon.com/support/home#/)를 참조하세요. # EFO 커넥터 1.15.2의 자격 증명 공급자 문제 Kinesis 데이터 스트림 EFO 커넥터 버전 최대 1.15.2에는 `FlinkKinesisConsumer`가 `Credential Provider` 구성을 준수하지 않는 [알려진 문제가](https://issues.apache.org/jira/browse/FLINK-29205) 있습니다. 이 문제로 인해 유효한 구성이 무시되고 있으며, 이로 인해 `AUTO` 자격 증명 공급자가 사용됩니다. 이로 인해 EFO 커넥터를 사용하여 Kinesis에 대한 교차 계정 액세스를 사용할 때 문제가 발생할 수 있습니다. 이 오류를 해결하려면 EFO 커넥터 버전 1.15.3 이상을 사용하십시오. # 지원되지 않는 Kinesis 커넥터가 있는 애플리케이션 Managed Service for Apache Flink 버전 1.15 이상은 애플리케이션 JAR 또는 아카이브(ZIP)에 번들로 제공되는 지원되지 않는 Kinesis 커넥터 버전(1.15.2 이전 버전)을 사용하는 경우 [애플리케이션의 시작 또는 업데이트를 자동으로 거부합니다](https://docs.aws.amazon.com/managed-flink/latest/java/flink-1-15-2.html). ## 거부 오류 다음을 통해 애플리케이션 생성/업데이트 호출을 제출할 때 다음 오류가 표시됩니다. ``` An error occurred (InvalidArgumentException) when calling the CreateApplication operation: An unsupported Kinesis connector version has been detected in the application. Please update flink-connector-kinesis to any version equal to or newer than 1.15.2. For more information refer to connector fix: https://issues.apache.org/jira/browse/FLINK-23528 ``` ## 해결 단계 + `flink-connector-kinesis`에 대한 애플리케이션 종속성을 업데이트하십시오. Maven을 프로젝트의 빌드 도구로 사용하고 있다면 [Maven 종속성 업데이트](#troubleshooting-unsupported-kinesis-connectors-update-maven-dependency)을 따르세요. Gradle을 사용하고 있다면 [Gradle 종속성 업데이트](#troubleshooting-unsupported-kinesis-connectors-update-gradle-dependency)을 따르세요. + 애플리케이션을 재패키징합니다. + Amazon S3 버킷에 업로드합니다. + Amazon S3 버킷으로 업로드한 수정된 애플리케이션으로 애플리케이션 생성/업데이트 요청을 다시 제출합니다. + 동일한 오류 메시지가 계속 표시되면 애플리케이션 종속성을 다시 확인하십시오. 문제가 지속되면 지원 티켓을 생성하세요. ### Maven 종속성 업데이트 1. 프로젝트의 `pom.xml`를 엽니다. 1. 프로젝트의 종속성을 찾아보세요. 모양은 다음과 같습니다. ``` ... ... org.apache.flink flink-connector-kinesis ... ... ``` 1. 1.15.2 이상의 버전으로 `flink-connector-kinesis`을 업데이트하세요. 예를 들면 다음과 같습니다. ``` ... ... org.apache.flink flink-connector-kinesis 1.15.2 ... ... ``` ### Gradle 종속성 업데이트 1. 프로젝트 `build.gradle`(또는 Kotlin 애플리케이션의 `build.gradle.kts`)를 엽니다. 1. 프로젝트의 종속성을 찾아보세요. 모양은 다음과 같습니다. ``` ... dependencies { ... implementation("org.apache.flink:flink-connector-kinesis") ... } ... ``` 1. 1.15.2 이상의 버전으로 `flink-connector-kinesis`을 업데이트하세요. 예를 들면 다음과 같습니다. ``` ... dependencies { ... implementation("org.apache.flink:flink-connector-kinesis:1.15.2") ... } ... ``` # 컴파일 오류: ‘프로젝트의 종속성을 해결할 수 없음’ Managed Service for Apache Flink 샘플 애플리케이션을 컴파일하려면 먼저 Apache Flink Kinesis 커넥터를 다운로드하여 컴파일한 다음 로컬 Maven 저장소에 추가해야 합니다. 커넥터가 저장소에 추가되지 않은 경우 다음과 비슷한 컴파일 오류가 나타납니다. ``` Could not resolve dependencies for project your project name: Failure to find org.apache.flink:flink-connector-kinesis_2.11:jar:1.8.2 in https://repo.maven.apache.org/maven2 was cached in the local repository, resolution will not be reattempted until the update interval of central has elapsed or updates are forced ``` 이 오류를 해결하려면 커넥터용 Apache Flink 소스 코드([https://flink.apache.org/downloads.html](https://flink.apache.org/downloads.html)의 버전 1.8.2)를 다운로드해야 합니다. Apache Flink 소스 코드를 다운로드, 컴파일 및 설치하는 방법에 대한 지침은 [Apache Flink Kinesis 스트림 커넥터를 이전 Apache Flink 버전과 함께 사용](earlier.md#how-creating-apps-building-kinesis) 섹션을 참조하십시오. # 잘못된 선택: ‘kinesisanalyticsv2’ Managed Service for Apache FlinkAPI의 v2를 사용하려면 최신 버전 AWS Command Line Interface (AWS CLI)이 필요합니다. 업그레이드에 대한 자세한 내용은 *AWS Command Line Interface 사용 설명서*[의 설치를 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) AWS CLI참조하세요. # UpdateApplication 작업에서 애플리케이션 코드가 다시 로드되지 않는 문제 지정된 S3 객체 버전이 없는 경우 [UpdateApplication](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_UpdateApplication.html) 작업은 동일한 파일 명칭을 가진 애플리케이션 코드를 다시 로드하지 않습니다. 애플리케이션 코드를 동일한 파일 명칭으로 다시 로드하려면 S3 버킷의 버전 관리를 활성화하고 `ObjectVersionUpdate` 파라미터를 사용하여 새 객체 버전을 지정하십시오. S3 버킷에서 객체 버전 관리 활성화에 대한 자세한 내용을 알아보려면 [버전 관리 활성화 또는 비활성화](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/enable-versioning.html)를 참조하세요. # S3 StreamingFileSink FileNotFoundExceptions Managed Service for Apache Flink 애플리케이션은 저장 포인트에서 참조하는 진행 중인 부분 파일이 없는 경우 스냅샷에서 시작할 때 진행 중인 부분 파일 `FileNotFoundException`로 실행될 수 있습니다. 이 오류 모드가 발생하면 Managed Service for Apache Flink 애플리케이션의 연산자 상태는 일반적으로 복구할 수 없으므로 `SKIP_RESTORE_FROM_SNAPSHOT`을 사용하는 스냅샷 없이 다시 시작해야 합니다. 다음 예 스택트레이스를 참조하십시오. ``` java.io.FileNotFoundException: No such file or directory: s3://amzn-s3-demo-bucket/pathj/INSERT/2023/4/19/7/_part-2-1234_tmp_12345678-1234-1234-1234-123456789012 at org.apache.hadoop.fs.s3a.S3AFileSystem.s3GetFileStatus(S3AFileSystem.java:2231) at org.apache.hadoop.fs.s3a.S3AFileSystem.innerGetFileStatus(S3AFileSystem.java:2149) at org.apache.hadoop.fs.s3a.S3AFileSystem.getFileStatus(S3AFileSystem.java:2088) at org.apache.hadoop.fs.s3a.S3AFileSystem.open(S3AFileSystem.java:699) at org.apache.hadoop.fs.FileSystem.open(FileSystem.java:950) at org.apache.flink.fs.s3hadoop.HadoopS3AccessHelper.getObject(HadoopS3AccessHelper.java:98) at org.apache.flink.fs.s3.common.writer.S3RecoverableMultipartUploadFactory.recoverInProgressPart(S3RecoverableMultipartUploadFactory.java:97) ... ``` Flink `StreamingFileSink`는 [파일 시스템](https://nightlies.apache.org/flink/flink-docs-release-1.15/docs/deployment/filesystems/overview/)에서 지원하는 파일 시스템에 레코드를 기록합니다. 들어오는 스트림을 제한하지 않을 수 있다는 점을 고려하면 데이터는 데이터가 기록될 때 새 파일이 추가되고 한정된 크기의 부분 파일로 구성됩니다. 부품 라이프사이클 및 롤오버 정책에 따라 부분 파일의 타이밍, 크기 및 명칭이 결정됩니다. 체크포인트 지정 및 저장점 지정(스냅샷) 중에는 보류 중인 모든 파일의 명칭이 바뀌고 구속됩니다. 그러나 진행 중인 부분 파일은 구속되지 않고 명칭이 변경되며 해당 참조는 작업을 복원할 때 사용할 체크포인트 또는 저장점 메타데이터에 보관됩니다. 진행 중인 이러한 부분 파일은 결국 미결로 넘겨지고 후속 체크포인트 또는 저장점에서 명칭을 바꾸고 구속됩니다. 진행 중인 부분 파일이 누락되는 근본 원인과 해결 방법은 다음과 같습니다. + Managed Service for Apache Flink 애플리케이션을 시작하는 데 사용되는 오래된 스냅샷 – 애플리케이션이 중지되거나 업데이트될 때 생성된 최신 시스템 스냅샷만 Amazon S3 StreamingFileSink를 사용하여 Managed Service for Apache Flink 애플리케이션을 시작하는 데 사용할 수 있습니다. 이러한 장애 클래스를 방지하려면 최신 시스템 스냅샷을 사용하십시오. + 예를 들어 중지 또는 업데이트 중에 시스템 트리거 스냅샷 대신 `CreateSnapshot`을 사용하여 만든 스냅샷을 선택할 때 이런 현상이 발생합니다. 이전 스냅샷의 저장점에는 후속 체크포인트 또는 저장점에 의해 명칭이 변경되고 구속된 진행 중인 부분 파일에 대한 오래된 참조가 보관됩니다. + 이는 최신이 아닌 Stop/Update 이벤트에서 시스템이 트리거한 스냅샷을 선택한 경우에도 발생할 수 있습니다. 시스템 스냅샷이 비활성화되었지만 `RESTORE_FROM_LATEST_SNAPSHOT`을 이미 구성한 애플리케이션을 예로 들 수 있습니다. 일반적으로 Amazon S3 StreamingFileSink를 사용하는 Managed Service for Apache Flink에서는 항상 시스템 스냅샷을 활성화하고 `RESTORE_FROM_LATEST_SNAPSHOT`을 구성해야 합니다. + 진행 중인 부분 파일 제거 – 진행 중인 부분 파일은 S3 버킷에 있으므로 해당 버킷에 액세스할 수 있는 다른 구성 요소나 행위자에 의해 제거될 수 있습니다. + 이는 앱을 너무 오랫동안 중지하고 앱의 저장점에서 참조하는 진행 중인 부분 파일이 [S3 버킷 MultiPartupload](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpu-abort-incomplete-mpu-lifecycle-config.html) 라이프사이클 정책에 의해 제거된 경우 발생할 수 있습니다. 이러한 장애 클래스를 방지하려면 S3 Bucket MPU 라이프사이클 정책이 사용 사례에 비해 충분히 긴 기간 동안 적용되는지 확인하십시오. + 이는 진행 중인 부분 파일을 수동으로 제거하거나 시스템의 다른 구성 요소에 의해 제거된 경우에도 발생할 수 있습니다. 이러한 오류 클래스를 방지하려면 진행 중인 부분 파일이 다른 행위자나 구성 요소에 의해 제거되지 않도록 하십시오. + 저장점 이후 자동 체크포인트가 트리거되는 경쟁 조건 – 이는 Managed Service for Apache Flink 버전(최대 1.13 포함)에 영향을 미칩니다. 이 문제는 Managed Service for Apache Flink 버전 1.15에서 수정되었습니다. 재발을 방지하려면 애플리케이션을 최신 버전의 Managed Service for Apache Flink로 마이그레이션하세요. 또한 StreamingFileSink에서 [FileSink](https://nightlies.apache.org/flink/flink-docs-release-1.19/docs/connectors/datastream/filesystem/#file-sink)로 마이그레이션하는 것이 좋습니다. + 애플리케이션이 중지되거나 업데이트되면 Managed Service for Apache Flink는 저장점을 트리거하고 두 단계에 걸쳐 애플리케이션을 중지합니다. 두 단계 사이에 자동 체크포인트가 트리거되면 진행 중인 부분 파일의 명칭이 바뀌고 잠재적으로 구속될 수 있으므로 저장점을 사용할 수 없게 됩니다. # 저장점 사용 중지 관련 FlinkKafkaConsumer 문제 레거시 FlinkKafkaConsumer를 사용할 때 시스템 스냅샷을 활성화한 경우 애플리케이션이 업데이트, 중지 또는 조정에서 멈출 수 있습니다. 이 [문제](https://issues.apache.org/jira/browse/FLINK-28758)에 대한 수정은 게시되지 않았으므로 이 문제를 완화하려면 새 [KafkaSource](https://nightlies.apache.org/flink/flink-docs-master/docs/connectors/datastream/kafka/#kafka-source)로 업그레이드하는 것이 좋습니다. 스냅샷이 활성화된 상태로 `FlinkKafkaConsumer`를 사용하는 경우 Flink 작업에서 저장점 API로 중지 요청을 처리할 때 `ClosedException`를 보고하는 런타임 오류가 발생하여 `FlinkKafkaConsumer`이 실패할 수 있습니다. 이러한 상황에서는 Flink 애플리케이션이 중단되고 실패한 체크포인트로 나타납니다. # Flink 1.15 Async Sink 교착 상태 AsyncSink 인터페이스를 구현하는 Apache Flink용 AWS 커넥터에는 [알려진 문제가](https://issues.apache.org/jira/browse/FLINK-32230) 있습니다. 이는 다음 커넥터와 함께 Flink 1.15를 사용하는 애플리케이션에 영향을 줍니다. + Java 애플리케이션의 경우: + KinesisStreamsSink – `org.apache.flink:flink-connector-kinesis` + KinesisStreamsSink – `org.apache.flink:flink-connector-aws-kinesis-streams` + KinesisFirehoseSink – `org.apache.flink:flink-connector-aws-kinesis-firehose` + DynamoDbSink – `org.apache.flink:flink-connector-dynamodb` + Flink SQL/TableAPI/Python 애플리케이션: + kinesis – `org.apache.flink:flink-sql-connector-kinesis` + kinesis – `org.apache.flink:flink-sql-connector-aws-kinesis-streams` + firehose – `org.apache.flink:flink-sql-connector-aws-kinesis-firehose` + dynamodb – `org.apache.flink:flink-sql-connector-dynamodb` 영향을 받는 애플리케이션에서는 다음과 같은 증상이 나타납니다. + Flink 작업이 `RUNNING` 상태이지만 데이터를 처리하지 못하고 있다; + 작업이 다시 시작되지 않는다; + 체크포인트 시간이 초과되었다. 이 문제는 AWS SDK의 [버그](https://github.com/aws/aws-sdk-java-v2/issues/4354)로 인해 비동기 HTTP 클라이언트를 사용할 때 호출자에게 특정 오류가 표시되지 않습니다. 이로 인해 싱크는 체크포인트 플러시 작업 중에 “진행 중인 요청”이 완료될 때까지 무기한 대기하게 됩니다. 이 문제는 버전 **2.20.144**부터 AWS SDK에서 수정되었습니다. 다음은 애플리케이션에서 새 버전의 AWS SDK를 사용하도록 영향을 받는 커넥터를 업데이트하는 방법에 대한 지침입니다. **Topics** + [Java 애플리케이션 업데이트](troubleshooting-async-deadlock-update-java-apps.md) + [Python 애플리케이션 업데이트](troubleshooting-async-deadlock-update-python-apps.md) # Java 애플리케이션 업데이트 아래 절차에 따라 Java 애플리케이션을 업데이트하십시오. ## flink-connector-kinesis 애플리케이션은 `flink-connector-kinesis`을 사용하는 경우: Kinesis 커넥터는 셰이딩을 사용하여 AWS SDK를 비롯한 일부 종속성을 커넥터 jar에 패키징합니다. AWS SDK 버전을 업데이트하려면 다음 절차에 따라 이러한 셰이딩된 클래스를 바꿉니다. ------ #### [ Maven ] 1. Kinesis 커넥터와 필수 AWS SDK 모듈을 프로젝트 종속성으로 추가합니다. 1. 구성 `maven-shade-plugin`: 1. Kinesis 커넥터 jar의 콘텐츠를 복사할 때 음영 처리된 AWS SDK 클래스를 제외하도록 필터를 추가합니다. 1. 재배치 규칙을 추가하여 업데이트된 AWS SDK 클래스를 Kinesis 커넥터에서 예상되는 패키지로 이동합니다. **pom.xml** ``` ... ... org.apache.flink flink-connector-kinesis 1.15.4 software.amazon.awssdk kinesis 2.20.144 software.amazon.awssdk netty-nio-client 2.20.144 software.amazon.awssdk sts 2.20.144 ... ... ... ... org.apache.maven.plugins maven-shade-plugin 3.1.1 package shade ... ... org.apache.flink:flink-connector-kinesis org/apache/flink/kinesis/shaded/software/amazon/awssdk/** org/apache/flink/kinesis/shaded/org/reactivestreams/** org/apache/flink/kinesis/shaded/io/netty/** org/apache/flink/kinesis/shaded/com/typesafe/netty/** ... ... software.amazon.awssdk org.apache.flink.kinesis.shaded.software.amazon.awssdk org.reactivestreams org.apache.flink.kinesis.shaded.org.reactivestreams io.netty org.apache.flink.kinesis.shaded.io.netty com.typesafe.netty org.apache.flink.kinesis.shaded.com.typesafe.netty ... ... ... ... ``` ------ #### [ Gradle ] 1. Kinesis 커넥터와 필수 AWS SDK 모듈을 프로젝트 종속성으로 추가합니다. 1. ShadowJar 구성 조정: 1. Kinesis 커넥터 jar의 콘텐츠를 복사할 때 음영 처리된 AWS SDK 클래스를 제외합니다. 1. 업데이트된 AWS SDK 클래스를 Kinesis 커넥터에서 예상되는 패키지로 재배치합니다. **build.gradle** ``` ... dependencies { ... flinkShadowJar("org.apache.flink:flink-connector-kinesis:1.15.4") flinkShadowJar("software.amazon.awssdk:kinesis:2.20.144") flinkShadowJar("software.amazon.awssdk:sts:2.20.144") flinkShadowJar("software.amazon.awssdk:netty-nio-client:2.20.144") ... } ... shadowJar { configurations = [project.configurations.flinkShadowJar] exclude("software/amazon/kinesis/shaded/software/amazon/awssdk/**/*") exclude("org/apache/flink/kinesis/shaded/org/reactivestreams/**/*.class") exclude("org/apache/flink/kinesis/shaded/io/netty/**/*.class") exclude("org/apache/flink/kinesis/shaded/com/typesafe/netty/**/*.class") relocate("software.amazon.awssdk", "org.apache.flink.kinesis.shaded.software.amazon.awssdk") relocate("org.reactivestreams", "org.apache.flink.kinesis.shaded.org.reactivestreams") relocate("io.netty", "org.apache.flink.kinesis.shaded.io.netty") relocate("com.typesafe.netty", "org.apache.flink.kinesis.shaded.com.typesafe.netty") } ... ``` ------ ## 영향을 받는 기타 커넥터 애플리케이션이 영향을 받는 다른 커넥터를 사용하는 경우. AWS SDK 버전을 업데이트하려면 프로젝트 빌드 구성에서 SDK 버전을 적용해야 합니다. ------ #### [ Maven ] `pom.xml` 파일의 종속성 관리 섹션에 AWS SDK BOM(Bill of Material)을 추가하여 프로젝트에 SDK 버전을 적용합니다. **pom.xml** ``` ... ... software.amazon.awssdk bom 2.20.144 import pom ... ... ``` ------ #### [ Gradle ] AWS SDK 재료표(BOM)에 플랫폼 종속성을 추가하여 프로젝트에 SDK 버전을 적용합니다. 이를 위해서는 Gradle 5.0 이상이 필요합니다. **build.gradle** ``` ... dependencies { ... flinkShadowJar(platform("software.amazon.awssdk:bom:2.20.144")) ... } ... ``` ------ # Python 애플리케이션 업데이트 Python 애플리케이션은 커넥터를 두 가지 방식으로 사용할 수 있습니다. 커넥터 및 기타 Java 종속성을 단일 uber-jar의 일부로 패키징하거나 커넥터 jar를 직접 사용하는 것입니다. Async Sink 교착 상태의 영향을 받는 애플리케이션을 수정하려면, + 애플리케이션이 uber jar를 사용하는 경우 [Java 애플리케이션 업데이트](troubleshooting-async-deadlock-update-java-apps.md)의 지침을 따르세요. + 소스에서 커넥터 jar를 다시 빌드하려면 다음 단계를 사용하십시오. **소스에서 커넥터 만들기:** Flink [빌드 요건](https://nightlies.apache.org/flink/flink-docs-release-1.15/docs/flinkdev/building/#build-flink)과 유사한 사전 요건: + Java 11 + Maven 3.2.5 ## flink-sql-connector-kinesis 1. Flink 1.15.4의 소스 코드 다운로드: ``` wget https://archive.apache.org/dist/flink/flink-1.15.4/flink-1.15.4-src.tgz ``` 1. 소스 코드 압축 해제: ``` tar -xvf flink-1.15.4-src.tgz ``` 1. kinesis 커넥터 디렉터리로 이동합니다. ``` cd flink-1.15.4/flink-connectors/flink-connector-kinesis/ ``` 1. 필요한 AWS SDK 버전을 지정하여 커넥터 jar을 컴파일하고 설치합니다. 빌드 속도를 높이려면 테스트 실행을 건너뛰는 `-DskipTests` 방법과 추가 소스 코드 검사를 건너뛰는 `-Dfast` 방법을 사용하십시오. ``` mvn clean install -DskipTests -Dfast -Daws.sdkv2.version=2.20.144 ``` 1. kinesis 커넥터 디렉터리로 이동합니다. ``` cd ../flink-sql-connector-kinesis ``` 1. sql 커넥터 jar 컴파일 및 설치: ``` mvn clean install -DskipTests -Dfast ``` 1. 결과 jar는 다음에서 확인할 수 있습니다. ``` target/flink-sql-connector-kinesis-1.15.4.jar ``` ## flink-sql-connector-aws-kinesis-streams 1. Flink 1.15.4의 소스 코드 다운로드: ``` wget https://archive.apache.org/dist/flink/flink-1.15.4/flink-1.15.4-src.tgz ``` 1. 소스 코드 압축 해제: ``` tar -xvf flink-1.15.4-src.tgz ``` 1. kinesis 커넥터 디렉터리로 이동합니다. ``` cd flink-1.15.4/flink-connectors/flink-connector-aws-kinesis-streams/ ``` 1. 필요한 AWS SDK 버전을 지정하여 커넥터 jar을 컴파일하고 설치합니다. 빌드 속도를 높이려면 테스트 실행을 건너뛰는 `-DskipTests` 방법과 추가 소스 코드 검사를 건너뛰는 `-Dfast` 방법을 사용하십시오. ``` mvn clean install -DskipTests -Dfast -Daws.sdk.version=2.20.144 ``` 1. kinesis 커넥터 디렉터리로 이동합니다. ``` cd ../flink-sql-connector-aws-kinesis-streams ``` 1. sql 커넥터 jar 컴파일 및 설치: ``` mvn clean install -DskipTests -Dfast ``` 1. 결과 jar는 다음에서 확인할 수 있습니다. ``` target/flink-sql-connector-aws-kinesis-streams-1.15.4.jar ``` ## flink-sql-connector-aws-kinesis-firehose 1. Flink 1.15.4의 소스 코드 다운로드: ``` wget https://archive.apache.org/dist/flink/flink-1.15.4/flink-1.15.4-src.tgz ``` 1. 소스 코드 압축 해제: ``` tar -xvf flink-1.15.4-src.tgz ``` 1. 커넥터 디렉토리로 이동합니다. ``` cd flink-1.15.4/flink-connectors/flink-connector-aws-kinesis-firehose/ ``` 1. 필요한 AWS SDK 버전을 지정하여 커넥터 jar을 컴파일하고 설치합니다. 빌드 속도를 높이려면 테스트 실행을 건너뛰는 `-DskipTests` 방법과 추가 소스 코드 검사를 건너뛰는 `-Dfast` 방법을 사용하십시오. ``` mvn clean install -DskipTests -Dfast -Daws.sdk.version=2.20.144 ``` 1. sql 커넥터 디렉터리로 이동합니다. ``` cd ../flink-sql-connector-aws-kinesis-firehose ``` 1. sql 커넥터 jar 컴파일 및 설치: ``` mvn clean install -DskipTests -Dfast ``` 1. 결과 jar는 다음에서 확인할 수 있습니다. ``` target/flink-sql-connector-aws-kinesis-firehose-1.15.4.jar ``` ## flink-sql-connector-dynamodb 1. Flink 1.15.4의 소스 코드 다운로드: ``` wget https://archive.apache.org/dist/flink/flink-connector-aws-3.0.0/flink-connector-aws-3.0.0-src.tgz ``` 1. 소스 코드 압축 해제: ``` tar -xvf flink-connector-aws-3.0.0-src.tgz ``` 1. 커넥터 디렉토리로 이동합니다. ``` cd flink-connector-aws-3.0.0 ``` 1. 필요한 AWS SDK 버전을 지정하여 커넥터 jar을 컴파일하고 설치합니다. 빌드 속도를 높이려면 테스트 실행을 건너뛰는 `-DskipTests` 방법과 추가 소스 코드 검사를 건너뛰는 `-Dfast` 방법을 사용하십시오. ``` mvn clean install -DskipTests -Dfast -Dflink.version=1.15.4 -Daws.sdk.version=2.20.144 ``` 1. 결과 jar는 다음에서 확인할 수 있습니다. ``` flink-sql-connector-dynamodb/target/flink-sql-connector-dynamodb-3.0.0.jar ``` # 리샤딩 중 Amazon Kinesis Data Streams 소스 처리 순서가 잘못됨 현재 FlinkKinesisConsumer 구현은 Kinesis 샤드 간의 강력한 주문 보장을 제공하지 않습니다. 이로 인해 Kinesis Stream을 리샤딩하는 동안 처리 순서가 잘못될 수 있으며, 특히 처리 지연이 발생하는 Flink 애플리케이션의 경우 더욱 그렇습니다. 이벤트 시간을 기반으로 하는 Windows 연산자와 같은 일부 상황에서는 결과적으로 지연이 발생하여 이벤트가 삭제될 수 있습니다. ![\[Diagram showing shards and shard consumers with time progression and trim horizon.\]](http://docs.aws.amazon.com/ko_kr/managed-flink/latest/java/images/flink-ts.png) 이는 오픈 소스 Flink의 [알려진 문제](https://issues.apache.org/jira/browse/FLINK-6349)입니다. 커넥터 수정 사항이 제공될 때까지 다시 파티셔닝하는 동안 Flink 애플리케이션이 Kinesis Data Streams에 뒤쳐지지 않도록 합니다. Flink 앱에서 처리 지연을 허용하도록 하여 잘못된 처리 순서로 인한 영향과 데이터 손실 위험을 최소화할 수 있습니다. # 실시간 벡터 임베딩 블루프린트 FAQ 및 문제 해결 실시간 벡터 임베딩 블루프린트 문제를 해결하려면 다음 FAQ 및 문제 해결 섹션을 검토하세요. 실시간 벡터 임베딩 블루프린트에 관한 자세한 내용은 [실시간 벡터 임베딩 블루프린트](https://docs.aws.amazon.com/msk/latest/developerguide/ai-vector-embedding-integration-learn-more.html)를 참조하세요. Managed Service for Apache Flink 애플리케이션의 일반적인 문제 해결 방법은 [https://docs.aws.amazon.com/managed-flink/latest/java/troubleshooting-runtime.html](https://docs.aws.amazon.com/managed-flink/latest/java/troubleshooting-runtime.html) 페이지를 참조하세요. **Topics** + [실시간 벡터 임베딩 블루프린트 - FAQ](troubleshooting-blueprints-FAQ.md) + [실시간 벡터 임베딩 블루프린트 - 문제 해결](troubleshooting-blueprints-TS.md) # 실시간 벡터 임베딩 블루프린트 - FAQ 실시간 벡터 임베딩 블루프린트에 관한 FAQ를 검토하세요. 실시간 벡터 임베딩 블루프린트에 관한 자세한 내용은 [실시간 벡터 임베딩 블루프린트](https://docs.aws.amazon.com/msk/latest/developerguide/ai-vector-embedding-integration-learn-more.html)를 참조하세요. **Topics** + [이 블루프린트는 어떤 AWS 리소스를 생성하나요?](#troubleshooting-blueprints-1) + [AWS CloudFormation 스택 배포가 완료된 후 내 작업은 무엇입니까?](#troubleshooting-blueprints-2) + [소스 Amazon MSK 주제의 데이터는 어떤 구조로 구성되어 있어야 하나요?](#troubleshooting-blueprints-3) + [메시지의 일부만 임베딩하도록 지정할 수 있나요?](#troubleshooting-blueprints-4) + [여러 Amazon MSK 주제에서 데이터를 읽을 수 있나요?](#troubleshooting-blueprints-5) + [Amazon MSK 주제 이름을 정규식으로 구성할 수 있나요?](#troubleshooting-blueprints-6) + [Amazon MSK 주제에서 읽을 수 있는 메시지의 최대 크기는 얼마인가요?](#troubleshooting-blueprints-7) + [어떤 유형의 OpenSearch가 지원되나요?](#troubleshooting-blueprints-8) + [OpenSearch Serverless 컬렉션에서 벡터 검색 컬렉션, 벡터 인덱스, 벡터 필드를 사용해야 하는 이유는 무엇인가요?](#troubleshooting-blueprints-9) + [벡터 필드의 차원으로 무엇을 설정해야 하나요?](#troubleshooting-blueprints-10) + [구성된 OpenSearch 인덱스에서 출력은 어떻게 보이나요?](#troubleshooting-blueprints-11) + [OpenSearch 인덱스에 저장되는 문서에 추가할 메타데이터 필드를 지정할 수 있나요?](#troubleshooting-blueprints-12) + [OpenSearch 인덱스에서 중복 항목이 발생할 수 있나요?](#troubleshooting-blueprints-13) + [여러 OpenSearch 인덱스로 데이터를 전송할 수 있나요?](#troubleshooting-blueprints-14) + [하나의 AWS 계정계정에 여러 실시간 벡터 임베딩 애플리케이션을 배포할 수 있나요?](#troubleshooting-blueprints-15) + [여러 실시간 벡터 임베딩 애플리케이션이 동일한 데이터 소스 또는 싱크를 사용할 수 있나요?](#troubleshooting-blueprints-16) + [애플리케이션이 교차 계정 연결을 지원하나요?](#troubleshooting-blueprints-17) + [애플리케이션이 교차 리전 연결을 지원하나요?](#troubleshooting-blueprints-18) + [Amazon MSK 클러스터와 OpenSearch 컬렉션이 서로 다른 VPC 또는 서브넷에 있을 수 있나요?](#troubleshooting-blueprints-19) + [애플리케이션에서 지원하는 임베딩 모델은 무엇인가요?](#troubleshooting-blueprints-20) + [워크로드에 따라 애플리케이션의 성능을 미세 조정할 수 있나요?](#troubleshooting-blueprints-21) + [어떤 Amazon MSK 인증 유형이 지원되나요?](#troubleshooting-blueprints-22) + [`sink.os.bulkFlushIntervalMillis`란 무엇이며 어떻게 설정하나요?](#troubleshooting-blueprints-23) + [Managed Service for Apache Flink 애플리케이션을 배포할 때 Amazon MSK 주제의 어느 지점부터 메시지 읽기를 시작하나요?](#troubleshooting-blueprints-24) + [`source.msk.starting.offset`을 어떻게 사용하나요?](#troubleshooting-blueprints-25) + [지원되는 청킹 전략은 무엇인가요?](#troubleshooting-blueprints-26) + [벡터 데이터 저장소에서 레코드를 어떻게 읽나요?](#troubleshooting-blueprints-27) + [소스 코드에 대한 새로운 업데이트는 어디에서 찾을 수 있나요?](#troubleshooting-blueprints-28) + [AWS CloudFormation 템플릿을 변경하고 Managed Service for Apache Flink 애플리케이션을 업데이트할 수 있나요?](#troubleshooting-blueprints-29) + [에서 사용자를 대신하여 애플리케이션을 AWS 모니터링하고 유지 관리하나요?](#troubleshooting-blueprints-30) + [이 애플리케이션이 데이터를 AWS 계정외부로 이동하나요?](#troubleshooting-blueprints-31) ## 이 블루프린트는 어떤 AWS 리소스를 생성하나요? 계정에 배포된 리소스를 찾으려면 AWS CloudFormation 콘솔로 이동하여 Managed Service for Apache Flink 애플리케이션에 제공한 이름으로 시작하는 스택 이름을 식별합니다. **리소스** 탭을 선택하여 스택의 일부로 생성된 리소스를 확인합니다. 스택이 생성하는 주요 리소스는 다음과 같습니다. + 실시간 벡터 임베딩 Managed Service for Apache Flink 애플리케이션 + 실시간 벡터 임베딩 애플리케이션의 소스 코드를 저장하는 Amazon S3 버킷 + 로그를 저장하는 CloudWatch 로그 그룹 및 로그 스트림 + 리소스를 조회하고 생성하는 Lambda 함수 + Lambda, Managed Service for Apache Flink 애플리케이션, Amazon Bedrock, Amazon OpenSearch Service에 액세스하기 위한 IAM 역할 및 정책 + Amazon OpenSearch Service 데이터 액세스 정책 + Amazon Bedrock 및 Amazon OpenSearch Service에 액세스하기 위한 VPC 엔드포인트 ## AWS CloudFormation 스택 배포가 완료된 후 내 작업은 무엇입니까? AWS CloudFormation 스택 배포가 완료되면 Managed Service for Apache Flink 콘솔에 액세스하여 블루프린트 Managed Service for Apache Flink 애플리케이션을 찾습니다. **구성** 탭에서 모든 런타임 속성이 올바르게 설정되어 있는지 확인합니다. 속성이 많으면 다음 페이지로 이어질 수 있습니다. 설정이 정확하다는 확신이 들면 **실행**을 선택합니다. 애플리케이션은 주제에서 메시지를 수집하기 시작합니다. 새 릴리스를 확인하려면 [https://github.com/awslabs/real-time-vectorization-of-streaming-data/releases](https://github.com/awslabs/real-time-vectorization-of-streaming-data/releases) 페이지를 참조하세요. ## 소스 Amazon MSK 주제의 데이터는 어떤 구조로 구성되어 있어야 하나요? 현재 정형 및 비정형 소스 데이터를 모두 지원합니다. + 비정형 데이터는 `STRING`에서 `source.msk.data.type`으로 표시됩니다. 데이터는 들어오는 메시지 값을 그대로 읽습니다. + 조화된 JSON 데이터도 지원하며, 이는 `source.msk.data.type`에서 `JSON`으로 지정됩니다. 데이터는 반드시 JSON 형식이어야 합니다. 애플리케이션은 잘못된 형식의 JSON을 수신하면 실패합니다. + JSON을 소스 데이터 유형으로 사용할 경우 모든 소스 주제의 메시지가 유효한 JSON인지 반드시 확인해야 합니다. 이 설정에서 JSON 객체가 아닌 데이터를 포함한 주제를 구독하면 애플리케이션은 실패합니다. 한 이상의 주제에 정형 데이터와 비정형 데이터가 혼합된 경우 Managed Service for Apache Flink 애플리케이션에서 소스 데이터를 비정형 데이터로 구성하는 것이 좋습니다. ## 메시지의 일부만 임베딩하도록 지정할 수 있나요? + `source.msk.data.type`이 `STRING`인 비정형 입력 데이터의 경우 애플리케이션은 메시지 전체를 임베딩하며 구성된 OpenSearch 인덱스에 전체 메시지를 저장합니다. + `source.msk.data.type`이 `JSON`인 정형 입력 데이터의 경우, `embed.input.config.json.fieldsToEmbed` 값을 설정해 JSON 객체에서 임베딩할 필드를 지정할 수 있습니다. 이 설정은 최상위 JSON 필드만 지원하며 중첩 JSON이나 JSON 배열이 포함된 메시지에는 사용할 수 없습니다. 전체 JSON을 임베딩하려면 .\$1를 사용하세요. ## 여러 Amazon MSK 주제에서 데이터를 읽을 수 있나요? 네, 이 애플리케이션은 여러 Amazon MSK 주제에서 데이터를 읽을 수 있습니다. 모든 주제의 데이터는 동일한 유형(STRING 또는 JSON)이어야 하며, 그렇지 않으면 애플리케이션이 실패할 수 있습니다. 모든 주제에서 읽은 데이터는 항상 하나의 OpenSearch 인덱스에 저장됩니다. ## Amazon MSK 주제 이름을 정규식으로 구성할 수 있나요? `source.msk.topic.names`는 정규식 목록을 지원하지 않습니다. 쉼표로 구분된 주제 이름 목록 또는 모든 주제를 포함하기 위한 `.*` 정규식을 지원합니다. ## Amazon MSK 주제에서 읽을 수 있는 메시지의 최대 크기는 얼마인가요? 처리할 수 있는 메시지의 최대 크기는 현재 25,000,000으로 설정된 Amazon Bedrock InvokeModel 본문 제한에 의해 결정됩니다. 자세한 내용은 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html#API_runtime_InvokeModel_RequestBody)을 참조하세요. ## 어떤 유형의 OpenSearch가 지원되나요? OpenSearch 도메인과 컬렉션을 모두 지원합니다. OpenSearch 컬렉션을 사용하는 경우 이 애플리케이션에서 사용하기 위해 벡터 컬렉션을 사용하고 벡터 인덱스를 생성해야 합니다. 이렇게 하면 데이터를 쿼리하기 위해 OpenSearch 벡터 데이터베이스 기능을 사용할 수 있습니다. 자세한 내용은 [Amazon OpenSearch Service의 벡터 데이터 베이스 기능 설명](https://aws.amazon.com/blogs/big-data/amazon-opensearch-services-vector-database-capabilities-explained/)을 참조하세요. ## OpenSearch Serverless 컬렉션에서 벡터 검색 컬렉션, 벡터 인덱스, 벡터 필드를 사용해야 하는 이유는 무엇인가요? OpenSearch Serverless의 *벡터 검색* 컬렉션 유형은 확장 가능하고 성능이 우수한 유사성 검색 기능을 제공합니다. 이는 최신 기계 학습(ML) 기반 증강 검색 환경과 생성형 인공 지능(AI) 애플리케이션을 구축하는 과정을 간소화합니다. 자세한 내용은 [벡터 검색 컬렉션 작업](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-vector-search.html?icmpid=docs_console_unmapped)을 참조하세요. ## 벡터 필드의 차원으로 무엇을 설정해야 하나요? 벡터 필드의 차원은 사용할 임베딩 모델에 따라 설정합니다. 다음 표를 참조하고 해당 설명서에서 이러한 값을 확인합니다. **벡터 필드 차원** | Amazon Bedrock 벡터 임베딩 모델 이름 | 모델이 제공하는 출력 차원 지원 | | --- | --- | | Amazon Titan Text Embeddings V1 | 1,536 | | Amazon Titan Text Embeddings V2 | 1,024(기본값), 384, 256 | | Amazon Titan Multimodal Embeddings G1 | 1,024(기본값), 384, 256 | | Cohere Embed English | 1,024 | | Cohere Embed Multilingual | 1,024 | ## 구성된 OpenSearch 인덱스에서 출력은 어떻게 보이나요? OpenSearch 인덱스의 모든 문서에는 다음 필드가 포함됩니다. + **original\$1data**: 임베딩을 생성하는 데 사용된 데이터입니다. STRING 유형의 경우 전체 메시지입니다. JSON 객체의 경우 임베딩에 사용된 JSON 객체입니다. 이는 메시지의 전체 JSON이 될 수도 있고 JSON 내 지정된 필드가 될 수도 있습니다. 예를 들어, 들어오는 메시지에서 이름 필드가 임베딩 대상으로 선택된 경우 출력은 다음과 같습니다. ``` "original_data": "{\"name\":\"John Doe\"}" ``` + **embedded\$1data**: Amazon Bedrock에서 생성한 임베딩의 벡터 부동 배열입니다. + **날짜**: 문서가 OpenSearch에 저장된 시점의 UTC 타임스탬프입니다. ## OpenSearch 인덱스에 저장되는 문서에 추가할 메타데이터 필드를 지정할 수 있나요? 아니요. 현재 OpenSearch 인덱스에 저장되는 최종 문서에 추가 필드를 포함하는 기능은 지원하지 않습니다. ## OpenSearch 인덱스에서 중복 항목이 발생할 수 있나요? 애플리케이션 구성 방식에 따라 인덱스에 중복 메시지가 나타날 수 있습니다. 일반적인 원인은 애플리케이션 재시작입니다. 애플리케이션은 기본적으로 소스 주제의 가장 이른 메시지부터 읽도록 구성되어 있습니다. 구성을 변경하면 애플리케이션이 재시작되며 주제의 모든 메시지를 다시 처리합니다. 재처리를 방지하려면 source.msk.starting.offset 사용 방법에 대한 설명서를 참조하고 애플리케이션의 시작 오프셋을 올바르게 설정합니다. ## 여러 OpenSearch 인덱스로 데이터를 전송할 수 있나요? 아니요. 애플리케이션은 하나의 OpenSearch 인덱스에만 데이터를 저장하는 것을 지원합니다. 여러 인덱스에 벡터화 출력을 구성하려면 별도의 Managed Service for Apache Flink 애플리케이션을 배포해야 합니다. ## 하나의 AWS 계정계정에 여러 실시간 벡터 임베딩 애플리케이션을 배포할 수 있나요? 예. 각 애플리케이션에 고유한 이름이 있는 경우 하나의 AWS 계정 에 여러 실시간 벡터 임베딩 Managed Service for Apache Flink 애플리케이션을 배포할 수 있습니다. ## 여러 실시간 벡터 임베딩 애플리케이션이 동일한 데이터 소스 또는 싱크를 사용할 수 있나요? 예. 동일한 주제에서 데이터를 읽거나 동일한 인덱스에 데이터를 저장하는 여러 실시간 벡터 임베딩 Managed Service for Apache Flink 애플리케이션을 생성할 수 있습니다. ## 애플리케이션이 교차 계정 연결을 지원하나요? 아니요. 애플리케이션이 성공적으로 실행되려면 Amazon MSK 클러스터와 OpenSearch 컬렉션이 Managed Service for Apache Flink 애플리케이션을 설정하려는 AWS 계정 동일한에 있어야 합니다. ## 애플리케이션이 교차 리전 연결을 지원하나요? 아니요. 애플리케이션은 Amazon MSK 클러스터와 OpenSearch 컬렉션이 Managed Service for Apache Flink 애플리케이션과 동일한 리전에 있는 경우에만 Managed Service for Apache Flink 애플리케이션을 배포할 수 있습니다. ## Amazon MSK 클러스터와 OpenSearch 컬렉션이 서로 다른 VPC 또는 서브넷에 있을 수 있나요? 예. 동일한 AWS 계정에 있는 경우 Amazon MSK 클러스터와 OpenSearch 컬렉션이 서로 다른 VPC 및 서브넷에 있어도 지원합니다. 설정이 올바른지 확인하려면 (일반적인 MSF 문제 해결)을 참조하세요. ## 애플리케이션에서 지원하는 임베딩 모델은 무엇인가요? 현재 해당 애플리케이션은 Bedrock에서 지원하는 모든 모델을 지원합니다. 다음이 포함됩니다. + Amazon Titan Embeddings G1 - Text + Amazon Titan Text Embeddings V2 + Amazon Titan Multimodal Embeddings G1 + Cohere Embed English + Cohere Embed Multilingual ## 워크로드에 따라 애플리케이션의 성능을 미세 조정할 수 있나요? 예. 애플리케이션의 처리량은 여러 요소에 따라 달라지며, 이 모든 요소는 고객이 제어할 수 있습니다. 1. **AWS MSF KPUs** 애플리케이션은 기본 병렬 처리 인자 2와 KPU 1당 병렬 처리로 배포되며 자동 조정이 켜져 있습니다. 그러나 워크로드에 따라 Managed Service for Apache Flink 애플리케이션의 조정을 구성할 것을 권장합니다. 자세한 내용은 [Managed Service for Apache Flink 애플리케이션 리소스 검토](https://docs.aws.amazon.com/managed-flink/latest/java/how-resources.html)를 참조하세요. 1. **Amazon Bedrock**: 선택한 Amazon Bedrock 온디맨드 모델에 따라 적용되는 할당량이 다를 수 있습니다. 서비스가 처리할 수 있는 워크로드를 확인하려면 Bedrock 서비스 할당량을 검토합니다. 자세한 내용은 [Amazon Bedrock 할당량](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas.html)을 참조하세요. 1. **Amazon OpenSearch Service**: 경우에 따라 OpenSearch가 파이프라인의 병목 지점이 될 수 있습니다. 크기 조정 정보는 OpenSearch 크기 조정 [Amazon OpenSearch Service 도메인 크기 조절](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/sizing-domains.html)을 참조하세요. ## 어떤 Amazon MSK 인증 유형이 지원되나요? IAM MSK 인증 유형만 지원합니다. ## `sink.os.bulkFlushIntervalMillis`란 무엇이며 어떻게 설정하나요? Amazon OpenSearch Service로 데이터를 전송할 때 벌크 플러시 간격은 요청 내 작업 수나 요청 크기와 관계없이 벌크 요청이 실행되는 간격입니다. 기본값은 1밀리초입니다. 플러시 간격을 설정하면 데이터가 적시에 인덱싱되도록 하는 데 도움이 되지만, 간격이 너무 짧게 설정된 경우 오버헤드가 증가할 수 있습니다. 플러시 간격을 선택할 때 사용 사례와 적시 인덱싱의 중요성을 고려하여 적절한 값을 선택합니다. ## Managed Service for Apache Flink 애플리케이션을 배포할 때 Amazon MSK 주제의 어느 지점부터 메시지 읽기를 시작하나요? 애플리케이션은 애플리케이션의 런타임 구성에서 설정된 `source.msk.starting.offset` 구성에 지정된 오프셋부터 Amazon MSK 주제의 메시지를 읽기 시작합니다. `source.msk.starting.offset`이 명시적으로 설정되지 않은 경우 애플리케이션은 주제에서 사용 가능한 가장 이른 메시지부터 읽기 시작합니다. ## `source.msk.starting.offset`을 어떻게 사용하나요? 원하는 동작에 따라 `ource.msk.starting.offset`을 다음 값 중 하나로 명시적으로 설정합니다. + EARLIEST: 기본 설정으로, 파티션의 가장 오래된 오프셋부터 읽습니다. 다음과 같은 경우에 적합합니다. + Amazon MSK 주제 및 소비자 애플리케이션을 새로 생성한 경우 + 상태를 빌드하거나 재구성하기 위해 데이터를 재생해야 하는 경우 이는 이벤트 소싱 패턴을 구현하거나 데이터 기록의 전체 보기를 필요로 하는 신규 서비스를 초기화할 때 관련이 있습니다. + LATEST: Managed Service for Apache Flink 애플리케이션이 파티션 끝에서 메시지를 읽습니다. 새로 생성되는 메시지만 필요하고 기존 데이터를 처리할 필요가 없는 경우 권장됩니다. 이 설정에서는 소비자가 기존 메시지를 무시하고 업스트림 프로듀서가 새로 게시하는 메시지만 읽습니다. + COMMITTED: Managed Service for Apache Flink 애플리케이션이 소비 그룹의 커밋된 오프셋부터 메시지 소비를 시작합니다. 커밋된 오프셋이 없는 경우 EARLIEST 재설정 전략이 사용됩니다. ## 지원되는 청킹 전략은 무엇인가요? 입력을 청킹하기 위해 [langchain](https://js.langchain.com/v0.1/docs/get_started/introduction/) 라이브러리를 사용하고 있습니다. 입력 길이가 선택한 `maxSegmentSizeInChars`보다 큰 경우에만 청킹이 적용됩니다. 다음 다섯 가지 청킹 유형을 지원합니다. + `SPLIT_BY_CHARACTER`: 각 청크의 길이가 maxSegmentSizeInChars를 초과하지 않는 범위에서 가능한 많은 문자를 청크에 포함합니다. 공백을 고려하지 않으므로 단어가 잘릴 수 있습니다. + `SPLIT_BY_WORD`: 공백 문자를 기준으로 청킹합니다. 단어가 잘리지 않습니다. + `SPLIT_BY_SENTENCE`: Apache OpenNLP 라이브러리의 영어 문장 모델을 사용하여 문장 경계를 감지합니다. + `SPLIT_BY_LINE`: 줄바꿈 문자를 기준으로 청킹합니다. + `SPLIT_BY_PARAGRAPH`: 연속된 줄바꿈 문자를 기준으로 청킹합니다. 분할 전략은 앞서 제시된 순서에 따라 폴백되며, `SPLIT_BY_PARAGRAPH`와 같은 더 큰 청킹 전략은 `SPLIT_BY_CHARACTER`로 폴백됩니다. 예를 들어 `SPLIT_BY_LINE`을 사용하는 경우 줄이 너무 길면 문장 단위로 다시 청킹되며 각 청크는 가능한 많은 문장을 포함합니다. 문장이 너무 긴 경우 단어 단위로 청킹됩니다. 단어가 너무 긴 경우 문자 단위로 분할됩니다. ## 벡터 데이터 저장소에서 레코드를 어떻게 읽나요? 1. `source.msk.data.type`이 `STRING`인 경우 + **original\$1data**: Amazon MSK 메시지의 전체 원본 문자열입니다. + **embedded\$1data**: `chunk_data`가 비어 있지 않은 경우(청킹 적용됨) 여기에서 생성된 임베딩 벡터이며 청킹이 적용되지 않은 경우 `original_data`에서 생성된 임베딩 벡터입니다. + **chunk\$1data**: 원본 데이터가 청킹된 경우에만 나타납니다. `embedded_data`의 임베딩을 생성하는 데 사용된 원본 메시지의 청크를 포함합니다. 1. `source.msk.data.type`이 `JSON`인 경우 + **original\$1data**: JSON 키 필터링 적용 *후* Amazon MSK 메시지의 전체 원본 JSON입니다. + **embedded\$1data**: `chunk_data`가 비어 있지 않은 경우(청킹 적용됨) 여기에서 생성된 임베딩 벡터이며 청킹이 적용되지 않은 경우 `original_data`에서 생성된 임베딩 벡터입니다. + **chunk\$1key**: 원본 데이터가 청킹된 경우에만 나타납니다. `original_data` 내에 해당 청크가 속한 JSON 키를 포함합니다. 예를 들어, 중첩된 키의 경우 `jsonKey1.nestedJsonKeyA`와 같은 형태가 될 수 있으며, `original_data`의 예시에서는 *metadata*와 같은 키가 될 수 있습니다. + **chunk\$1data**: 원본 데이터가 청킹된 경우에만 나타납니다. `embedded_data`의 임베딩을 생성하는 데 사용된 원본 메시지의 청크를 포함합니다. 네, 이 애플리케이션은 여러 Amazon MSK 주제에서 데이터를 읽을 수 있습니다. 모든 주제의 데이터는 동일한 유형(STRING 또는 JSON)이어야 하며, 그렇지 않으면 애플리케이션이 실패할 수 있습니다. 모든 주제에서 읽은 데이터는 항상 하나의 OpenSearch 인덱스에 저장됩니다. ## 소스 코드에 대한 새로운 업데이트는 어디에서 찾을 수 있나요? 새 릴리스를 확인하려면 [https://github.com/awslabs/real-time-vectorization-of-streaming-data/releases](https://github.com/awslabs/real-time-vectorization-of-streaming-data/releases) 페이지를 참조하세요. ## AWS CloudFormation 템플릿을 변경하고 Managed Service for Apache Flink 애플리케이션을 업데이트할 수 있나요? 아니요. AWS CloudFormation 템플릿을 변경해도 Managed Service for Apache Flink 애플리케이션은 업데이트되지 않습니다. 의 새로운 변경 사항은 새 스택을 배포해야 AWS CloudFormation 함을 의미합니다. ## 에서 사용자를 대신하여 애플리케이션을 AWS 모니터링하고 유지 관리하나요? 아니요, AWS 는 사용자를 대신하여이 애플리케이션을 모니터링, 확장, 업데이트 또는 패치하지 않습니다. ## 이 애플리케이션이 데이터를 AWS 계정외부로 이동하나요? Managed Service for Apache Flink 애플리케이션에서 읽고 저장한 모든 데이터는 내에서 유지 AWS 계정 되며 계정에서 나가지 않습니다. # 실시간 벡터 임베딩 블루프린트 - 문제 해결 실시간 벡터 임베딩 블루프린트에 대한 다음 문제 해결 주제를 검토합니다. 실시간 벡터 임베딩 블루프린트에 관한 자세한 내용은 [실시간 벡터 임베딩 블루프린트](https://docs.aws.amazon.com/msk/latest/developerguide/ai-vector-embedding-integration-learn-more.html)를 참조하세요. **Topics** + [CloudFormation 스택 배포가 실패하거나 롤백되었습니다. 이를 해결하려면 어떻게 해야 하나요?](#troubleshooting-blueprints-deployment) + [애플리케이션이 Amazon MSK 주제의 시작 부분부터 메시지를 읽는 것을 원치 않습니다. 어떻게 해야 합니까?](#troubleshooting-blueprints-beginning) + [Managed Service for Apache Flink 애플리케이션에 문제가 있는지 어떻게 알 수 있으며 디버깅하려면 어떻게 해야 하나요?](#troubleshooting-blueprints-debug) + [Managed Service for Apache Flink 애플리케이션에 대해 모니터링해야 하는 핵심 지표는 무엇인가요?](#troubleshooting-blueprints-metrics) ## CloudFormation 스택 배포가 실패하거나 롤백되었습니다. 이를 해결하려면 어떻게 해야 하나요? + CFN 스택으로 이동하여 스택 실패 원인을 확인합니다. 실패 원인은 권한 누락, AWS 리소스 이름 충돌 등 다양할 수 있습니다. 배포 실패의 근본 원인을 수정합니다. 자세한 내용은 [CloudWatch 문제 해결 안내서](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html#basic-ts-guide)를 참조하세요. + [선택 사항] 하나의 VPC에서는 서비스당 하나의 VPC 엔드포인트만 존재할 수 있습니다. 동일한 VPC에서 Amazon OpenSearch Service 컬렉션으로 데이터를 쓰기 위해 여러 실시간 벡터 임베딩 블루프린트를 배포한 경우 VPC 엔드포인트를 공유하고 있을 수 있습니다. 이러한 엔드포인트는 이미 계정의 해당 VPC에 존재하고 있을 수도 있고, 최초의 실시간 벡터 임베딩 블루프린트 스택이 Amazon Bedrock 및 Amazon OpenSearch Service용 VPC 엔드포인트를 생성하여 계정에 배포된 모든 다른 스택이 이를 사용하고 있을 수도 있습니다. 스택이 실패한 경우 해당 스택이 Amazon Bedrock 및 Amazon OpenSearch Service용 VPC 엔드포인트를 생성했는지 확인하고 계정의 다른 곳에서 사용되지 않는 경우 삭제합니다. VPC 엔드포인트를 삭제하는 단계는 애플리케이션을 안전하게 삭제하는 방법에 대한 설명서를 참조하세요. + 계정의 다른 서비스나 애플리케이션이 해당 VPC 엔드포인트를 사용하고 있을 수 있습니다. 엔드포인트를 삭제하면 다른 서비스에 네트워크 중단이 발생할 수 있습니다. 이러한 엔드포인트를 삭제할 때는 주의해야 합니다. ## 애플리케이션이 Amazon MSK 주제의 시작 부분부터 메시지를 읽는 것을 원치 않습니다. 어떻게 해야 합니까? 원하는 동작에 따라 `source.msk.starting.offset`을 다음 값 중 하나로 명시적으로 설정해야 합니다. + **가장 빠른 오프셋**: 파티션에서 가장 오래된 오프셋입니다. + **최신 오프셋**: 소비자가 파티션의 끝에서 메시지를 읽습니다. + **커밋된 오프셋**: 소비자가 파티션 내에서 마지막으로 처리한 메시지부터 읽습니다. ## Managed Service for Apache Flink 애플리케이션에 문제가 있는지 어떻게 알 수 있으며 디버깅하려면 어떻게 해야 하나요? [Managed Service for Apache Flink troubleshooting guide](https://docs.aws.amazon.com/managed-flink/latest/java/troubleshooting-runtime.html)를 사용하여 애플리케이션의 Managed Service for Apache Flink 관련 문제를 디버깅합니다. ## Managed Service for Apache Flink 애플리케이션에 대해 모니터링해야 하는 핵심 지표는 무엇인가요? + 일반 Managed Service for Apache Flink 애플리케이션에서 사용할 수 있는 모든 지표는 애플리케이션 모니터링에 도움이 됩니다. 자세한 내용은 [Managed Service for Apache Flink의 지표 및 차원](https://docs.aws.amazon.com/managed-flink/latest/java/metrics-dimensions.html)을 참조하세요. + Amazon Bedrock 지표를 모니터링하려면 [Amazon Bedrock용 Amazon CloudWatch 지표](https://docs.aws.amazon.com/bedrock/latest/userguide/monitoring.html#runtime-cloudwatch-metrics)를 참조하세요. + 임베딩 생성 성능을 모니터링하기 위해 두 가지 새로운 지표를 추가했습니다. CloudWatch의 `EmbeddingGeneration` 작업 이름에서 확인할 수 있습니다. 두 가지 지표는 다음과 같습니다. + **BedrockTitanEmbeddingTokenCount**: Amazon Bedrock으로 전송되는 단일 요청에 포함된 토큰 수입니다. + **BedrockEmbeddingGenerationLatencyMs**: Amazon Bedrock에서 임베딩을 생성하기 위한 응답을 보내고 받는 데 걸린 시간을 밀리초 단위로 보고합니다. + Amazon OpenSearch Service 서버리스 컬렉션의 경우 `IngestionDataRate`, `IngestionDocumentErrors` 등의 지표를 사용할 수 있습니다. 자세한 내용은 [Amazon CloudWatch로 OpenSearch Serverless 모니터링](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/monitoring-cloudwatch.html)을 참조하세요. + 프로비저닝된 OpenSearch 지표는 [Amazon CloudWatch로 OpenSearch 클러스터 지표 모니터링](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/managedomains-cloudwatchmetrics.html)을 참조하세요.