JavaScript용 Azure AI Search 클라이언트 라이브러리 - 버전 12.0.0
Azure AI Search(이전의 "Azure Cognitive Search")는 개발자가 대규모 언어 모델을 엔터프라이즈 데이터와 결합하는 풍부한 검색 환경 및 생성 AI 앱을 빌드하는 데 도움이 되는 AI 기반 정보 검색 플랫폼입니다.
Azure AI Search는 다음 애플리케이션 시나리오에 적합합니다.
- 다양한 콘텐츠 형식을 검색 가능한 단일 인덱스로 통합합니다. 인덱스 채우기를 위해 콘텐츠가 포함된 JSON 문서를 푸시하거나 데이터가 이미 Azure에 있는 경우 데이터를 자동으로 끌어올 인덱서를 만들 수 있습니다.
- 인덱서에 기술 세트를 연결하여 이미지 및 큰 텍스트 문서에서 검색 가능한 콘텐츠를 만듭니다. 기술 세트는 기본 제공 OCR, 엔터티 인식, 핵심 구 추출, 언어 감지, 텍스트 번역 및 감정 분석을 위해 AI 서비스의 API를 활용합니다. 사용자 지정 기술을 추가하여 데이터 수집 중에 콘텐츠의 외부 처리를 통합할 수도 있습니다.
- 검색 클라이언트 애플리케이션에서 상용 웹 검색 엔진과 유사한 쿼리 논리 및 사용자 환경을 구현합니다.
클라이언트 라이브러리를 @azure/search-documents 사용하여 다음을 수행합니다.
- 벡터, 키워드(keyword) 및 하이브리드 쿼리 양식을 사용하여 쿼리를 제출합니다.
- 메타데이터, 지리 공간적 검색, 패싯 탐색 또는 필터 조건에 따라 결과의 범위를 좁히기 위해 필터링된 쿼리를 구현합니다.
- 검색 인덱스를 만들고 관리합니다.
- 검색 인덱스에서 문서를 업로드하고 업데이트합니다.
- Azure에서 인덱스로 데이터를 끌어오는 인덱서를 만들고 관리합니다.
- 데이터 수집에 AI 보강을 추가하는 기술 세트를 만들고 관리합니다.
- 고급 텍스트 분석 또는 다국어 콘텐츠를 위한 분석기를 만들고 관리합니다.
- 점수 매기기 프로필을 통해 결과를 최적화하여 비즈니스 논리 또는 새로 고침을 고려합니다.
주요 링크:
시작
@azure/search-documents
패키지를 설치합니다.
npm install @azure/search-documents
현재 지원되는 환경
- Node.js의 LTS 버전
- 최신 버전의 Safari, Chrome, Edge, Firefox.
자세한 내용은 지원 정책을 참조하세요.
필수 구성 요소
새 검색 서비스를 만들려면 Azure Portal, Azure PowerShell 또는 Azure CLI를 사용할 수 있습니다. 다음은 Azure CLI를 사용하여 시작하기 위한 무료 instance 만드는 예제입니다.
az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus
사용 가능한 옵션에 대한 자세한 내용은 가격 책정 계층 선택을 참조하세요.
클라이언트 인증
검색 서비스와 상호 작용하려면 적절한 클라이언트 클래스 SearchClient
의 instance 만들어야 합니다. 인덱싱된 문서 검색, SearchIndexClient
인덱스 관리 또는 SearchIndexerClient
데이터 원본 크롤링 및 인덱스에 검색 문서 로드용입니다.
클라이언트 개체를 인스턴스화하려면 엔드포인트 및 Azure 역할 또는 API 키가 필요합니다. 검색 서비스에서 지원되는 인증 방법에 대한 자세한 내용은 설명서를 참조하세요.
API 키 가져오기
API 키는 기존 역할 할당이 필요하지 않으므로 더 쉽게 시작할 수 있습니다.
Azure Portal의 검색 서비스에서 엔드포인트 및 API 키를 가져올 수 있습니다. API 키를 가져오는 방법에 대한 지침은 설명서를 참조하세요.
또는 다음 Azure CLI 명령을 사용하여 검색 서비스에서 API 키를 검색할 수 있습니다.
az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>
api-key가 있으면 다음과 같이 사용할 수 있습니다.
const {
SearchClient,
SearchIndexClient,
SearchIndexerClient,
AzureKeyCredential,
} = require("@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>"));
국가별 클라우드에서 인증
National Cloud에서 인증하려면 클라이언트 구성에 다음을 추가해야 합니다.
- 에서 설정
Audience
SearchClientOptions
const {
SearchClient,
SearchIndexClient,
SearchIndexerClient,
AzureKeyCredential,
KnownSearchAudience,
} = require("@azure/search-documents");
// To query and manipulate documents
const searchClient = new SearchClient(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>"),
{
audience: KnownSearchAudience.AzureChina,
}
);
// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
audience: KnownSearchAudience.AzureChina,
});
// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
audience: KnownSearchAudience.AzureChina,
});
주요 개념
Azure AI Search Service JSON 문서 형식으로 검색 가능한 데이터의 영구 스토리지를 제공하는 하나 이상의 인덱스를 포함합니다. 검색을 처음 접하는 경우 인덱스와 데이터베이스 테이블 간에 매우 대략적인 비유를 만들 수 있습니다. 클라이언트 라이브러리는 @azure/search-documents 세 가지 기본 클라이언트 유형을 통해 이러한 리소스에 대한 작업을 노출합니다.
SearchClient
다음을 수행할 수 있습니다.- 벡터 쿼리, 키워드(keyword) 쿼리 및 하이브리드 쿼리를 사용하여 인덱싱된 문서 검색
- 벡터 쿼리 필터 및텍스트 쿼리 필터
- 관련성을 높이기 위한 의미 체계 순위 및 점수 매기기 프로필
- 인덱스의 문서에 따라 부분적으로 입력된 검색어 자동 완성
- 문서에서 가장 일치하는 텍스트를 사용자 유형으로 제안
- 인덱스에서 문서 문서 추가, 업데이트 또는 삭제
SearchIndexClient
를 사용하면 다음을 수행할 수 있습니다.SearchIndexerClient
를 사용하면 다음을 수행할 수 있습니다.
참고: 호출하는 API는 CORS(원본 간 리소스 공유)를 지원하지 않으므로 이러한 클라이언트는 브라우저에서 작동할 수 없습니다.
TypeScript/JavaScript 관련 개념
문서
검색 인덱스 내에 저장된 항목입니다. 이 문서의 모양은 를 사용하여 Field
인덱스에서 설명합니다. 각 필드에는 이름, 데이터 형식 및 검색 가능하거나 필터링 가능한 경우와 같은 추가 메타데이터가 있습니다.
페이지 매김
일반적으로 한 번에 사용자에게 검색 결과의 하위 집합만 표시 하려고 합니다. 이를 지원하기 위해 , skip
및 includeTotalCount
매개 변수를 top
사용하여 검색 결과 위에 페이징된 환경을 제공할 수 있습니다.
문서 필드 인코딩
인덱스에서 지원되는 데이터 형식은 API 요청/응답의 JSON 형식에 매핑됩니다. JS 클라이언트 라이브러리는 다음과 같은 몇 가지 예외를 제외하고 대부분 동일하게 유지합니다.
Edm.DateTimeOffset
는 JS 로 변환됩니다Date
.Edm.GeographyPoint
는 클라이언트 라이브러리에서GeographyPoint
내보낸 형식으로 변환됩니다.- 형식의
number
특수 값(NaN, Infinity, -Infinity)은 REST API에서 문자열로 직렬화되지만 클라이언트 라이브러리에서 로 다시number
변환됩니다.
참고: 데이터 형식은 인덱스 스키마의 필드 형식이 아니라 값을 기준으로 변환됩니다. 즉, 필드 값으로 ISO8601 Date 문자열(예: "2020-03-06T18:48:27.896Z")이 있는 경우 스키마에 저장한 방법에 관계없이 날짜로 변환됩니다.
예제
다음 예제에서는 기본 사항을 보여 줍니다. 샘플을 훨씬 더 검사.
인덱스 만들기
const { SearchIndexClient, AzureKeyCredential } = require("@azure/search-documents");
const client = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));
async function main() {
const result = await client.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(result);
}
main();
인덱스에서 특정 문서 검색
특정 문서는 기본 키 값으로 검색할 수 있습니다.
const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
async function main() {
const result = await client.getDocument("1234");
console.log(result);
}
main();
인덱스로 문서 추가
여러 문서를 일괄 처리 내의 인덱스로 업로드할 수 있습니다.
const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
async function main() {
const uploadResult = await client.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}`);
}
}
main();
문서에 대한 검색 수행
특정 쿼리의 모든 결과를 나열하려면 간단한 쿼리 구문을 사용하는 검색 문자열과 함께 를 사용할 search
수 있습니다.
const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
async function main() {
const searchResults = await client.search("wifi -luxury");
for await (const result of searchResults.results) {
console.log(result);
}
}
main();
Lucene 구문을 사용하는 고급 검색의 경우 을 로 지정 queryType
합니다full
.
const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
async function main() {
const searchResults = await client.search('Category:budget AND "recently renovated"^3', {
queryType: "full",
searchMode: "all",
});
for await (const result of searchResults.results) {
console.log(result);
}
}
main();
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> | null;
parkingIncluded?: boolean | null;
lastRenovationDate?: Date | null;
rating?: number | null;
rooms?: Array<{
beds?: number | null;
description?: string | null;
} | null>;
}
const client = new SearchClient<Hotel>(
"<endpoint>",
"<indexName>",
new AzureKeyCredential("<apiKey>")
);
async function main() {
const searchResults = await client.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 rating.
// Trying to access result.document.description would emit a TS error.
console.log(result.document.hotelName);
}
}
main();
OData 필터를 사용하여 쿼리
쿼리 매개 변수를 filter
사용하면 OData $filter 식의 구문을 사용하여 인덱스를 쿼리할 수 있습니다.
const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");
const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
async function main() {
const baseRateMax = 200;
const ratingMin = 4;
const searchResults = await client.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);
}
}
main();
벡터를 사용하여 쿼리
검색 매개 변수를 사용하여 텍스트 포함을 vector
쿼리할 수 있습니다.
const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");
const searchClient = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
async function main() {
const queryVector = [...]
const searchResults = await searchClient.search("*", {
vector: {
fields: ["descriptionVector"],
kNearestNeighborsCount: 3,
value: queryVector,
},
});
for await (const result of searchResults.results) {
// These results are the nearest neighbors to the query vector
console.log(result);
}
}
main();
패싯을 사용하여 쿼리
패싯 은 애플리케이션 사용자가 미리 구성된 차원을 따라 검색을 구체화하는 데 사용됩니다. 패싯 구문 은 패싯 값을 정렬하고 버킷하는 옵션을 제공합니다.
const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
async function main() {
const searchResults = await client.search("WiFi", {
facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
});
console.log(searchResults.facets);
// Output will look like:
// {
// 'rooms/baseRate': [
// { count: 16, value: 0 },
// { count: 17, value: 100 },
// { count: 17, value: 200 }
// ],
// category: [
// { count: 5, value: 'Budget' },
// { count: 5, value: 'Luxury' },
// { count: 5, value: 'Resort and Spa' }
// ]
// }
}
main();
결과를 facets
검색할 때 각 패싯 버킷에 속하는 결과 수를 나타내는 속성을 사용할 수 있습니다. 구체화를 구동하는 데 사용할 수 있습니다(예: 3보다 크거나 같거나 4보다 작은 것을 필터링 Rating
하는 후속 검색 실행).
문제 해결
로깅
로깅을 사용하도록 설정하면 실패에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL
환경 변수를 info
로 설정합니다. 또는 @azure/logger
에서 setLogLevel
을 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
로그를 사용하는 방법에 대한 자세한 내용은 @azure/logger package docs를 참조하세요.
다음 단계
참여
이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.
이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 cla.microsoft.com.
이 프로젝트는 Microsoft 오픈 소스 행동 강령을 채택했습니다. 자세한 내용은 행동 강령 FAQ 를 참조하거나 추가 질문 또는 의견을 문의 opencode@microsoft.com 하세요.
관련된 프로젝트
Azure SDK for JavaScript
피드백
https://aka.ms/ContentUserFeedback
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요.다음에 대한 사용자 의견 제출 및 보기