azure search openai javascript
1.0.0
이 샘플은 검색 증강 생성 패턴을 사용하여 자신의 데이터를 통해 ChatGpt와 같은 경험을 만드는 몇 가지 접근법을 보여줍니다. Azure Openai 서비스를 사용하여 ChatGpt 모델 (GPT-35-Turbo)에 액세스하고 Azure AI 검색 데이터 인덱싱 및 검색을 검색합니다.
리포에는 샘플 데이터가 포함되어있어 끝까지 시도 할 준비가되었습니다. 이 샘플 응용 프로그램에서 우리는 Contoso Real Estate라는 가상의 회사를 사용하며,이 경험을 통해 고객은 제품 사용에 대한 지원 질문을 할 수 있습니다. 샘플 데이터에는 서비스 약관, 개인 정보 보호 정책 및 지원 안내서를 설명하는 문서 세트가 포함되어 있습니다.
응용 프로그램은 다음을 포함하여 여러 구성 요소로 만들어집니다.
앱의 비디오 개요를 시청하십시오
중요 : 이 샘플을 배포하고 실행하려면 다음을 수행해야합니다.
Microsoft.Authorization/roleAssignments/write 권한이 있어야 역할 기반 액세스 제어 관리자, 사용자 액세스 관리자 또는 소유자가 있어야합니다. 구독 수준의 권한이없는 경우 기존 리소스 그룹을 위해 RBAC를 사용하여 기존 그룹에 배포해야합니다.Microsoft.Resources/deployments/write 권한이 필요합니다. 가격은 지역 및 사용량당 다를 수 있습니다. 정확한 비용은 추정 할 수 없습니다. 아래의 리소스에 대해 Azure 가격 책정 계산기를 사용해 볼 수 있습니다.
azd down --purge 실행하여 더 이상 사용하지 않는 경우 앱을 중단하십시오.
이 프로젝트를 성공적으로 설정하는 방법에는 여러 가지가 있습니다.
시작하는 가장 쉬운 방법은 GitHub 코드 스페이스를 사용하여 전제 조건을 제공하여 모든 도구를 설정합니다. 아래에서 자세히 알아보십시오. 또는 아래 지시 사항을 충전하는 지역 환경을 설정할 수 있습니다.
GitHub Codespaces를 사용 하여이 리포트를 거의 실행할 수 있습니다. GitHub Codespaces는 브라우저에서 웹 기반 대 코드를 열게됩니다.
Codespace와 유사한 옵션은 VS Code 원격 컨테이너이며, Dev 컨테이너 확장을 사용하여 로컬 대 코드 인스턴스에서 프로젝트를 열게됩니다.
pwsh.exe 실행할 수 있는지 확인하십시오. 이것이 실패하면 PowerShell을 업그레이드해야 할 것입니다.그런 다음 프로젝트 코드를 가져옵니다.
azd auth login 실행하십시오azd init -t azure-search-openai-javascript 실행하십시오기존 Azure 서비스가없고 새로운 배포에서 시작하려는 경우 다음 명령을 실행하십시오.
azd up 이는 Azure Resources를 제공 하고이 샘플을 ./data 폴더에있는 파일을 기반으로 검색 지수를 구축하는 것을 포함하여 해당 리소스에 배포됩니다.eastus2 에 배포됩니다. azd env set AZURE_OPENAI_RESOURCE_GROUP_LOCATION {location} 으로 다른 위치를 설정할 수 있습니다. 현재 짧은 위치 목록 만 허용됩니다. 이 위치 목록은 OpenAI 모델 가용성 테이블을 기반으로하며 가용성이 변경됨에 따라 구식이 될 수 있습니다.eastus2 에 배포됩니다. azd env set AZURE_WEBAPP_LOCATION {location} 으로 다른 위치를 설정할 수 있습니다. 현재 짧은 위치 목록 만 허용됩니다. 정적 웹 앱은 글로벌 서비스이며 선택한 위치는이 샘플에서 사용되지 않는 관리 기능 앱에만 영향을 미칩니다.다음과 같습니다.
참고 : 응용 프로그램을 완전히 배포하는 데 15 분 이상이 걸릴 수 있습니다.
기존 Azure 리소스가 이미있는 경우 azd 환경 값을 설정하여 재사용 할 수 있습니다.
azd env set AZURE_RESOURCE_GROUP {Name of existing resource group}azd env set AZURE_LOCATION {Location of existing resource group} azd env set AZURE_OPENAI_SERVICE {Name of existing OpenAI service}azd env set AZURE_OPENAI_RESOURCE_GROUP {Name of existing resource group that OpenAI service is provisioned to}azd env set AZURE_OPENAI_CHATGPT_DEPLOYMENT {Name of existing ChatGPT deployment} . chatgpt 배포가 기본 '채팅'이 아닌 경우에만 필요합니다.azd env set AZURE_OPENAI_EMBEDDING_DEPLOYMENT {Name of existing GPT embedding deployment} . 임베딩 배포가 기본 '임베딩'이 아닌 경우에만 필요합니다. azd env set AZURE_SEARCH_SERVICE {Name of existing Azure AI Search service}azd env set AZURE_SEARCH_SERVICE_RESOURCE_GROUP {Name of existing resource group with ACS service}azd up 단계를 선택할 수있는 위치와 다른 위치에 있으면 azd env set AZURE_SEARCH_SERVICE_LOCATION {Location of existing service} 실행하십시오.azd env set AZURE_SEARCH_SERVICE_SKU {Name of SKU} 실행하십시오. 무료 계층은 관리 된 ID를 지원하지 않기 때문에 작동하지 않습니다. (다른 가능한 값 참조) 기존 스토리지 계정을 사용할 수도 있습니다. 기존 리소스를 구성하기 위해 azd env set 에 전달할 환경 변수 목록은 ./infra/main.parameters.json 참조하십시오.
이제 위의 처음부터 배포하는 단계에 따라 azd up 실행할 수 있습니다. 리소스를 제공하고 코드를 배포합니다.
app 폴더에서 백엔드/프론트 엔드 코드 만 변경 한 경우 Azure 리소스를 다시 제공 할 필요가 없습니다. 당신은 그냥 실행할 수 있습니다 :
azd deploy
인프라 파일 ( infra 폴더 또는 azure.yaml )을 변경 한 경우 Azure 리소스를 다시 제공해야합니다. 실행하여 할 수 있습니다.
azd up
다른 사람이 완전히 배치 된 기존 환경에 대한 액세스 권한을 부여하려면 다음과 같은 단계를 수행 할 수 있습니다.
azd init -t azure-search-openai-javascript 실행 하거나이 저장소를 복제하십시오.azd env refresh -e {environment name} run azd 환경 이름, 구독 ID 및 위치가 필요합니다.이 명령을 실행하십시오. .azure/{env name}/.env 파일에서 해당 값을 찾을 수 있습니다. 이렇게하면 앱을 로컬로 실행하는 데 필요한 모든 설정으로 AZD Environment의 .env 파일이 채워집니다.AZURE_PRINCIPAL_ID .env 파일 또는 활성 쉘에서 Azure ID로 설정하여 az ad signed-in-user show 통해 얻을 수 있습니다../scripts/roles.ps1 또는 ./scripts/roles.sh 를 실행하여 필요한 모든 역할을 사용자에게 할당하십시오. 구독에서 역할을 수행하는 데 필요한 권한이없는 경우이 스크립트를 실행해야 할 수도 있습니다. 스크립트가 실행되면 앱을 로컬로 실행할 수 있어야합니다. 이 샘플에서 생성 된 모든 리소스를 정리하려면 다음과 같습니다.
azd down --purge 실행하십시오y 입력하십시오.y 입력하십시오.리소스 그룹과 모든 리소스가 삭제됩니다.
기본적으로 배포 된 Azure Web 앱에는 인증 또는 액세스 제한이 활성화되지 않으므로 웹 앱에 대한 네트워크 액세스가 가능한 누구나 인덱스 된 데이터와 채팅 할 수 있습니다. Add Add Authentication Tutorial을 따르고 배포 된 웹 앱에 대해 설정하여 Azure Entra ID에 대한 인증이 필요할 수 있습니다.
그런 다음 특정 사용자 또는 그룹 세트에 대한 액세스를 제한하려면 "할당 필요"를 변경하여 Azure Entra 앱을 제한하는 단계를 따라야합니다. 엔터프라이즈 응용 프로그램에서 옵션을 한 다음 사용자/그룹 액세스 할당. 명시 적 액세스 권한이 부여되지 않은 사용자는 오류 메시지를 받게됩니다 -AADSTS50105 : 관리자는 응용 프로그램에 특별히 부여되지 않은 ( '할당 된') 액세스가없는 한 사용자를 차단하기 위해 응용 프로그램 <app_name>을 구성했습니다 .-
추가 보안 메커니즘을 배포하는 것이 좋습니다. 해당되는 경우 VNET 설정 또는 프록시 정책 설정을 고려하십시오.
기본적으로 배포 된 검색 API는 배포 된 웹 앱 원점과 동일한 원점에서만 요청을 허용합니다. 다른 원점에서 호스팅되는 프론트 엔드의 CORS를 활성화하려면 다음을 실행하십시오.
azd env set ALLOWED_ORIGIN https://<your-domain.com>azd up 실행하십시오 azd up 명령을 성공적으로 실행 한 후에 만 로컬로 실행할 수 있습니다.
azd auth login 실행하십시오azd env get-values > .env 를 실행하려면 앱의 환경 변수를 얻으십시오.az login 실행하십시오npm start 하거나 "VS Code Task : START APP"를 실행하여 프로젝트를 로컬로 시작하십시오. 웹 앱에서 일단 :
검색 API 서비스는 AI 채팅 앱에 대한 HTTP 프로토콜을 구현합니다. 이 저장소에 소개 된 Node.js 구현 대신이 저장소의 Python Backend 클라이언트와 같은 동일한 프로토콜을 구현하는 모든 서비스로 교체 할 수 있습니다.
그렇게하려면 다음 단계를 따르십시오.
azd env get-values | grep WEBAPP_URI 얻으려면 URL을 얻습니다.http://localhost:5173 사용하십시오.https://<your_codespace_base_url>-5173.app.github.dev 사용하십시오.azd env set ALLOWED_ORIGIN <your_frontend_url> 로 Frontend URL을 허용 된 원점으로 설정하십시오.azd env get-values | grep BACKEND_URI .azd env set BACKEND_URI <your_backend_url> 실행하십시오. 배포 된 웹 앱을 사용하려면 azd up 실행하여 재배치하십시오.
컴퓨터 또는 코드 스페이스에서 로컬 웹 앱을 사용하려면 다음을 실행하십시오.
# Export the environment variable.
# The syntax may be different depending on your shell or if you're using Windows.
export BACKEND_URI= < your_backend_url >
# Start the app
npm start --workspace=webapp이 샘플은 Azure 컨테이너 앱에 배포 된 백엔드 서비스와 API의 두 가지 응용 프로그램과 Azure 정적 웹 앱에 배포 된 프론트 엔드 응용 프로그램으로 구성됩니다. 기본적으로 배포 된 Azure Container 앱에는 인증 또는 액세스 제한이 활성화되지 않으므로 컨테이너 앱에 대한 라우팅 가능한 네트워크 액세스가있는 사람은 색인 데이터와 채팅 할 수 있습니다. 컨테이너 추가 앱 인증 자습서를 따르고 배포 된 Azure Container App에 대해 설정하여 Azure Entra ID에 대한 인증이 필요할 수 있습니다.
특정 사용자 또는 그룹 세트에 대한 액세스를 제한하려면 "할당 필요"를 변경하여 Azure Entra 앱을 제한하는 단계를 따라야합니다. 엔터프라이즈 응용 프로그램에서 옵션을 한 다음 사용자/그룹 액세스 할당. 명시 적 액세스 권한이 부여되지 않은 사용자는 오류 메시지를 받게됩니다 -AADSTS50105 : 관리자는 응용 프로그램에 특별히 부여되지 않은 ( '할당 된') 액세스가없는 한 사용자를 차단하기 위해 응용 프로그램 <app_name>을 구성했습니다 .-
이 샘플은 자체 생산 응용 프로그램의 출발점으로 설계되었지만 생산에 배포하기 전에 보안 및 성능을 철저히 검토해야합니다. 고려해야 할 사항은 다음과 같습니다.
infra/main.bicep 의 chatGptDeploymentCapacity 및 embeddingDeploymentCapacity 매개 변수를 계정의 최대 용량으로 변경하여 용량을 늘릴 수 있습니다. Azure Openai Studio의 할당량 탭을보고 얼마나 많은 용량을 가지고 있는지 이해할 수 있습니다.Standard_LRS SKU를 사용합니다. 탄력성을 향상 시키려면 생산 배포에 Standard_ZRS 사용하는 것이 좋습니다. 이는 infra/main.bicep 의 storage 모듈 아래에서 sku 속성을 사용하는 것을 지정할 수 있습니다.Standard SKU를 사용하므로 한 달에 1000 개의 무료 쿼리가 제공됩니다. 앱이 1000 개 이상의 질문을 경험한다고 가정하면 semanticSearch "표준"으로 변경하거나 요청 옵션에서 의미 검색을 완전히 비활성화해야합니다. 검색 서비스 용량에 대한 오류가 초과되는 경우 infra/core/search/search-services.bicep 또는 Azure 포털에서 수동으로 스케일링하여 replicaCount 변경하여 복제본 수를 늘리는 것이 도움이 될 수 있습니다.청킹을 통해 토큰 제한으로 인해 OpenAI에 보내는 정보의 양을 제한 할 수 있습니다. 컨텐츠를 분해함으로써 OpenAI에 주입 할 수있는 잠재적 인 텍스트 덩어리를 쉽게 찾을 수 있습니다. 우리가 사용하는 청킹 방법은 하나의 청크를 끝내는 문장이 다음에 시작되도록 텍스트의 슬라이딩 창을 활용합니다. 이를 통해 텍스트의 맥락을 잃을 가능성을 줄일 수 있습니다.
더 많은 문서를 업로드하려면 문서를 데이터/폴더에 넣고 ./scripts/index-data.sh 또는 ./scripts/index-data.ps1 을 실행하십시오.
이 사용 사례에 대한 또 다른 인기있는 저장소는 다음과 같습니다. https://github.com/microsoft/sample-app-aiai-chatgpt/
이 저장소는 Azure Openai Studio와 Azure Portal을 사용하는 고객이 설계하여 설계되었습니다. 또한 처음부터 완전히 배포하려는 사람들에 대한 azd 지원도 포함됩니다.
주요 차이점 :
기능 비교 :
| 특징 | Azure-Search-Openai-JavaScript | 샘플 App-Aoai-Chatgpt |
|---|---|---|
| 헝겊 접근법 | 여러 접근법 | ChatCompletion API Data_Sources를 통해서만 |
| 벡터 지원 | ✅ 예 | ✅ 예 |
| 데이터 수집 | ✅ 예 (MD) | ✅ 예 (PDF, TXT, MD, HTML) |
| 지속적인 채팅 기록 | 아니요 (브라우저 탭 만) | ✅ 예, COSMOSDB에서 |
기술 비교 :
| 기술 | Azure-Search-Openai-JavaScript | 샘플 App-Aoai-Chatgpt |
|---|---|---|
| 프론트 엔드 | 반응/조명 | 반응 |
| 백엔드 | node.js (Fastify) | 파이썬 (플라스크) |
| 벡터 DB | Azure AI 검색 | Azure AI 검색 |
| 전개 | Azure Developer Cli (AZD) | Azure Portal, AZ, AZD |
이 명령을 실행하십시오.
azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4 계정이 허용되는 TPM의 양에 따라 infra/main.bicep 파일의 용량을 조정해야 할 수도 있습니다.
채팅 탭은 채팅 읽기-retieve-read.ts에서 프로그래밍 된 접근법을 사용합니다. Ask 탭은 Ask-Retrieve-then-Read.ts에서 프로그래밍 된 접근 방식을 사용합니다. [에이전트 사용] (https://github.com/azure-samples/azure-search-openai-javascript/blob/main/packages/search/src/lib/proaches/ask-Read-Retrieve-Read.ts.
azd up 명령은 Azure Developer CLI에서 제공되며 Azure 리소스를 프로비저닝하고 선택한 Azure 호스트에 코드를 배포합니다.
azd up 명령은 azure.yaml 파일을 infra/ Folder의 인프라 -Code .bicep 파일과 결합합니다. 이 프로젝트의 azure.yaml 파일은 Prepackage 단계 및 후보자 단계에 대한 몇 가지 "후크"를 선언합니다. up 명령은 먼저 노드 종속성을 설치하고 React.js 기반 JavaScript 파일을 빌드하는 prepackage Hook를 실행합니다. 그런 다음 모든 코드 (Frontend 및 Backend Services)를 나중에 배포 할 zip 파일로 패키지합니다.
다음으로 main.bicep 및 main.parameters.json 기반으로 리소스를 제공합니다. 이 시점에서 OpenAI 자원 위치에 대한 기본값이 없으므로 사용 가능한 지역 목록에서 위치를 선택하도록 요청합니다. 그런 다음 Azure에 요청을 보내어 필요한 모든 자원을 제공합니다. 모든 것을 프로비저닝하면 postprovision 후크를 실행하여 로컬 데이터를 처리하고 Azure AI 검색 인덱스에 추가합니다.
마지막으로 azure.yaml 을보고 Azure 호스트 (컨테이너 앱 및 정적 웹 앱,이 경우)를 결정하고 ZIP를 Azure App Service에 업로드합니다. azd up 명령은 이제 완료되었지만 최초 배포 후 앱을 완전히 사용할 수 있고 작동하는 데 몇 분이 걸릴 수 있습니다.
관련 명령은 업데이트 된 앱 코드를 배포하기 위해 프로비저닝 (인프라 파일이 변경되는 경우) 및 azd deploy azd provision 입니다.
가장 일반적인 실패 시나리오 및 솔루션은 다음과 같습니다.
구독 ( AZURE_SUBSCRIPTION_ID )은 Azure Openai 서비스에 액세스 할 수 없습니다. AZURE_SUBSCRIPTION_ID OpenAI 액세스 요청 프로세스에 지정된 ID와 일치하는지 확인하십시오.
Azure Openai (예 : US East US 대신 US 2) 또는 사용하려는 모델이 활성화되지 않은 곳에서 활성화되지 않은 지역에서 리소스를 만들려고합니다. 모델 가용성 의이 매트릭스를 참조하십시오.
당신은 할당량을 초과했으며, 가장 자주 지역 당 자원 수를 초과했습니다. 할당량 및 한계에 대한이 기사를 참조하십시오.
"동일한 리소스 이름이 허용되지 않는"충돌을 받고 있습니다. 샘플을 여러 번 실행하고 매번 생성 한 리소스를 삭제했지만 제거하는 것을 잊었 기 때문일 수 있습니다. Azure는 소프트 삭제에서 제거하지 않는 한 48 시간 동안 자원을 유지합니다. 제거 자원에 대한이 기사를 참조하십시오.
azd up 실행하고 웹 사이트를 방문한 후 브라우저에서 '404를 찾을 수없는'것을 볼 수 있습니다. 10 분 동안 기다렸다가 다시 시작할 수 있으므로 다시 시도하십시오. 그런 다음 azd deploy 실행하고 다시 기다리십시오. 배포 된 앱과 여전히 오류가 발생하는 경우 앱 서비스 앱 배포를 디버깅하기위한 이러한 팁을 참조하고 오류 로그가 문제를 해결하는 데 도움이되지 않으면 문제를 제출하십시오.
오류가 발생하고 401 Principal does not have access to API/Operation . 환경 변수에는 AZURE_TENANT_ID , AZURE_CLIENT_ID 및 AZURE_CLIENT_SECRET 포함되기 때문일 수 있습니다. 정상적인 액세스를 보장하기 위해 관련 서비스 원금 에 권한을 부여하거나 환경에서 이러한 변수를 제거해야합니다. 자세한 내용은 Azure Identity SDK를 참조하십시오.
참고 :이 데모에 사용 된 문서에는 언어 모델 (Azure OpenAi Service)을 사용하여 생성 된 정보가 포함되어 있습니다. 이 문서에 포함 된 정보는 데모 목적으로 만 사용되며 Microsoft의 의견이나 신념을 반영하지 않습니다. Microsoft는이 문서에 포함 된 정보와 관련하여 완전성, 정확성, 신뢰성, 적합성 또는 가용성에 대해 어떤 종류의 표현 또는 묵시적 임의의 진술이나 보증도하지 않습니다. 모든 권리가 Microsoft에 보유됩니다.
