뉴스 정보 뉴스 컴퓨터 소프트웨어 및 개발 , , ,

Azure Cosmos DB, Azure 기능이있는 이벤트 중심 GO 앱

Azure Cosmos DB, Azure 기능이있는 이벤트 중심 GO 앱

GO 프로그래밍 언어는 서버리스 애플리케이션을 구축하는 데 적합합니다. GO 애플리케이션은 정적으로 연결된 단일 바이너리로 쉽게 컴파일하여 배포를 간단하게 만들고 외부 종속성을 줄일 수 있습니다. 그들은 빠르게 시작하여 콜드 스타트에서 기능이 자주 호출되는 서버리스 환경에 이상적입니다. GO 애플리케이션은 또한 다른 언어에 비해 메모리를 적게 사용하는 경향이 있으므로 서버리스 시나리오에서 리소스 사용량을 최적화하고 비용을 줄이는 데 도움이됩니다.

Azure Functions는 사용자 정의 핸들러를 사용하여 GO를 지원하며 Extension 번들을 통해 트리거 및 입력 및 출력 바인딩을 사용할 수 있습니다. Azure 함수는 바인딩 (입력, 출력) 및 트리거를 사용하여 Azure Cosmos DB와 밀접하게 통합됩니다.

이 블로그 게시물은 이러한 Azure Cosmos DB 통합을 사용하는 Go를 사용하여 Azure 기능을 구축하는 방법을 안내합니다. 바인딩을 사용하면 Cosmos DB에 데이터를 쉽게 읽고 쓸 수 있으며 트리거는 Cosmos DB의 데이터 변경에 응답하는 이벤트 중심 응용 프로그램을 구축하는 데 유용합니다.

1 부 이 블로그의 Cosmos DB 컨테이너의 변경으로 인해 트리거되는 기능으로 시작하여 Raw Azure Functions Event Payload 및 Cosmos DB 문서를 단순히 기록합니다. Cosmos DB 에뮬레이터 및 Azure 기능 핵심 도구 덕분에 기능을 실행하고 Cosmos DB로 로컬로 테스트하는 방법을 배우게됩니다. Go 및 Azure 기능으로 처음 작업 한 경우 빨리 일어나서 실행하는 것이 도움이되어야합니다. Azure에 배포 할 수는 있지만이 블로그의 다음 부분에이를 저장합니다.

2 부 Cosmos DB 컨테이너의 문서에 대한 임베딩을 생성하는 다른 기능으로 뛰어납니다. 이 예제는 Azure Openai 임베딩 모델을 사용하여 컨테이너의 문서에 대한 임베딩을 생성 한 다음 삽입물을 컨테이너에 다시 저장합니다. 이는 시맨틱 검색 또는 기타 생성 AI 응용 프로그램이 필요한 응용 프로그램을 구축하는 데 유용합니다.

전체 코드는 Github 저장소를 확인하십시오.

1 부 : 간단한 COSMOS DB 트리거 기반 기능을 구축하고 로컬로 실행하십시오.

Cosmos DB 에뮬레이터를 사용하면 Cosmos DB를 로컬로 실행할 수 있듯이 Azure 기능 핵심 도구를 사용하면 기능을 로컬로 개발하고 테스트 할 수 있습니다.

Azure 함수 핵심 도구를 설치하여 시작하십시오; 참조 선적 서류 비치 특정 지침 당신의 OS. 예를 들어 Linux에서는 다음과 같습니다.

sudo apt-get update
sudo apt-get install azure-functions-core-tools-4

다음으로 Cosmos DB 에뮬레이터를 시작하십시오. 아래 명령은 Linux에 대한 것이며 Docker 컨테이너 기반 접근법을 사용합니다.. 나타내다 다른 옵션에 대한 문서에.

기계에 Docker를 설치하고 실행해야합니다. 설치되지 않은 경우 Docker 설치 안내서를 참조하십시오.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

docker run \
 --publish 8081:8081 \
 --name linux-emulator \
 -e AZURE_COSMOS_EMULATOR_PARTITION_COUNT=1 \
 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

에뮬레이터 SSL 인증서도 구성하십시오. 예를 들어, 내가 사용중인 Linux 시스템의 경우 인증서를 다운로드하고 인증서 번들을 재생하기 위해 다음 명령을 실행했습니다.

curl --insecure  > ~/emulatorcert.crt
sudo update-ca-certificates

다음 URL을 사용하여 브라우저를 사용하여 Cosmos DB 데이터 탐색기로 이동하십시오. http://localhost:8081/_explorer/index.html. 다음 리소스를 만듭니다.

  • 데이터베이스
  • 파티션 키가있는 컨테이너 /id – 이것은 소스 컨테이너입니다
  • 이름이있는 임대 컨테이너 leases 그리고 파티션 키 /id – 소스 컨테이너의 변경 사항을 추적하는 데 방아쇠가 사용합니다.

기능에 대한 코드로 Github 저장소를 복제하십시오.

git clone 
cd golang_cosmosdb_azure_functions/getting_started_guide

a local.settings.json Cosmos DB 관련 정보로 파일. 이전 단계에서 만든 것과 동일한 데이터베이스 및 컨테이너 이름을 사용하십시오. 그만큼 local.settings.json 파일은 로컬에서 실행할 때 기능 앱의 구성 설정을 저장하는 데 사용됩니다.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "custom",
    "COSMOS_CONNECTION": "AccountEndpoint=
    "COSMOS_DATABASE_NAME": "test",
    "COSMOS_CONTAINER_NAME": "tasks"
  }
}

COSMOS_CONNECTION Cosmos DB 에뮬레이터의 연결 문자열에 대한 정적 값이 있습니다. 변경하지 마십시오.

다음 명령을 사용하여 GO 기능 바이너리를 빌드하십시오. 이것은 이름이 지정된 이진 파일을 만듭니다 main 현재 디렉토리에서 :

로컬로 기능을 시작하십시오.

기능 앱을 시작하고 들어오는 요청을 듣습니다. 다음과 유사한 출력이 표시됩니다.

[2025-04-25T07:44:53.921Z] Worker process started and initialized.

Functions:

        processor: cosmosDBTrigger

For detailed output, run func with --verbose flag.
[2025-04-25T07:44:58.809Z] Host lock lease acquired by instance ID '0000000000000000000000006ADD8D3E'.

//...

Cosmos DB의 소스 컨테이너에 데이터를 추가하십시오. 에뮬레이터의 데이터 탐색기로 탐색하여이를 수행 할 수 있습니다. 예를 들어 다음 JSON이있는 문서를 추가하십시오.

{
  "id": "42",
  "description": "test"
}

문서가 컨테이너에 추가되면 기능을 자동으로 트리거해야합니다. 기능 앱의 로그를 확인하여 성공적으로 트리거되었는지 확인할 수 있습니다.

[2025-04-25T07:48:10.559Z] Executing 'Functions.processor' (Reason='New changes on container tasks at 2025-04-25T07:48:10.5593689Z', Id=7b62f8cf-683b-4a5b-9db0-83d049bc4c86)
[2025-04-25T07:48:10.565Z] processor function invoked...
[2025-04-25T07:48:10.565Z] Raw event payload: {{"[{\"id\":\"42\",\"description\":\"test\",\"_rid\":\"AxI2AL1rrFoDAAAAAAAAAA==\",\"_self\":\"dbs/AxI2AA==/colls/AxI2AL1rrFo=/docs/AxI2AL1rrFoDAAAAAAAAAA==/\",\"_etag\":\"\\\"00000000-0000-0000-b5b6-6123f4d401db\\\"\",\"_attachments\":\"attachments/\",\"_ts\":1745567285,\"_lsn\":4}]"}} {{processor 2025-04-25T07:48:10.560243Z 4f29b3f3-ba95-4043-9b67-2856a43b4734}}}
[2025-04-25T07:48:10.566Z] Cosmos DB document: {42  AxI2AL1rrFoDAAAAAAAAAA== dbs/AxI2AA==/colls/AxI2AL1rrFo=/docs/AxI2AL1rrFoDAAAAAAAAAA==/ "00000000-0000-0000-b5b6-6123f4d401db" attachments/ 1745567285 4}
[2025-04-25T07:48:10.566Z] Executed 'Functions.processor' (Succeeded, Id=7b62f8cf-683b-4a5b-9db0-83d049bc4c86, Duration=6ms)

//.....

작동 방식

코드의 매우 높은 수준의 개요는 다음과 같습니다.

  • main.go: a processor 엔드 포인트. 트리거되면 요청에서 Cosmos DB 트리거 페이로드를 읽고 중첩 문서를 구문 분석하고 정보를 기록하며 구조화 된 JSON 응답을 반환합니다. 그것은 유형과 도우미를 사용합니다 common패키지.
  • 일반적인 패키지: Cosmos DB 트리거 처리를위한 공유 유형 및 유틸리티가 포함되어 있습니다.
    • Payload.go: 트리거 페이로드, 문서 및 응답의 데이터 구조를 정의합니다.
    • parse.go: 제공 a Parse 트리거 페이로드의 중첩 된 JSON 구조에서 문서를 추출하고 비안 한 기능.

2 부 : Azure Openai를 사용하여 Cosmos DB 컨테이너의 문서에 대한 임베드를 생성합니다.

부호가 적고 성능이 높고 확장 성 특성 외에도 벡터 (의미 론적/유사성), 전체 텍스트 및 하이브리드 검색에 대한 지원은 Azure Cosmos DB가 생성 AI 응용 프로그램에 매우 적합합니다.

전자 상거래 플랫폼 용 제품 카탈로그 관리를위한 사용 사례를 고려하십시오. 신제품이 시스템에 추가 될 때마다 ( “소음이 취소 된 Bluetooth 헤드폰”과 같은 간단한 설명), 해당 항목을 의미 적으로 즉시 검색 할 수 있도록하려고합니다.

제품 문서가 Cosmos DB에 기록 되 자마자 Azure 함수는 트리거. 제품 설명을 추출하고 Azure Openai를 사용하여 벡터 임베딩을 생성하며 ENDEDDING을 출력 바인딩. 임베딩이 포함되면 이제 제품이 색인화되어 추가 노력없이 시맨틱 및 하이브리드 검색 쿼리에 대비할 수 있습니다.

임베딩을 생성하십시오

전제 조건

이 예제를 Azure에서 실행하므로 Azure 계정이 필요합니다. 없는 경우 무료 계정을 만들 수 있습니다.

NOSQL 계정에 대한 Azure Cosmos DB를 만듭니다. 벡터 인덱싱 및 검색 기능을 활성화-일회성 작업입니다.

이전과 마찬가지로 다음 리소스를 만들어야합니다.

  • 데이터베이스
  • 파티션 키가있는 컨테이너 /id – 이것은 소스 컨테이너입니다
  • 이름이있는 임대 컨테이너 leases 그리고 파티션 키 /id – 소스 컨테이너의 변경 사항을 추적하는 데 방아쇠가 사용합니다.

Cosmos DB 계정에 액세스하기 위해 관리 된 ID를 사용하도록 Azure 기능을 구성 했으므로 임대 컨테이너를 미리 작성해야합니다. 키 또는 연결 문자열을 사용할 필요가 없습니다.

Azure OpenAI 서비스 리소스를 만듭니다. Azure OpenAi Service는 GPT-4O, GPT-4O 미니 (및 기타) 및 임베딩 모델을 포함한 OpenAI 모델에 대한 액세스를 제공합니다. Azure AI Foundry Portal을 사용하여 선택한 임베딩 모델을 배포합니다 (예 : 사용했습니다. text-embedding-3-small 모델). Cosmos DB 계정과 마찬가지로 Azure Function App은 관리 된 ID를 사용하여 Azure OpenAI 서비스 리소스에 액세스합니다.

배포 리소스

오른쪽 디렉토리로 이동 :

cd ../embeddings_generator

필요한 리소스 및 구성과 함께 기능 앱의 배포를 단순화하려면 deploy.sh 스크립트. 높은 수준에서 IT :

  • Azure 리소스의 환경 변수를 설정합니다.
  • Azure Resource 그룹, 스토리지 계정 및 기능 앱 계획을 만듭니다.
  • 사용자 정의 GO 기반 Azure 기능 앱을 배포합니다.
  • Windows 용 Go Binary를 구축합니다.
  • 기능 앱을 Azure에 게시합니다.
  • 기능 앱 시스템 ID를 활성화하고 Cosmos DB 및 Azure OpenAI Resource Access에 필요한 역할을 제공합니다.

솔루션을 배포하기 전에 업데이트하십시오 local.settings.json. 이전 단계에서 만든 것과 동일한 데이터베이스 및 컨테이너 이름을 사용하십시오.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "custom",
    "COSMOS_CONNECTION__accountEndpoint": "
    "COSMOS_DATABASE_NAME": "name of the database",
    "COSMOS_CONTAINER_NAME": "name of the container",
    "COSMOS_HASH_PROPERTY": "hash",
    "COSMOS_VECTOR_PROPERTY": "embedding",
    "COSMOS_PROPERTY_TO_EMBED": "description",
    "OPENAI_DEPLOYMENT_NAME": "enter the embedding model deployment name e.g. text-embedding-3-small",
    "OPENAI_DIMENSIONS": "enter the dimensions e.g. 1536",
    "OPENAI_ENDPOINT": "
  }
}

  • cosmos_connection_accountendpoint: Azure Cosmos DB 계정의 Endpoint URL.
  • cosmos_database_name: 사용할 코스모스 DB 데이터베이스 이름.
  • cosmos_container_name: 사용할 코스모스 DB 컨테이너의 이름.
  • cosmos_hash_property: Cosmos DB 문서에서 해시로 사용되는 속성의 이름 (이를 수정할 필요가 없습니다).
  • cosmos_vector_property: Cosmos db에 벡터 임베딩을 저장하는 속성의 이름.
  • cosmos_property_to_embed: 값이 포함 된 속성의 이름. 문서 구조에 따라 이것을 변경하십시오.
  • OpenAi_deployment_name: 임베딩에 사용할 Azure Openai 모델 배포의 이름.
  • Openai_dimensions: 임베딩 벡터의 치수 수.
  • Openai_endpoint: Azure OpenAi 리소스의 EndPoint URL.

실행 deploy.sh 스크립트:

chmod +x deploy.sh
./deploy.sh

의 일부로 azure functionapp publish 스크립트에 사용 된 명령은 기존의 값을 덮어 쓰는 메시지가 표시됩니다. AzureWebJobsStorage 설정 local.settings.json Azure에 파일 – “아니오”를 선택하십시오.

엔드 투 엔드 예제를 실행하십시오

Cosmos DB의 소스 컨테이너에 데이터를 추가하십시오. 예를 들어 다음 JSON이있는 문서를 추가하십시오.

{
  "id": "de001c6d-4efe-4a65-a59a-39a0580bfa2a",
  "description": "Research new technology"
}

문서가 컨테이너에 추가되면 기능을 자동으로 트리거해야합니다. 기능 앱의 로그를 확인하여 성공적으로 트리거되었는지 확인할 수 있습니다.

func azure functionapp logstream

이와 유사한 로그를 볼 수 있습니다 (페이로드는 추가 데이터에 따라 다릅니다).

2025-04-23T05:34:41Z [Information] function invoked
2025-04-23T05:34:41Z [Information] cosmosVectorPropertyName: embedding
2025-04-23T05:34:41Z [Information] cosmosVectorPropertyToEmbedName: description
2025-04-23T05:34:41Z [Information] cosmosHashPropertyName: hash
2025-04-23T05:34:41Z [Information] Processing 1 documents
2025-04-23T05:34:41Z [Information] Processing document ID: de001c6d-4efe-4a65-a59a-39a0580bfa2a
2025-04-23T05:34:41Z [Information] Document data: Research new technology
2025-04-23T05:34:41Z [Information] New document detected, generated hash: 5bb57053273563e2fbd4202c666373ccd48f86eaf9198d7927a93a555aa200aa
2025-04-23T05:34:41Z [Information] Document modification status: true, hash: 5bb57053273563e2fbd4202c666373ccd48f86eaf9198d7927a93a555aa200aa
2025-04-23T05:34:41Z [Information] Created embedding for document: map[description:Research new technology id:de001c6d-4efe-4a65-a59a-39a0580bfa2a]
2025-04-23T05:34:41Z [Information] Adding 1 document with embeddings
2025-04-23T05:34:41Z [Information] Added enriched documents to binding output
2025-04-23T05:34:41Z [Information] Executed 'Functions.cosmosdbprocessor' (Succeeded, Id=91f4760f-047a-4867-9030-46a6602ab179, Duration=128ms)

//....

Cosmos DB에서 데이터를 확인하십시오. 당신은 다음을위한 임베딩을 볼 수 있어야합니다 description 에 저장된 문서의 속성 embedding 재산. 다음과 같이 보일 것입니다.

{
  "id": "de001c6d-4efe-4a65-a59a-39a0580bfa2a",
  "description": "Research new technology",
  "embedding": [
    0.028226057, -0.00958694
    //....
  ],
  "hash": "5bb57053273563e2fbd4202c666373ccd48f86eaf9198d7927a93a555aa200aa"
}

임베딩이 생성되면 생성 AI 애플리케이션과 통합 할 수 있습니다. 예를 들어, Azure Cosmos DB의 벡터 검색 기능을 사용하여 임베딩을 기반으로 유사성 검색을 수행 할 수 있습니다.

작동 방식

코드의 매우 높은 수준의 개요는 다음과 같습니다.

  • main.go: a cosmosdbprocessor엔드 포인트. 트리거되면 요청에서 Cosmos DB 트리거 페이로드를 읽고 중첩 된 문서를 구문 분석하고 Azure OpenAi를 사용하여 임베딩을 생성하며 풍부한 문서를 Cosmos DB 컨테이너에 다시 씁니다.
    • 노출 cosmosdbprocessor 수신 코스모스 DB 문서를 처리하는 엔드 포인트.
    • 각 문서의 경우 새로 수정되었는지 (해시 사용) (해시 사용)인지 확인하고 Azure Openai를 사용하여 임베딩 (벡터)을 생성하고 강화 된 문서를 출력을 준비합니다.
    • 함수 실행에 대한 로깅 및 오류보고를 처리합니다.
  • 일반적인 패키지: Cosmos DB 문서 처리를위한 공유 유틸리티 및 유형이 포함되어 있습니다.
    • 삽입: Azure Openai를 사용하여 임베딩의 생성을 처리합니다.
    • parse.go: Cosmos DB 트리거 페이로드에서 문서를 구문 분석하고 추출합니다.
    • Payload.go: 프로젝트 전반에 사용되는 페이로드 및 응답에 대한 데이터 구조를 정의합니다.

함수는 a를 사용합니다 hash 문서가 이미 처리되었는지 확인하는 속성. 만약 hash 값은 Cosmos DB에 저장된 것과 다릅니다. 이는 문서가 수정되었으며 재 처리해야 함을 의미합니다.

이 경우 함수는 새 임베딩을 생성하고 새로운 해시 값으로 문서를 업데이트합니다. 이렇게하면 함수가 무한 루프에 갇히지 않도록합니다. 만약 hash 값은 동일합니다. 문서가 수정되지 않았으며 재 처리 할 필요가 없음을 의미합니다. 이 경우, 함수는 문서가 변경되지 않았으며 새 임베딩을 생성하지 않는 것으로 기록됩니다.

이와 유사한 로그를 볼 수 있습니다.

2025-04-23T05:34:42Z   [Information]   function invoked
2025-04-23T05:34:42Z   [Information]   cosmosVectorPropertyName: embedding
2025-04-23T05:34:42Z   [Information]   cosmosVectorPropertyToEmbedName: description
2025-04-23T05:34:42Z   [Information]   cosmosHashPropertyName: hash
2025-04-23T05:34:42Z   [Information]   Processing 1 document
2025-04-23T05:34:42Z   [Information]   Processing document ID: de001c6d-4efe-4a65-a59a-39a0580bfa2a
2025-04-23T05:34:42Z   [Information]   Document data: Research new technology
2025-04-23T05:34:42Z   [Information]   Document unchanged, hash: 5bb57053273563e2fbd4202c666373ccd48f86eaf9198d7927a93a555aa200aa
2025-04-23T05:34:42Z   [Information]   Document modification status: false, hash:
2025-04-23T05:34:42Z   [Information]   Executed 'Functions.cosmosdbprocessor' (Succeeded, Id=f0cf039a-5de5-4cc1-b29d-928ce32b294e, Duration=6ms)

//....

리소스 삭제

Azure에서 만든 자원을 정리하십시오. Azure Portal 또는 Azure CLI를 사용하여이를 수행 할 수 있습니다. 예를 들어, 리소스 그룹과 모든 리소스를 삭제하려면 다음을 실행하십시오.

Cosmos DB 계정, 기능 앱 및 스토리지 계정을 포함한 리소스 그룹 및 모든 리소스가 삭제됩니다.

결론

이 블로그 게시물에서는 Cosmos DB 트리거 및 바인딩을 사용하는 Go를 사용하여 Azure 기능을 구축하는 방법을 배웠습니다. 원시 이벤트 페이로드와 Cosmos DB 문서를 기록한 간단한 기능으로 시작한 다음 Azure OpenAI를 사용하여 Cosmos DB 컨테이너에 문서에 대한 임베드를 생성하는보다 복잡한 기능으로 이동했습니다. 또한 Cosmos DB 에뮬레이터 및 Azure 기능 핵심 도구를 사용하여 기능을 로컬로 실행하는 방법과 Azure에 배치하는 방법을 배웠습니다.

이 예제를 GO 및 AZURE 기능으로 자신의 서버리스 애플리케이션을 구축하기위한 시작점으로 사용할 수 있습니다. Azure Functions의 확장 성 및 Cosmos DB와의 통합과 함께 GO의 성능과 단순성의 조합은 현대적인 응용 프로그램을 구축하기위한 강력한 플랫폼입니다.

출처 참조

Tag

Related Posts

Post Comment

당신은 놓쳤을 수도 있습니다