인덱싱된 OneLake 기술 원본 만들기

참고

Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.

REST API를 사용하여 인덱싱된 OneLake 지식 원본2026-11-01-preview을 만들어 Microsoft OneLake 파일을 수집하고 Foundry IQ(Azure AI 검색)에서 원본 권한을 유지합니다. 지식 원본은 독립적으로 생성되고, 지식 베이스에서 참조되며, 지식 베이스가 런타임에 쿼리될 때 근거 데이터로 사용됩니다.

Important

이 문서에서 (미리 보기)로 표시된 기능 또는 성능은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.

Foundry IQ(Azure AI 검색)에 대한 미리 보기 약관은 미리 보기 기능을 참조하세요.

외부 데이터 원본에 연결할 때 적용되는 용어는 외부 데이터 원본을 참조하세요.

인덱싱된 OneLake 지식 원본을 만들 때 Foundry IQ는 다음 개체를 자동으로 생성합니다.

  • 레이크하우스를 나타내는 데이터 원본입니다.
  • 레이크하우스에서 다중 모달 콘텐츠를 분할하여 선택적으로 벡터화할 수 있는 기술입니다.
  • 보강된 콘텐츠를 저장하고 에이전트 검색 조건을 충족하는 인덱스입니다.
  • 이전 개체를 사용하여 인덱싱 및 보강 파이프라인을 구동하는 인덱서입니다.

생성된 인덱서는 OneLake 인덱서에 부합합니다. 필수 구성 요소, 지원되는 작업, 문서 형식 및 제한 사항은 OneLake 지식 원본에도 적용됩니다. OneLake 인덱서 설명서 및 인덱서 제한을 참조하세요. 일반적인 바로 가기 수집 지원은 이 미리 보기에서 바로 가기 파생 콘텐츠를 제외하는 권한 인식 검색과는 별개입니다. 생성된 기술 세트가 외부 서비스를 호출하는 경우 해당 기술의 입력 및 서비스 제한도 적용됩니다.

필수 구성 요소

  • 에이전트 검색을 제공하는 지역의 Azure 퍼블릭 클라우드의 Foundry IQ 서비스입니다.

  • OneLake 인덱서 필수 구성 요소 및 데이터 준비 완료

  • OneLake 권한 보존 필수 구성 요소 완료 Foundry IQ 서비스에는 시스템 할당 관리 ID가 있어야 합니다. Fabric 작업 영역에서 이 ID에 관리자 역할을 할당합니다.

  • 지식 원본을 만들 수 있는 권한입니다. 사용자 계정에 할당된 Search Service 기여자 및 검색 인덱스 데이터 기여자 역할을 사용하여 키 없는 인증을 구성하거나 관리자 API 키를 사용합니다.

  • REST 클라이언트입니다. 이 문서의 요청에는 Search Service REST API 버전 2026-11-01-preview를 사용하세요. 키 없는 인증의 경우 Authorization 헤더에 사용할 Microsoft Entra ID 토큰을 가져옵니다.

  • standard을 contentExtractionMode(으)로 구성한 경우, Foundry Tools의 Content Understanding에서 지원하는 지역에 있는 Microsoft Foundry 리소스 및 해당 https://<resource-name>.services.ai.azure.com 엔드포인트를 사용합니다. 임베딩 모델을 배포하고, 이미지 설명을 사용하도록 설정한 경우 멀티모달 채팅 모델도 배포합니다. 이 문서의 예제에서는 minimal를 사용하고 이미지 언어화를 사용하지 않도록 설정합니다.

  • 관리 ID를 사용해 Azure OpenAI 임베딩 또는 이미지 언어화를 호출하는 경우, 와 일치하는 Azure OpenAI 또는 상위 Foundry 리소스에서 선택한 ID에 resourceUri를 할당합니다. 추출 서비스 권한은 별개입니다. 역할 할당을 참조하세요.

  • 프라이빗 수집의 경우 공유 프라이빗 링크 워크로드 요구 사항을 충족하는 적격 S2, S3, L1 또는 L2 Dedicated 서비스를 사용합니다. Microsoft.Fabric/privateLinkServicesForFabric에 설명된 대상과 workspace 그룹 ID를 사용하여 Fabric 작업 영역에 대한 공유 프라이빗 링크를 만들고 승인합니다. 파이프라인에서 사용하는 보호된 추출, 모델 또는 기타 Azure 종속성에 대해 승인된 링크를 구성합니다.

Limitations

서버리스 및 S3 HD는 프라이빗 인덱서 실행 또는 아웃바운드 검색 공유 프라이빗 링크를 지원하지 않습니다. 네트워크 보안 경계 구성은 지원되는 공용 엔드포인트 액세스를 제어합니다. 프라이빗 실행을 사용하도록 설정하지는 않습니다.

OneLake 권한 수집을 사용하도록 설정하면 자산 저장소, 보강 캐시 및 그래프 추출 설정을 생략합니다. 지원되는 기술 및 기타 미리 보기 제약 조건은 OneLake 권한 유지 제한 사항을 참조하세요.

기존 지식 원본 확인

기술 자료는 재사용 가능한 최상위 개체입니다. 이름을 선택하거나 새 개체를 만들기 전에 기존 knowledge source를 확인합니다.

GET /knowledgesources?api-version=2026-11-01-preview&$select=name,kind를 검색 엔드포인트로 보내세요.

단일 정의를 검토하려면 GET /knowledgesources/<knowledge-source-name>?api-version=2026-11-01-preview를 보냅니다. 각 요청에 인증 헤더를 포함하세요.

기술 자료 만들기

다음 REST 요청을 사용하여 지식 원본을 만듭니다. 이 예제에서는 최소한의 콘텐츠 추출을 사용하고, 이미지 설명 생성을 사용하지 않도록 설정하고, OneLake 권한 보존을 사용하도록 설정합니다.

OneLake 권한 보존 (미리 보기)

indexedOneLakeParameters.ingestionParameters.ingestionPermissionOptions에서 oneLakeParentFolders 및 oneLakeLakehouseId를 모두 설정합니다. 직접 OneLake 데이터 원본의 indexerPermissionOptions와 달리, 보안 인덱싱된 OneLake 지식 원본에는 두 값이 모두 함께 필요합니다.

Foundry IQ 서비스 이름, 액세스 토큰, 작업 영역 ID 및 lakehouse ID를 사용자의 값으로 바꿉니다.

PUT https://<search-service>.search.windows.net/knowledgesources/my-secured-onelake-ks?api-version=2026-11-01-preview
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "my-secured-onelake-ks",
  "kind": "indexedOneLake",
  "indexedOneLakeParameters": {
    "fabricWorkspaceId": "<fabric-workspace-id>",
    "lakehouseId": "<lakehouse-id>",
    "ingestionParameters": {
      "contentExtractionMode": "minimal",
      "disableImageVerbalization": true,
      "ingestionPermissionOptions": [
        "oneLakeParentFolders",
        "oneLakeLakehouseId"
      ]
    }
  }
}

권한 구성 및 해당 제약 조건은 인덱싱된 OneLake 지식 원본 구성을 참조하세요.

생성 응답에는 indexedOneLakeParameters.createdResources 아래에 생성된 개체가 나열됩니다. 지식 소스는 권한이 설정된 인덱스, 필드 매핑 및 청크 프로젝션을 생성합니다. 이러한 매핑을 별도로 구성할 필요가 없습니다. 생성된 필드 요구 사항 및 쿼리 시간 권한 부여는 OneLake 권한 유지를 참조하세요.

선택적 설정은 다음 속성 경로를 사용합니다.

  • indexedOneLakeParameters.targetPath: 수집을 레이크하우스 내의 폴더로 제한합니다. 바로 가기 파생 콘텐츠는 권한 인식 검색에서 제외된 상태로 유지됩니다.
  • indexedOneLakeParameters.ingestionParameters.embeddingModel: 선택적 콘텐츠 벡터화를 구성합니다.
  • indexedOneLakeParameters.ingestionParameters.chatCompletionModel: 이미지 언어화 또는 컨텍스트 추출을 위한 채팅 완성 모델을 구성합니다. 이 예제에서는 이미지 설명을 비활성화된 상태로 유지합니다.
  • indexedOneLakeParameters.ingestionParameters.ingestionSchedule: startTime 및 선택 사항인 interval로 소스 변경 폴링을 구성합니다. 적격한 실행 시간 중지 후 자동 계속은 이 폴링 간격과 별개입니다. 예약이나 연속 작업 모두 권한의 최신 상태를 보장하지 않습니다.

선택적 설정을 추가할 때 두 권한 옵션을 모두 유지합니다. 네트워크 액세스 모드는 기본적으로 public로 설정됩니다. 적격 전용 구성의 경우 개인 네트워크로 수집 제한을 참조하세요.

프라이빗 네트워크로 수집 제한

인덱싱된 OneLake 지식 원본에 대한 프라이빗 수집은 일반적으로 적격 전용 서비스의 REST API 2026-10-01에서 사용할 수 있습니다. 이 문서의 예제에서 OneLake 권한 보존에는 별도로 2026-11-01-preview가 필요합니다.

생성 요청에서 indexedOneLakeParameters.ingestionParameters.networkAccessMode를 private로 설정합니다.

  1. 프라이빗 네트워크 필수 구성 요소를 완료합니다.

  2. 지식 소스 생성 요청에서 private을(를) networkAccessMode(으)로 설정합니다. 안정적인 2026-10-01 API를 포함하여 만드는 동안에만 이 속성을 설정할 수 있습니다. 저장 모드를 나중에 변경하려면 지식 원본을 삭제하고 다시 만듭니다. 적격 Blob, ADLS Gen2 및 Azure SQL 원본은 대신 임시로 생성된 인덱서 네트워킹 재정의를 사용할 수 있습니다. 이 예외는 인덱싱된 SharePoint 또는 다른 원본 종류에는 적용되지 않습니다.

    서비스 계층 또는 런타임이 프라이빗 실행을 지원하지 않거나 필요한 공유 프라이빗 링크가 없는 경우 생성이 실패할 수 있습니다. 서버리스 및 S3 HD는 프라이빗 실행을 지원하지 않습니다. 네트워크 보안 경계 구성은 프라이빗 실행이 아니라 지원되는 퍼블릭 엔드포인트 액세스를 제어합니다.

  3. 생성된 인덱서가 parameters.configuration.executionEnvironment .인지 private확인합니다.

  4. 필요한 각 공유 프라이빗 링크가 승인되고 프로비전되었으며 올바른 종속성을 대상으로 하는지 확인합니다. 만들기에 성공해도 링크 승인 또는 대상 지정은 확인되지 않습니다. 포털 검사에서 구독 간 리소스를 확인할 수 없는 경우 대상 리소스 및 Foundry IQ 서비스에 대한 승인 및 준비 상태를 수동으로 확인합니다.

  5. lastSynchronizationState.endTime에 값이 있을 때까지 지식 소스 상태를 폴링합니다. itemsUpdatesFailed이(가) 0인지 확인한 다음, 커넥터별 원본 콘텐츠를 확인합니다. 종속성에 연결할 수 없는 경우 동기화가 실패합니다.

표준 추출 설정

앞의 예제에서 minimal 추출 대신 레이아웃 추출 및 의미 체계 청크에 Content Understanding을 사용하려면 standard을 contentExtractionMode로 설정하고 Foundry 리소스 엔드포인트로 aiServices을 구성합니다. 필수 구성 요소에 설명된 리소스 및 배포를 사용합니다.

표준 추출은 Content Understanding 요금을 발생시키고 이미지 구두화를 사용하도록 설정하면 모델 사용 요금이 부과됩니다. 자세한 내용은 청구 및 이미지 설명 컨트롤을 참조하세요.

언어별 자동 분석기 사용(미리 보기)

언어별 자동 분석기를 사용하도록 설정하려면 minimal를 indexedOneLakeParameters.ingestionParameters.contentExtractionMode로 설정합니다. indexedOneLakeParameters.ingestionParameters.aiServices.uri을 Microsoft Foundry 리소스 엔드포인트로 설정합니다. Foundry IQ는 각 원본 문서의 언어를 검색하고 일치하는 Microsoft 언어 분석기를 적용합니다. 기술 자료 정의 또는 쿼리에서 분석기를 지정하지 않습니다.

키 없는 인증의 경우 생략 indexedOneLakeParameters.ingestionParameters.aiServices.apiKey합니다. Microsoft Foundry 리소스의 Cognitive Services 사용자 역할을 Foundry IQ 서비스의 관리 ID에 할당합니다.

지원되는 언어는 영어, 일본어, 프랑스어, 스페인어, 독일어, 네덜란드어, 이탈리아어, 브라질 포르투갈어, 유럽 포르투갈어, 중국어 간체, 중국어 번체 및 한국어입니다.

다국어 콘텐츠의 경우 Foundry IQ는 주로 감지된 언어를 기반으로 분석기를 선택합니다. 언어가 지원되지 않거나 불확실한 경우 표준 분석기를 사용합니다.

이 옵션을 사용하면 데이터에 해당 언어가 포함되지 않더라도 생성된 인덱스에 지원되는 모든 언어에 대한 언어별 콘텐츠 필드가 포함됩니다. 수집 중에 Foundry IQ는 감지된 언어에 대한 필드로 문서를 라우팅합니다. 사용하지 않는 필드에는 인덱싱된 콘텐츠가 없고 스토리지에 미치는 영향이 최소화되지만 여전히 인덱스 필드 제한에 포함됩니다. 필드 수 및 스토리지 용량을 계획할 때 이러한 필드를 고려합니다.

언어 감지는 무료 AI 보강 할당 후에 요금이 부과됩니다.

수집 상태 확인

GET /knowledgesources/my-secured-onelake-ks/status?api-version=2026-11-01-preview를 인증 헤더와 함께 검색 엔드포인트로 보냅니다.

동기화 상태, 현재 및 이전 동기화 상태 및 문서 수준 오류를 검토합니다. 인덱서 상태 및 실행 기록을 사용하여 수집 실패를 조사합니다. 수집에 성공해도 원본 권한 변경 내용이 전파되지는 않습니다. 사용 권한 및 경로 최신 상태를 참조하세요.

생성된 개체 검토

생성된 데이터 원본, 기술 세트, 인덱서 및 인덱스는 지식 원본 이름에 따라 이름을 사용합니다. 이러한 이름은 변경할 수 없습니다. 변경 내용이 인덱서 파이프라인을 손상할 수 있으므로 개체를 직접 편집하지 마십시오.

생성된 개체 이름을 indexedOneLakeParameters.createdResources 사용하여 각 정의를 검색합니다. GET /<resource-collection>/<generated-object-name>?api-version=2026-11-01-preview를 인증 헤더와 함께 검색 엔드포인트로 보냅니다. 리소스 컬렉션은 indexers, datasources, skillsets 및 indexes입니다.

  1. 인증 헤더와 함께 GET /indexers/<generated-indexer-name>/status?api-version=2026-11-01-preview를 보내세요. executionHistory 및 lastResult에서 연결 또는 할당량 오류를 포함한 실행 상태 및 오류 메시지를 검사하고 확인합니다. Get Indexer Status를 참조하세요.
  2. 데이터 원본을 확인하여 레이크하우스 연결 및 관리형 ID 구성을 확인합니다.
  3. 기술 세트를 확인하여 콘텐츠가 청크되고 선택적으로 벡터화되는 방법을 확인합니다.
  4. 인덱스의 콘텐츠 및 사용 권한 필드를 확인합니다. 생성된 필드 매핑 및 청크 프로젝션이 원본 위치 메타데이터를 유지하는지 확인합니다.

기술 자료에 할당

기술 자료에 만족하는 경우 기술 자료에 추가합니다.

인덱싱된 OneLake 지식 원본을 지정하는 모든 기술 자료의 경우 true를 includeReferenceSourceData로 설정합니다. 이 설정은 원본 문서 URL을 인용에 끌어오는 데 필요합니다.

지식 베이스 질의

기술 자료를 구성한 후 검색 작업 또는 MCP 엔드포인트를 호출 하여 기술 자료를 쿼리합니다.

문서 수준 권한 적용(미리 보기)

2026-11-01-preview를 OneLake 권한 인식 요청에 사용합니다. x-ms-query-source-authorization에 설명된 대로 에 요청 중인 사용자의 액세스 토큰을 포함합니다. OneLake 쿼리 및 테스트 지침에 따라 허용된 사용자와 거부된 사용자를 확인합니다.

문서에 포함된 이미지 표시(미리 보기)

이미지 제공은 ingestionPermissionOptions이(가) 구성된 경우 지원되지 않으므로 이 문서의 보안 지식 원본에 assetStore을(를) 추가하지 마세요. 권한 수집이 없는 시나리오의 경우 에이전트 검색에서 문서에 포함된 이미지를 Surface(미리 보기)를 참조하세요.

지식 원본 삭제

지식 소스를 삭제하기 전에 이를 참조하는 지식 베이스를 삭제하거나 지식 베이스 정의를 업데이트하여 참조를 제거합니다. 원본이 계속 사용 중인 경우 삭제가 실패하고 영향을 받는 지식 베이스 목록을 반환합니다.

  1. 기술 자료 베이스를 나열하려면 GET /knowledgebases?api-version=2026-11-01-preview을(를) 보내세요. GET /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview를 사용하여 각 정의에서 지식 원본에 대한 참조를 검사합니다.
  2. 지식 베이스를 업데이트하여 참조를 제거합니다. 또는 해당 지식 베이스가 더 이상 필요하지 않은 경우 DELETE /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview를 보내세요.
  3. 지식 소스를 삭제하려면 DELETE /knowledgesources/my-secured-onelake-ks?api-version=2026-11-01-preview를 보내세요. 각 요청에 인증 헤더를 포함합니다.

인덱싱된 OneLake 지식 원본을 삭제하면 생성된 데이터 원본, 기술 세트, 인덱서 및 인덱스도 삭제됩니다. 이는 Microsoft Fabric의 원본 레이크하우스 또는 파일을 삭제하지 않습니다.