ai_embed_text 플러그 인(미리 보기)
적용 대상: ✅Azure Data Explorer
플러그 인을 ai_embed_text 사용하면 언어 모델을 사용하여 텍스트를 포함할 수 있으므로 RAG(검색 보강 세대) 애플리케이션 및 의미 체계 검색과 같은 다양한 AI 관련 시나리오를 사용할 수 있습니다. 플러그 인은 관리 ID를 사용하여 액세스하는 Azure OpenAI Service 포함 모델을 지원합니다.
필수 조건
구문
evaluateai_embed_text (text, connectionString [, options [, IncludeErrorMessages]])
구문 규칙에 대해 자세히 알아봅니다.
매개 변수
| 이름 | Type | 필수 | 설명 |
|---|---|---|---|
| text | string |
✔️ | 포함할 텍스트입니다. 값은 열 참조 또는 상수 스칼라일 수 있습니다. |
| connectionString | string |
✔️ | 언어 모델의 연결 문자열 형식<ModelDeploymentUri>;<AuthenticationMethod>으로, 각각 AI 모델 배포 URI 및 인증 방법으로 바꿉 <ModelDeploymentUri> <AuthenticationMethod> 다. |
| options | dynamic |
포함 모델 엔드포인트에 대한 호출을 제어하는 옵션입니다. 옵션을 참조하세요. | |
| IncludeErrorMessages | bool |
출력 테이블의 새 열에서 오류를 출력할지 여부를 나타냅니다. 기본값: false. |
옵션
다음 표에서는 포함 모델 엔드포인트에 대한 요청이 수행되는 방식을 제어하는 옵션에 대해 설명합니다.
| 속성 | 형식 | 설명 |
|---|---|---|
RecordsPerRequest |
int |
요청당 처리할 레코드 수를 지정합니다. 기본값: 1. |
CharsPerRequest |
int |
요청당 처리할 최대 문자 수를 지정합니다. 기본값: 0 (무제한). Azure OpenAI는 토큰 수를 계산하며 각 토큰은 약 4자로 변환됩니다. |
RetriesOnThrottling |
int |
제한이 발생할 때 다시 시도 횟수를 지정합니다. 기본값: 0. |
GlobalTimeout |
timespan |
포함 모델의 응답을 기다리는 최대 시간을 지정합니다. 기본값: null |
ModelParameters |
dynamic |
모니터링 목적으로 차원 또는 사용자 식별자 포함과 같은 포함 모델과 관련된 매개 변수입니다. 기본값: null. |
ReturnSuccessfulOnly |
bool |
성공적으로 처리된 항목만 반환할지 여부를 나타냅니다. 기본값: false. IncludeErrorMessages 매개 변수가 설정된 true경우 이 옵션은 항상 .로 false설정됩니다. |
관리 ID 및 설명선 정책 구성
플러그 인을 ai_embed_text 사용하려면 다음 정책을 구성해야 합니다.
이러한 정책을 구성하려면 다음 단계의 명령을 사용합니다.
관리 ID를 구성합니다.
.alter-merge cluster policy managed_identity ``` [ { "ObjectId": "system", "AllowedUsages": "AzureAI" } ] ```설명선 정책을 구성합니다.
.alter-merge cluster policy callout ``` [ { "CalloutType": "azure_openai", "CalloutUriRegex": "https://[A-Za-z0-9\\-]{3,63}\\.openai\\.azure\\.com/.*", "CanCall": true } ] ```
반품
다음 새 포함 열을 반환합니다.
- 포함 값이 포함된 _embedding 접미사가 있는 열
- 오류를 반환하도록 구성된 경우 _embedding_error 접미사가 있는 열로, 오류 문자열이 포함되거나 작업이 성공하면 비어 있습니다.
입력 형식에 따라 플러그 인은 다른 결과를 반환합니다.
- 열 참조: 참조 열 이름 앞에 추가 열이 있는 하나 이상의 레코드를 반환합니다. 예를 들어 입력 열의 이름이 TextData이면 출력 열의 이름은 TextData_embedding 지정되고 오류를 반환하도록 구성된 경우 TextData_embedding_error.
- 상수 스칼라: 접두사로 지정되지 않은 추가 열이 있는 단일 레코드를 반환합니다. 열 이름은 _embedding 오류를 반환하도록 구성된 경우 _embedding_error.
예제
다음 예제에서는 Azure OpenAI Embedding 모델을 사용하여 텍스트를 Embed this text using AI 포함합니다.
let expression = 'Embed this text using AI';
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
evaluate ai_embed_text(expression, connectionString)
다음 예제에서는 Azure OpenAI 포함 모델을 사용하여 여러 텍스트를 포함합니다.
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
let options = dynamic({
"RecordsPerRequest": 10,
"CharsPerRequest": 10000,
"RetriesOnThrottling": 1,
"GlobalTimeout": 2m
});
datatable(TextData: string)
[
"First text to embed",
"Second text to embed",
"Third text to embed"
]
| evaluate ai_embed_text(TextData, connectionString, options , true)
모범 사례
Azure OpenAI 포함 모델에는 많은 제한이 적용되며 이 플러그 인에 대한 잦은 호출은 제한 제한에 빠르게 도달할 수 있습니다.
제한 및 비용을 최소화하면서 플러그 인을 효율적으로 사용 ai_embed_text 하려면 다음 모범 사례를 따르세요.
- 컨트롤 요청 크기: 요청
CharsPerRequest당 레코드(RecordsPerRequest) 및 문자 수를 조정합니다. - 쿼리 제한 시간 제어: 쿼리 제한 시간보다 낮은 값으로 설정
GlobalTimeout하여 해당 시점까지의 성공적인 호출에서 진행률이 손실되지 않도록 합니다. - 속도 제한을 더 정상적으로 처리: 제한 시 다시 시도 설정(
RetriesOnThrottling).