영어로 읽기

다음을 통해 공유


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: 시스템 할당 관리 ID가 Azure OpenAI 서비스에 인증되도록 허용합니다.
  • 설명선: AI 모델 엔드포인트 도메인에 권한을 부여합니다.

이러한 정책을 구성하려면 다음 단계의 명령을 사용합니다.

  1. 관리 ID를 구성합니다.

    .alter-merge cluster policy managed_identity
    ```
    [
      {
        "ObjectId": "system",
        "AllowedUsages": "AzureAI"
      }
    ]
    ```
    
  2. 설명선 정책을 구성합니다.

    .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).