Azure AI 검색(이전 명칭: "Azure Cognitive Search")는 AI 기반 정보 검색 플랫폼으로, 개발자들이 대규모 언어 모델과 엔터프라이즈 데이터를 결합한 풍부한 검색 경험과 생성형 AI 앱을 구축할 수 있도록 돕습니다.
Azure AI 검색 서비스는 다음 애플리케이션 시나리오에 적합합니다.
- 다양한 콘텐츠 형식을 검색 가능한 단일 인덱스로 통합합니다. 인덱스를 채우려면 콘텐츠가 포함된 JSON 문서를 푸시하거나 데이터가 이미 Azure에 있는 경우 데이터를 자동으로 끌어올 인덱서를 만들 수 있습니다.
- 인덱서에 기술 세트를 연결하여 이미지 및 구조화되지 않은 문서에서 검색 가능한 콘텐츠를 만듭니다. 기술 세트는 기본 제공 OCR, 엔터티 인식, 핵심 구 추출, 언어 감지, 텍스트 번역 및 감정 분석을 위해 Azure AI Services의 API를 활용합니다. 사용자 지정 기술을 추가하여 데이터 수집 중에 콘텐츠의 외부 처리를 통합할 수도 있습니다.
- 검색 클라이언트 애플리케이션에서 상용 웹 검색 엔진 및 채팅 스타일 앱과 유사한 쿼리 논리 및 사용자 환경을 구현합니다.
클라이언트 라이브러리를 @azure/search-documents 사용하여 다음을 수행할 수 있습니다.
- 벡터, 키워드 및 하이브리드 쿼리 양식을 사용하여 쿼리를 제출합니다.
- 메타데이터, 지리 공간적 검색, 패싯 탐색 또는 필터 조건에 따라 결과의 범위를 좁히기 위해 필터링된 쿼리를 구현합니다.
- 검색 인덱스를 만들고 관리합니다.
- 검색 인덱스로 문서를 업로드하고 업데이트합니다.
- Azure에서 인덱스로 데이터를 끌어오는 인덱서를 만들고 관리합니다.
- 데이터 수집에 AI 보강을 추가하는 기술 세트를 만들고 관리합니다.
- 고급 텍스트 분석 또는 다국어 콘텐츠를 위한 분석기를 만들고 관리합니다.
- 의미 체계 순위 및 점수 매기기 프로필을 통해 결과를 최적화하여 비즈니스 논리 또는 새로 고침을 고려합니다.
키 링크:
시작
@azure/search-documents 패키지 설치
npm install @azure/search-documents
버전 13.1.0은 기본적으로 GA 서비스 API를 대상으로 2026-10-01 합니다. 버전 13.0.0에서 업그레이드할 때는 GA-to-GA 주요 변경 사항을 검토하세요.
업데이트된 TypeScript 및 JavaScript 예제는 samples/v13에서 제공됩니다.
현재 지원되는 환경
- LTS 버전의 Node.js
- Safari, Chrome, Microsoft Edge 및 Firefox의 최신 버전입니다.
자세한 내용은 지원 정책을 참조하세요.
필수 구성 요소
새 검색 서비스를 만들려면 Azure Portal, Azure PowerShell 또는 Azure CLI를 사용할 수 있습니다. 다음은 Azure CLI를 사용하여 시작하기 위한 무료 인스턴스를 만드는 예제입니다.
az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus
사용 가능한 옵션에 대한 자세한 내용은 가격 책정 계층 선택 을 참조하세요.
클라이언트 인증
검색 서비스와 상호작용하려면 적절한 클라이언트를 생성하세요: SearchClient 문서용, SearchIndexClient 색인 및 지식 자원, SearchIndexerClient 데이터 소스/색인기/기술 세트용, 또는 KnowledgeRetrievalClient 지식 기반 검색용. 클라이언트 개체를 인스턴스화하려면 엔드포인트 및 Azure 역할 또는 API 키가 필요합니다. 검색 서비스에서 지원되는 인증 방법에 대한 자세한 내용은 설명서를 참조할 수 있습니다.
API 키 가져오기
API 키는 기존 역할 할당이 필요하지 않으므로 시작하는 것이 더 쉬울 수 있습니다.
Azure Portal의 검색 서비스에서 엔드포인트 및 API 키를 가져올 수 있습니다. API 키를 가져오는 방법에 대한 지침은 설명서 를 참조하세요.
또는 다음 Azure CLI 명령을 사용하여 검색 서비스에서 API 키를 검색할 수 있습니다.
az search admin-key show --resource-group <your-resource-group-name> --service-name <your-resource-name>
검색 서비스에 액세스하는 데 사용되는 키에는 admin(읽기-쓰기) 및 query(읽기 전용) 키의 두 가지 유형이 있습니다. 클라이언트 앱에서 액세스 및 작업을 제한하는 것은 서비스의 검색 자산을 보호하는 데 필수적입니다. 항상 클라이언트 앱에서 시작된 모든 쿼리에 대해 관리 키가 아닌 쿼리 키를 사용합니다.
참고: 위의 예시 Azure CLI 스니펫은 관리자 키를 가져와 API 탐색을 쉽게 시작할 수 있도록 하지만, 관리는 신중해야 합니다.
api-key가 있으면 다음과 같이 사용할 수 있습니다.
import {
SearchClient,
AzureKeyCredential,
SearchIndexClient,
SearchIndexerClient,
KnowledgeRetrievalClient,
} from "@azure/search-documents";
// To query and manipulate documents
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));
// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"));
// To retrieve from a knowledge base
const knowledgeRetrievalClient = new KnowledgeRetrievalClient(
"<endpoint>",
"<knowledgeBaseName>",
new AzureKeyCredential("<apiKey>"),
);
국가별 클라우드에서 인증
National Cloud에서 인증하려면 클라이언트 구성에 다음과 같은 사항을 추가해야 합니다.
-
Audience에서SearchClientOptions
import { DefaultAzureCredential } from "@azure/identity";
import {
SearchClient,
KnownSearchAudience,
SearchIndexClient,
SearchIndexerClient,
KnowledgeRetrievalClient,
} from "@azure/search-documents";
const credential = new DefaultAzureCredential({
authorityHost: "https://login.chinacloudapi.cn",
});
// To query and manipulate documents
const searchClient = new SearchClient("<endpoint>", "<indexName>", credential, {
audience: KnownSearchAudience.AzureChina,
});
// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", credential, {
audience: KnownSearchAudience.AzureChina,
});
// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", credential, {
audience: KnownSearchAudience.AzureChina,
});
// To retrieve from a knowledge base
const knowledgeRetrievalClient = new KnowledgeRetrievalClient(
"<endpoint>",
"<knowledgeBaseName>",
credential,
{ audience: KnownSearchAudience.AzureChina },
);
주요 개념
Azure AI 검색 서비스에는 JSON 문서 형식으로 검색 가능한 데이터의 영구 스토리지를 제공하는 하나 이상의 인덱스가 포함되어 있습니다. (검색이 완전히 처음이라면, 인덱스와 데이터베이스 테이블을 대략적으로 비유할 수 있습니다.) 클라이언트 라이브러리는 @azure/search-documents 네 가지 주요 클라이언트 유형을 통해 이러한 리소스에 대한 작업을 노출합니다.
SearchClient도움 사항:SearchIndexClient을 사용하면 다음을 수행할 수 있습니다.- 검색 인덱스를 생성, 삭제, 업데이트 또는 구성하세요
- 쿼리를 확장하거나 다시 작성하기 위한 사용자 지정 동의어 맵 선언
- 지식 베이스, 지식 소스, 파일 지식 소스에 업로드된 파일을 관리하세요
SearchIndexerClient을 사용하면 다음을 수행할 수 있습니다.KnowledgeRetrievalClient을 사용하면 다음을 수행할 수 있습니다.- 지식 베이스에서 검색하여 그 활동과 참조를 점검하세요
- 스트림 유형화된 검색 진행 상황과 터미널 결과를 서버 전송 이벤트로 표현했습니다
참고: 브라우저 사용은 선택한 검색 작업 및 리소스에 CORS가 구성되어 있는지에 따라 달라집니다. 파일 지식 소스와 지식 베이스는 CORS 설정을 노출하지만, 많은 관리 작업은 신뢰할 수 있는 서버 측 애플리케이션을 위한 것입니다.
TypeScript/JavaScript 관련 개념
문서
검색 인덱스 내에 저장된 항목입니다. 이 문서의 모양은 속성을 사용하여 인덱스에 설명되어 있습니다.fields 각각 SearchField 에는 이름, 데이터 유형 및 추가 메타데이터(예: 검색 가능 또는 필터링 가능한지)가 있습니다.
페이지 매김
일반적으로 한 번에 사용자에게 검색 결과의 하위 집합만 표시 하려고 합니다. 이를 지원하기 위해 , top 및 skip 매개 includeTotalCount변수를 사용하여 검색 결과 위에 페이징된 환경을 제공할 수 있습니다.
문서 필드 인코딩
인덱스에서 지원되는 데이터 유형은 API 요청/응답에서 JSON 유형에 매핑됩니다. JS 클라이언트 라이브러리는 다음과 같은 몇 가지 예외를 제외하고 대부분 동일하게 유지됩니다.
-
Edm.DateTimeOffsetJSDate로 변환됩니다. -
Edm.GeographyPoint클라이언트 라이브러리에서 내보낸 유형으로GeographyPoint변환됩니다. - 유형(NaN, Infinity, -Infinity)의
number특수 값은 REST API에서 문자열로 직렬화되지만 클라이언트 라이브러리에 의해 다시number변환됩니다.
참고: 데이터 유형은 인덱스 스키마의 필드 유형이 아닌 값을 기준으로 변환됩니다. 즉, 필드 값으로 ISO8601 Date 문자열(예: "2020-03-06T18:48:27.896Z")이 있는 경우 스키마에 저장한 방법에 관계없이 날짜로 변환됩니다.
예제
다음 예제는 기본 사항을 보여줍니다 - 자세한 내용은 샘플을 확인하십시오 .
- 색인 생성
- 색인에서 특정 문서 가져오기
- 문서 색인에 추가
- 문서 검색 수행
- 지식 베이스에서 가져오기
- 유사한 문서 찾기
- 지식 기반 구성
- 페이지 컨트롤이 포함된 리소스 목록
- SharePoint 문서 권한 구성
- SharePoint 사이트 콘텐츠 인덱싱
- 변경되지 않은 ADLS Gen2 권한 새로 고침
- 스트림 지식 검색
- 파일 지식 소스 용량 확인
- 지식 소스 파일 업로드 및 업데이트
아래 예시들은 클라이언트의 기본값인 안정적인 2026-10-01 서비스 API를 사용합니다.
이들은 별도의 클라이언트 세트를 필요로 하지 않고, 기존 인덱스, 인덱서, 지식 소스 및 검색 워크플로우를 확장합니다.
완전한 실행 가능한 워크플로우를 위해 샘플 소스 는 인덱스 SQL 콘텐츠 컬럼, 개인 수집 및 서비스 선택 분석기, 이미지 설명 모델 및 의미 청킹 콘텐츠 이해, 서비스/인덱서 런타임 예산, 검색 소유 인용 URL도 포함합니다. 선택적 리소스 설정과 사전 요구 사항은 sample.env에 나열되어 있습니다.
유사 문서 찾기
기존 문서 키와 함께 사용 moreLikeThis 하고 검색 텍스트는 생략하세요. 최상위 검색 가능한 텍스트 필드를 명시적으로 선택하세요: 복잡한 필드는 이 작업에서 지원되지 않습니다. 색인에는 유용한 일치를 반환하기 위해 다른 문서도 포함되어야 합니다.
import { SearchClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";
const client = new SearchClient("<endpoint>", "<indexName>", new DefaultAzureCredential());
const response = await client.search(undefined, {
moreLikeThis: "1",
searchFields: ["hotelName", "description"],
select: ["hotelId", "hotelName"],
top: 5,
});
for await (const result of response.results) {
console.log(result.document);
}
지식 기반 구성
의미 검색이 설정된 채워진 지식 소스를 사용하세요. 구성된 채팅 모델을 배포하고 검색 서비스의 관리 신원에 Azure OpenAI 리소스의 인지 서비스 OpenAI 사용자를 부여합니다. 배포 이름과 모델 이름은 별도의 설정입니다; 배포는 사용자 지정 이름을 가질 수 있습니다. 발신자는 지식 기반을 관리하기 위해 Search Service Contributer가 필요합니다.
저장된 명령어, 출력 모드, 추론 노력은 지식 출처를 교체하지 않고도 갱신할 수 있습니다.
answerSynthesis 구성된 모델을 사용합니다; extractiveData 답변을 합성하지 않고 추출한 내용을 반환합니다. GA 추론 모드는 , , low그리고 medium입니다minimal.
명시적 요청 의도는 모델 쿼리 계획을 우회합니다.
import { SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";
const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());
const knowledgeBase = await client.createKnowledgeBase({
name: "hotel-knowledge-base",
knowledgeSources: [{ name: "<existingKnowledgeSourceName>" }],
models: [
{
kind: "azureOpenAI",
azureOpenAIParameters: {
resourceUrl: "<azureOpenAIEndpoint>",
deploymentId: "<chatDeploymentName>",
modelName: "gpt-5.4-mini",
},
},
],
retrievalReasoningEffort: { kind: "low" },
outputMode: "answerSynthesis",
retrievalInstructions: "Prioritize hotel amenities and pricing information.",
answerInstructions: "Answer concisely and cite the supporting sources.",
});
knowledgeBase.outputMode = "extractiveData";
await client.createOrUpdateKnowledgeBase(knowledgeBase);
페이지 컨트롤이 포함된 리소스 목록
초기 목록을 이름 접두사별로 필터링하고 SDK가 불투명한 이어서 링크를 따라가도록 하세요. 호출기는 SearchIndexClient .를 노출시킵니다 byPage(). 기존의 동의어 맵, 인덱서, 데이터 소스, 그리고 스킬셋 편의 목록 메서드는 모든 페이지를 수집한 후에도 배열을 계속 반환합니다; 프로토콜 클라이언트는 해당 페이지 연산을 노출합니다.
import { SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";
const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());
for await (const page of client
.listIndexes({
search: "hotel",
searchType: "prefix",
pageSize: 10,
})
.byPage()) {
console.log(page.map((index) => index.name));
}
SharePoint 문서 권한 구성
인덱스를 만들기 전에 SharePoint 커넥터 응용 프로그램과 그 페더레이션 자격 증명을 등록하세요.
applicationId
federatedCredentialId 그리고 함께 필요하며, tenantId 검색 서비스 테넌트와 다를 때 제공할 수 있습니다. 발신자는 Search Service Contributor를 필요로 합니다.
조직 범위가 지정된 공유 권한은 권한 필드에서 userIds 사용됩니다orgLink:<tenantId>.
organizationAccessExpiration 만료 타임스탬프를 식별합니다. 최대 한 개의 최상위 필드 Edm.DateTimeOffset 만이 이를 가능하게 할 수 있습니다. 서비스는 권한 필터링 쿼리 중에 사용자의 테넌트와 타임스탬프를 검증합니다; 이 필드들만으로는 접근 권한이 부여되지 않습니다.
import { SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";
const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());
await client.createIndex({
name: "sharepoint-permissions",
permissionFilterOption: "enabled",
sharePointConnectorAppRegistration: {
applicationId: "<applicationId>",
federatedCredentialId: "<federatedCredentialId>",
},
fields: [
{ name: "id", type: "Edm.String", key: true },
{ name: "content", type: "Edm.String", searchable: true },
{
name: "userIds",
type: "Collection(Edm.String)",
filterable: true,
permissionFilter: "userIds",
},
{
name: "organizationLinkExpiresAt",
type: "Edm.DateTimeOffset",
organizationAccessExpiration: true,
},
],
});
SharePoint 사이트 콘텐츠 인덱싱
GA SharePoint 범위AllSiteLists에는 기존 라이브러리 범위 외에도 , AllSitePages가 AllSiteContent포함됩니다. 애플리케이션 비밀을 소스 코드에 삽입하기보다는 환경을 통해 커넥터 연결 문자열을 제공하세요.
import { SearchIndexClient, KnownIndexedSharePointContainerName } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";
const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());
const connectionString = process.env.SHAREPOINT_CONNECTION_STRING;
if (!connectionString) {
throw new Error("Set SHAREPOINT_CONNECTION_STRING before creating the knowledge source.");
}
await client.createKnowledgeSource({
name: "sharepoint-site",
kind: "indexedSharePoint",
indexedSharePointParameters: {
connectionString,
containerName: KnownIndexedSharePointContainerName.AllSiteContent,
},
});
변경되지 않은 ADLS Gen2 사용 권한 새로 고침
권한을 수집하는 기존 ADLS Gen2 인덱서의 경우, refreshAllAcls 문서 내용이 변경되지 않아도 권한 메타데이터를 새로고침합니다. 기본값은 true24시간에 한 번씩 실행되며, 콘텐츠나 보강은 재처리하지 않습니다. 새로 고침을 비활성화하려면 이 false 값을 설정하세요.
import { SearchIndexerClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";
const client = new SearchIndexerClient("<endpoint>", new DefaultAzureCredential());
const indexer = await client.getIndexer("<existingAdlsGen2Indexer>");
indexer.parameters = {
...indexer.parameters,
configuration: {
...indexer.parameters?.configuration,
refreshAllAcls: true,
},
};
await client.createOrUpdateIndexer(indexer);
지식 기반에서 검색
import {
KnowledgeRetrievalClient,
AzureKeyCredential,
KnownKnowledgeRetrievalReasoningEffortKind,
} from "@azure/search-documents";
const client = new KnowledgeRetrievalClient(
"<endpoint>",
"<knowledgeBaseName>",
new AzureKeyCredential("<apiKey>"),
);
const response = await client.retrieve({
intents: [{ type: "semantic", search: "What information is available?" }],
retrievalReasoningEffort: { kind: KnownKnowledgeRetrievalReasoningEffortKind.Low },
includeActivity: true,
});
console.log(response.response);
지식 검색 스트림
타입 반복자는 하나의 SSE 연결을 사용하며, 프레이밍과 하트비트를 처리하고 또는 error이후에 response.completed 멈춥니다. 완료 결과는 전부(200)나 부분(206)을 보고할 수 있습니다.
요청을 취소하려면 전화하세요 controller.abort() . 알 수 없는 이벤트 이름은 무시됩니다; 토큰-델타 이벤트는 이 API에 포함되지 않습니다. 활동 상관관계 및 취소 처리는 스트리밍 샘플을 참조하세요.
import { KnowledgeRetrievalClient, AzureKeyCredential } from "@azure/search-documents";
const client = new KnowledgeRetrievalClient(
"<endpoint>",
"<knowledgeBaseName>",
new AzureKeyCredential("<apiKey>"),
);
const controller = new AbortController();
for await (const event of await client.retrieveStream(
{
intents: [{ type: "semantic", search: "Summarize the indexed information." }],
includeActivity: true,
},
{ abortSignal: controller.signal },
)) {
if (event.event === "activity.completed") {
console.log(`Activity ${event.data.id} took ${event.data.elapsedInMs}ms`);
} else if (event.event === "response.completed") {
console.log(event.data.statusCode === 206 ? "Partial results" : "Complete results");
console.log(event.data.response.response);
} else if (event.event === "error") {
throw new Error(event.data.error.message);
}
}
지식 소스 파일 업로드 및 업데이트
import { SearchIndexClient, AzureKeyCredential } from "@azure/search-documents";
const client = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));
const body = {
metadata: { fileName: "manuals/example.txt", metadata: { category: "manual" } },
content: {
contents: new TextEncoder().encode("Azure AI Search retrieves relevant information."),
contentType: "text/plain",
filename: "example.txt",
},
};
const uploaded = await client.uploadKnowledgeSourceFileMultipart("<knowledgeSourceName>", body);
if (!uploaded.fileId) {
throw new Error("The service did not return an uploaded file ID.");
}
await client.updateKnowledgeSourceFile("<knowledgeSourceName>", uploaded.fileId, {
...body,
metadata: { ...body.metadata, metadata: { category: "updated-manual" } },
});
for await (const file of client.listKnowledgeSourceFiles("<knowledgeSourceName>", {
prefix: "manuals/",
pageSize: 10,
})) {
console.log(file.fileName, file.parsingMode, file.extractionMode);
}
파일 지식 소스 용량 확인
파일 지식 소스의 상태는 ()와 함께 남은 파일 개수와 파일당 바이트 제한을 노출시킵니다fileCapacityKnowledgeSourceFileCapacity. 업로드 전에 확인해 보세요; 다른 지식 출처 유형은 이 필드를 보고하지 않습니다. 직접 업로드에는 Search Service Contributor가 필요하며, 검색 서비스의 관리 아이덴티티에는 임베딩 리소스에 Cognitive Services OpenAI User 가 필요합니다.
import { SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";
const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());
const status = await client.getKnowledgeSourceStatus("<fileKnowledgeSourceName>");
if (!status.fileCapacity) {
throw new Error("The knowledge source did not report File upload capacity.");
}
console.log(`Remaining files: ${status.fileCapacity.remainingFileCount}`);
console.log(`Maximum file size: ${status.fileCapacity.maxFileSizeBytes} bytes`);
인덱스 만들기
import { SearchIndexClient, AzureKeyCredential } from "@azure/search-documents";
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));
const result = await indexClient.createIndex({
name: "example-index",
fields: [
{
type: "Edm.String",
name: "id",
key: true,
},
{
type: "Edm.Double",
name: "awesomenessLevel",
sortable: true,
filterable: true,
facetable: true,
},
{
type: "Edm.String",
name: "description",
searchable: true,
},
{
type: "Edm.ComplexType",
name: "details",
fields: [
{
type: "Collection(Edm.String)",
name: "tags",
searchable: true,
},
],
},
{
type: "Edm.Int32",
name: "hiddenWeight",
hidden: true,
},
],
});
console.log(`Index created with name ${result.name}`);
인덱스에서 특정 문서 검색
특정 문서는 기본 키 값으로 검색할 수 있습니다.
import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
const result = await searchClient.getDocument("1234");
인덱스로 문서 추가
일괄 처리 내의 인덱스로 여러 문서를 업로드할 수 있습니다.
import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
const uploadResult = await searchClient.uploadDocuments([
// JSON objects matching the shape of the client's index
{},
{},
{},
]);
for (const result of uploadResult.results) {
console.log(`Uploaded ${result.key}; succeeded? ${result.succeeded}`);
}
문서에 대한 검색 수행
특정 쿼리의 모든 결과를 나열하려면 search을 사용하는 검색 문자열과 함께 사용할 수 있습니다.
import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
const searchResults = await searchClient.search("wifi -luxury");
for await (const result of searchResults.results) {
console.log(result);
}
Lucene 구문을 사용하는 고급 검색의 경우 다음과 같이 queryType지정합니다full.
import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
const searchResults = await searchClient.search('Category:budget AND "recently renovated"^3', {
queryType: "full",
searchMode: "all",
});
for await (const result of searchResults.results) {
console.log(result);
}
TypeScript를 사용하여 쿼리
TypeScript에서 는 SearchClient 인덱스 문서의 모델 모양인 일반 매개 변수를 사용합니다. 이렇게 하면 결과에 반환된 필드의 강력한 형식 조회를 수행할 수 있습니다. TypeScript는 매개변수를 지정할 때 반환되는 필드도 확인할 수 있습니다 select .
import { SearchClient, AzureKeyCredential, SelectFields } from "@azure/search-documents";
// An example schema for documents in the index
interface Hotel {
hotelId?: string;
hotelName?: string | null;
description?: string | null;
descriptionVector?: Array<number>;
parkingIncluded?: boolean | null;
lastRenovationDate?: Date | null;
rating?: number | null;
rooms?: Array<{
beds?: number | null;
description?: string | null;
}>;
}
const searchClient = new SearchClient<Hotel>(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
const searchResults = await searchClient.search("wifi -luxury", {
// Only fields in Hotel can be added to this array.
// TS will complain if one is misspelled.
select: ["hotelId", "hotelName", "rooms/beds"],
});
// These are other ways to declare the correct type for `select`.
const select = ["hotelId", "hotelName", "rooms/beds"] as const;
// This declaration lets you opt out of narrowing the TypeScript type of your documents,
// though the AI Search service will still only return these fields.
const selectWide: SelectFields<Hotel>[] = ["hotelId", "hotelName", "rooms/beds"];
// This is an invalid declaration. Passing this to `select` will result in a compiler error
// unless you opt out of including the model in the client constructor.
const selectInvalid = ["hotelId", "hotelName", "rooms/beds"];
for await (const result of searchResults.results) {
// result.document has hotelId, hotelName, and rooms with only the beds property.
// Trying to access result.document.description would emit a TS error.
console.log(result.document.hotelName);
}
OData 필터를 사용하여 쿼리
query 매개 변수를 filter 사용하면 OData $filter 식의 구문을 사용하여 인덱스를 쿼리할 수 있습니다.
import { SearchClient, AzureKeyCredential, odata } from "@azure/search-documents";
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
const baseRateMax = 200;
const ratingMin = 4;
const searchResults = await searchClient.search("WiFi", {
filter: odata`Rooms/any(room: room/BaseRate lt ${baseRateMax}) and Rating ge ${ratingMin}`,
orderBy: ["Rating desc"],
select: ["hotelId", "hotelName", "Rating"],
});
for await (const result of searchResults.results) {
// Each result will have "HotelId", "HotelName", and "Rating"
// in addition to the standard search result property "score"
console.log(result);
}
벡터를 사용하여 쿼리
텍스트 임베딩은 search 매개 변수를 vector 사용하여 쿼리할 수 있습니다. 자세한 내용은 쿼리 벡터 및 벡터 쿼리 필터링을 참조하세요.
import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
const queryVector: number[] = [
// Embedding of the query "What are the most luxurious hotels?"
];
const searchResults = await searchClient.search("*", {
vectorSearchOptions: {
queries: [
{
kind: "vector",
vector: queryVector,
fields: ["descriptionVector"],
kNearestNeighborsCount: 3,
},
],
},
});
for await (const result of searchResults.results) {
// These results are the nearest neighbors to the query vector
console.log(result);
}
패싯을 사용하여 쿼리
파셋 은 애플리케이션 사용자가 미리 구성된 차원을 따라 검색을 세밀하게 조정할 수 있도록 돕는 데 사용됩니다. Facet 구문은 정렬 및 패싯 값을 버킷별로 분류하는 옵션을 제공합니다.
import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
);
const searchResults = await searchClient.search("WiFi", {
facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
});
console.log(searchResults.facets);
결과를 facets 검색할 때 각 패싯 버킷에 속하는 결과 수를 나타내는 속성을 사용할 수 있습니다. 이는 세분화를 추진하는 데 사용할 수 있습니다(예: 3 이상 4 미만인 것을 Rating 필터링하는 후속 검색 실행).
문제 해결
로깅
로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다. 또는 setLogLevel@azure/logger 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
로그를 사용하도록 설정하는 방법에 대한 자세한 지침은 @azure/로거 패키지 문서를 참조하세요.
다음 단계
기여
이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.
이 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여는 귀하가 귀하의 기여를 사용할 권리를 부여할 권리가 있음을 선언하는 CLA(기여자 사용권 계약)에 동의해야 합니다. 자세한 내용은 cla.microsoft.com 를 참조하십시오.
이 프로젝트는 Microsoft 오픈 소스 준수 사항을 채택했습니다. 자세한 내용은 행동 강령 FAQ 참조하거나 추가 질문이나 의견을 [email protected] 문의하세요.
관련 프로젝트
Azure SDK for JavaScript