azure search openai javascript
1.0.0
Esta muestra demuestra algunos enfoques para crear experiencias similares a ChatGPT sobre sus propios datos utilizando el patrón de generación aumentada de recuperación. Utiliza el servicio Azure OpenAI para acceder al modelo CHATGPT (GPT-35-TURBO) y Azure AI Buscando la indexación y recuperación de datos.
El repositorio incluye datos de muestra, por lo que está listo para probar de extremo a final. En esta aplicación de muestra utilizamos una empresa ficticia llamada Contoso Real Estate, y la experiencia permite a sus clientes hacer preguntas de soporte sobre el uso de sus productos. Los datos de muestra incluyen un conjunto de documentos que describen sus términos de servicio, política de privacidad y una guía de soporte.
La aplicación está hecha de múltiples componentes, incluidos:
Mira una descripción general de la aplicación
Importante: para implementar y ejecutar esta muestra, necesitará:
Microsoft.Authorization/roleAssignments/write , como administrador de control de acceso basado en roles, administrador de acceso de usuario o propietario. Si no tiene permisos de nivel de suscripción, se les debe otorgarle RBAC para un grupo de recursos existente e implementarse en ese grupo existente.Microsoft.Resources/deployments/write en un nivel de suscripción. Los precios pueden variar por región y uso. Los costos exactos no se pueden estimar. Puede probar la calculadora de precios de Azure para los recursos a continuación.
azd down --purge .
Hay múltiples formas de configurar con éxito este proyecto.
La forma más fácil de comenzar es con GitHub CodeSpaces que proporciona preconfiguraciones para configurar todas las herramientas para usted. Lea más a continuación. Alternativamente, puede configurar su entorno local follando las instrucciones a continuación.
Puede ejecutar este repositorio prácticamente utilizando GitHub CodesPaces, que abrirá un código VS basado en la web en su navegador:
Una opción similar a CodeSpaces es vs contenedores remotos de código, que abrirán el proyecto en su instancia local de código VS utilizando la extensión de contenedores Dev:
pwsh.exe desde un comando PowerShell. Si esto falla, es probable que necesite actualizar PowerShell.Luego obtenga el código del proyecto:
azd auth loginazd init -t azure-search-openai-javascriptEjecute el siguiente comando, si no tiene ningún servicio de Azure preexistente y desea comenzar desde una nueva implementación.
azd up : esto provocará recursos de Azure e implementará esta muestra en esos recursos, incluida la construcción del índice de búsqueda basado en los archivos encontrados en la carpeta ./data .eastus2 . Puede establecer una ubicación diferente con azd env set AZURE_OPENAI_RESOURCE_GROUP_LOCATION {location} . Actualmente, solo se acepta una breve lista de ubicaciones. Esa lista de ubicaciones se basa en la tabla de disponibilidad del modelo Operai y puede quedarse obsoleto a medida que los cambios de disponibilidad.eastus2 . Puede establecer una ubicación diferente con azd env set AZURE_WEBAPP_LOCATION {location} . Actualmente, solo se acepta una breve lista de ubicaciones. Tenga en cuenta que la aplicación web Static es un servicio global, y la ubicación que elija solo afectará la aplicación de funciones administradas que no se utiliza en esta muestra.Se verá como lo siguiente:
Nota: La aplicación puede tardar más de 15 minutos en implementarse por completo.
Si ya tiene recursos de Azure existentes, puede reutilizarlos estableciendo valores de entorno 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} . Solo necesario si su implementación de chatgpt no es el 'chat' predeterminado.azd env set AZURE_OPENAI_EMBEDDING_DEPLOYMENT {Name of existing GPT embedding deployment} . Solo se necesita si su implementación de incrustaciones no es la 'incrustación' predeterminada. 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 , luego ejecute azd env set AZURE_SEARCH_SERVICE_LOCATION {Location of existing service}azd env set AZURE_SEARCH_SERVICE_SKU {Name of SKU} . El nivel gratuito no funcionará, ya que no admite la identidad administrada. (Ver otros valores posibles) También puede usar una cuenta de almacenamiento existente. Consulte ./infra/main.parameters.json para una lista de variables de entorno para pasar a azd env set para configurar esos recursos existentes.
Ahora puede ejecutar azd up , siguiendo los pasos para implementarse desde cero arriba. Que provisen recursos e implementarán el código.
Si solo ha cambiado el código de backend/frontend en la carpeta app , entonces no necesita volver a proporcionar los recursos de Azure. Puedes simplemente ejecutar:
azd deploy
Si ha cambiado los archivos de infraestructura (carpeta infra o azure.yaml ), deberá volver a proporcionar los recursos de Azure. Puedes hacerlo ejecutando:
azd up
Para darle a otra persona acceso a un entorno completamente desplegado y existente, ya sea usted o pueden seguir estos pasos:
azd init -t azure-search-openai-javascript o Clone este repositorio.azd env refresh -e {environment name} Necesitará el nombre del entorno AZD, la identificación de suscripción y la ubicación para ejecutar este comando. Puede encontrar esos valores en su archivo .azure/{env name}/.env . Esto llenará el archivo .env de su entorno AZD con todas las configuraciones necesarias para ejecutar la aplicación localmente.AZURE_PRINCIPAL_ID , ya sea en ese archivo .env o en el shell activo a su ID de Azure, que pueden obtener con az ad signed-in-user show ../scripts/roles.ps1 o ./scripts/roles.sh para asignar todos los roles necesarios al usuario. Si no tienen el permiso necesario para crear roles en la suscripción, es posible que deba ejecutar este script para ellos. Una vez que se ejecuta el script, deberían poder ejecutar la aplicación localmente. Para limpiar todos los recursos creados por esta muestra:
azd down --purgeyyEl grupo de recursos y todos los recursos se eliminarán.
De manera predeterminada, la aplicación web de Azure implementada no tendrá habilitadas restricciones de autenticación o acceso, lo que significa que cualquier persona con acceso de red enrutable a la aplicación web puede chatear con sus datos indexados. Puede necesitar autenticación a su ID de Azure Entra siguiendo el tutorial de autenticación Agregar aplicación y establecerlo con la aplicación web implementada.
Para luego limitar el acceso a un conjunto específico de usuarios o grupos, puede seguir los pasos desde restringir su aplicación Azure Entra a un conjunto de usuarios cambiando "Asignación requerida"? Opción debajo de la aplicación Enterprise y luego asignando acceso a usuarios/grupos. Los usuarios no otorgados el acceso explícito recibirá el mensaje de error -AADSTS50105: su administrador ha configurado la aplicación <PPP_NAME> para bloquear a los usuarios a menos que se les otorgue específicamente el acceso ('asignado') a la aplicación.
Recomendamos implementar mecanismos de seguridad adicionales. Cuando corresponda, considere configurar un VNET o configurar una política de proxy.
De manera predeterminada, la API de búsqueda implementada solo permitirá solicitudes del mismo origen que el origen de la aplicación web implementada. Para habilitar CORS para un frontend alojado en un origen diferente, ejecute:
azd env set ALLOWED_ORIGIN https://<your-domain.com>azd up Solo puede ejecutar localmente después de haber ejecutado con éxito el comando azd up .
azd auth loginazd env get-values > .env para obtener las variables de entorno para la aplicaciónaz loginnpm start o ejecute la "Tarea VS Código: Inicio de la aplicación" para iniciar el proyecto localmente. Una vez en la aplicación web:
El servicio API de búsqueda implementa el protocolo HTTP para las aplicaciones de chat AI. Se puede intercambiar con cualquier servicio que implementa el mismo protocolo, como el cliente de backend de Python en este repositorio en lugar de la implementación de Node.js presentada en este repositorio.
Para hacerlo, siga estos pasos:
azd env get-values | grep WEBAPP_URI para obtener la URL.http://localhost:5173 .https://<your_codespace_base_url>-5173.app.github.dev .azd env set ALLOWED_ORIGIN <your_frontend_url> .azd env get-values | grep BACKEND_URI .azd env set BACKEND_URI <your_backend_url> . Si desea utilizar la aplicación web implementada, ejecute azd up redploy.
Si desea utilizar la aplicación web local en su máquina o en espacios de códigos, ejecute:
# 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=webappEsta muestra está compuesta por dos aplicaciones: un servicio de backend y una API, implementado en aplicaciones de contenedores Azure y una aplicación frontend, implementada en aplicaciones web estáticas de Azure. De manera predeterminada, la aplicación de contenedor Azure implementada no tendrá habilitadas restricciones de autenticación o acceso, lo que significa que cualquier persona con acceso de red enrutable a la aplicación Contenedor puede chatear con sus datos indexados. Puede requerir autenticación a su ID de Azure Entra siguiendo el tutorial de autenticación de la aplicación Agregar contenedor y establecerla con la aplicación de contenedor Azure implementada.
Para limitar el acceso a un conjunto específico de usuarios o grupos, puede seguir los pasos desde restringir su aplicación Azure Entra a un conjunto de usuarios cambiando "Asignación requerida"? Opción debajo de la aplicación Enterprise y luego asignando acceso a usuarios/grupos. Los usuarios no otorgados el acceso explícito recibirá el mensaje de error -AADSTS50105: su administrador ha configurado la aplicación <PPP_NAME> para bloquear a los usuarios a menos que se les otorgue específicamente el acceso ('asignado') a la aplicación.
Esta muestra está diseñada para ser un punto de partida para su propia aplicación de producción, pero debe hacer una revisión exhaustiva de la seguridad y el rendimiento antes de implementar la producción. Aquí hay algunas cosas a considerar:
chatGptDeploymentCapacity e embeddingDeploymentCapacity en infra/main.bicep a la capacidad máxima de su cuenta. También puede ver la pestaña Cuotas en Azure OpenAI Studio para comprender cuánta capacidad tiene.Standard_LRS . Para mejorar su resiliencia, recomendamos usar Standard_ZRS para implementaciones de producción, que puede especificar utilizando la propiedad sku bajo el módulo storage en infra/main.bicep .Standard con la opción de búsqueda semántica gratuita, que le ofrece 1000 consultas gratuitas al mes. Suponiendo que su aplicación experimentará más de 1000 preguntas, debe cambiar semanticSearch a "estándar" o deshabilitar la búsqueda semántica por completo en las opciones de solicitud. Si ve errores sobre la capacidad del servicio de búsqueda que se excede, puede encontrar útil aumentar el número de réplicas cambiando replicaCount en infra/core/search/search-services.bicepLa fragmentación nos permite limitar la cantidad de información que enviamos a OpenAI debido a los límites de token. Al romper el contenido, nos permite encontrar fácilmente fragmentos potenciales de texto que podemos inyectar en OpenAI. El método de fragmentación que usamos aprovecha una ventana deslizante de texto de tal manera que las oraciones que terminan un fragmento comenzarán la siguiente. Esto nos permite reducir la posibilidad de perder el contexto del texto.
Para cargar más documentos, colóquelos en la carpeta de datos/ejecución ./scripts/index-data.sh o ./scripts/index-data.ps1 .
Otro repositorio popular para este caso de uso está aquí: https://github.com/microsoft/sample-app-aoai-chatgpt/
Ese repositorio está diseñado para el uso de clientes que utilizan Azure Operai Studio y Azure Portal para la configuración. También incluye el soporte azd para las personas que desean implementarlo completamente desde cero.
Las diferencias principales:
Comparación de características:
| Característica | Azure-Search-Openai-JavaScript | muestra-app-aoai-chatgpt |
|---|---|---|
| Enfoque de trapo | Múltiples enfoques | Solo a través de chatcompletion API data_sources |
| Soporte vectorial | ✅ Sí | ✅ Sí |
| Ingestión de datos | ✅ Sí (MD) | ✅ Sí (PDF, TXT, MD, HTML) |
| Historia de chat persistente | No (pestaña del navegador solamente) | ✅ Sí, en Cosmosdb |
Comparación de tecnología:
| Técnico | Azure-Search-Openai-JavaScript | muestra-app-aoai-chatgpt |
|---|---|---|
| Interfaz | Reaccionar/encendido | Reaccionar |
| Backend | Node.js (fastify) | Python (frasco) |
| Vector DB | Azure AI Search | Azure AI Search |
| Despliegue | Desarrollador de Azure CLI (AZD) | Azure Portal, AZ, AZD |
Ejecute estos comandos:
azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4 También es posible que deba ajustar la capacidad en el archivo infra/main.bicep , dependiendo de cuánto TPM esté permitido su cuenta.
La pestaña de chat utiliza el enfoque programado en chat-read-retrieve-read.ts. La pestaña Ask utiliza el enfoque programado en Ask-Retrieve-Then-Read.ts. También hay otro enfoque de One/solicitante disponible, [usando un agente] (https://github.com/azure-samples/azure-search-openai-javascript/blob/main/packages/search/src/lib/approaches/ask-read-retrieve-read.ts.
El comando azd up proviene del desarrollador de Azure CLI, y se encarga de aprovisionar los recursos de Azure e implementar el código para los hosts Azure seleccionados.
El comando azd up utiliza el archivo azure.yaml combinado con los archivos de infraestructura-as- .bicep en la carpeta infra/ . El archivo azure.yaml para este proyecto declara varios "ganchos" para los pasos de prepackage y postprovision. El comando up primero ejecuta el gancho prepackage que instala dependencias de nodos y construye los archivos JavaScript basados en React.js. Luego empaqueta todo el código (servicios de frontend y backend) en un archivo zip que implementará más adelante.
A continuación, disposición los recursos basados en main.bicep y main.parameters.json . En ese momento, dado que no hay un valor predeterminado para la ubicación de recursos de Operai, le pide que elija una ubicación de una breve lista de regiones disponibles. Luego enviará solicitudes a Azure para aprovisionar todos los recursos requeridos. Con todo provisto, ejecuta el gancho postprovision para procesar los datos locales y agregarlo a un índice de búsqueda de AI Azure.
Finalmente, mira a azure.yaml para determinar el host de Azure (aplicaciones de contenedores y aplicaciones web estáticas, en este caso) y carga el servicio de aplicaciones Zip to Azure. El comando azd up ahora está completo, pero puede tardar unos minutos en que la aplicación esté completamente disponible y funcione después de la implementación inicial.
Los comandos relacionados son azd provision para el aprovisionamiento solo (si los archivos infra cambian) y azd deploy para implementar el código de la aplicación actualizado.
Estos son los escenarios y soluciones de falla más comunes:
La suscripción ( AZURE_SUBSCRIPTION_ID ) no tiene acceso al servicio Azure OpenAI. Asegúrese de que AZURE_SUBSCRIPTION_ID coincida con el ID especificado en el proceso de solicitud de acceso OpenAI.
Está intentando crear recursos en regiones no habilitadas para Azure OpenAI (por ejemplo, East US 2 en lugar de East US), o donde el modelo que está tratando de usar no está habilitado. Vea esta matriz de disponibilidad del modelo.
Has superado una cuota, con mayor frecuencia el número de recursos por región. Vea este artículo sobre cuotas y límites.
Estás obteniendo conflictos de "el mismo nombre de recurso no permitido". Eso es probable porque haya ejecutado la muestra varias veces y elimine los recursos que ha estado creando cada vez, pero se olvida de purgarlos. Azure mantiene recursos durante 48 horas a menos que purgas de Soft Elimine. Vea este artículo sobre recursos de purga.
Después de ejecutar azd up y visitar el sitio web, verá un '404 no encontrado' en el navegador. Espere 10 minutos y vuelva a intentarlo, ya que podría estar comenzando. Luego intente ejecutar azd deploy y espere nuevamente. Si aún encuentra errores con la aplicación implementada, consulte estos consejos para depurar las implementaciones de la aplicación de servicio de la aplicación y presentar un problema si los registros de errores no lo ayudan a resolver el problema.
Está recibiendo un error 401 Principal does not have access to API/Operation mientras ejecuta el proyecto localmente o intenta implementar. Eso es probable porque sus variables de entorno incluyen AZURE_TENANT_ID , AZURE_CLIENT_ID y AZURE_CLIENT_SECRET . Debe otorgar permisos al principal del servicio relacionado o eliminar estas variables de su entorno para garantizar el acceso normal. Para obtener más detalles, consulte Azure Identity SDK.
Nota: Los documentos utilizados en esta demostración contienen información generada utilizando un modelo de idioma (servicio Azure OpenAI). La información contenida en estos documentos es solo para fines de demostración y no refleja las opiniones o creencias de Microsoft. Microsoft no hace representaciones o garantías de ningún tipo, expresas o implícitas, sobre la integridad, precisión, confiabilidad, idoneidad o disponibilidad con respecto a la información contenida en este documento. Todos los derechos reservados para Microsoft.
