Поделиться через

Руководство: Создание приложения с дополненной генерацией в Azure App Service с помощью Azure OpenAI и Azure AI Search (FastAPI)

В этом руководстве вы создадите приложение Python получения дополненного поколения (RAG) с помощью FastAPI, Azure OpenAI и Azure AI Search и разверните его в Azure App Service. Это приложение демонстрирует, как реализовать интерфейс чата, который извлекает информацию из собственных документов и использует службы ИИ в Azure для предоставления точных, контекстно осведомленных ответов с соответствующими цитатами. Решение использует управляемые удостоверения для проверки подлинности без пароля между службами.

Снимок экрана, показывающий интерфейс чата FastAPI во введении.

В этом руководстве вы узнаете, как:

  • Разверните приложение FastAPI, использующее шаблон RAG со службами ИИ в Azure.
  • Настройте Azure OpenAI и Azure AI Search для гибридного поиска.
  • Отправка и индексирование документов для использования в приложении, на основе ИИ.
  • Используйте управляемые удостоверения для безопасного взаимодействия между службами.
  • Протестируйте реализацию RAG локально с помощью рабочих служб.

Обзор архитектуры

Прежде чем приступить к развертыванию, полезно понять архитектуру приложения, которое вы создадите. Следующая диаграмма взята из настраиваемого шаблона RAG для Azure AI Search:

Диаграмма архитектуры с веб-приложением, подключённым к Azure OpenAI и Azure AI Search, и хранилище выступает в качестве источника данных.

В этом руководстве приложение Blazer в Службе приложений заботится как о пользовательском интерфейсе приложения, так и сервере приложений. Однако он не делает отдельный запрос знаний для Azure AI Search. Вместо этого он сообщает Azure OpenAI выполнять запросы знаний, указывающие Azure AI Search в качестве источника данных. Эта архитектура предлагает несколько ключевых преимуществ:

  • Integrated Vectorization: встроенные возможности векторизации в Azure AI Search позволяют легко и быстро обрабатывать все документы для поиска, не требуя дополнительного кода для создания эмбеддингов.
  • Simplified API Access. С помощью Azure OpenAI On Your Data с Azure AI Search в качестве источника данных для завершений Azure OpenAI нет необходимости реализовывать сложный векторный поиск или генерацию вложений. Это всего лишь один вызов API и Azure OpenAI обрабатывает все, включая проектирование запросов и оптимизацию запросов.
  • Расширенные возможности поиска: встроенная векторизация предоставляет все, что необходимо для расширенного гибридного поиска с семантической повторной настройкой, которая объединяет сильные стороны сопоставления ключевых слов, сходства векторов и ранжирования на основе ИИ.
  • Полная поддержка ссылок: ответы автоматически включают ссылки на исходные документы, делая информацию проверяемой и отслеживаемой.

Предпосылки

1. Открытие примера с помощью codespaces

Самый простой способ приступить к работе — использовать GitHub Codespaces, которая предоставляет полную среду разработки со всеми необходимыми средствами, предварительно установленными.

  1. Перейдите к репозиторию GitHub по адресу https://github.com/Azure-Samples/app-service-rag-openai-ai-search-python.

  2. Нажмите кнопку "Код" , перейдите на вкладку "Пространства кода" и нажмите кнопку "Создать пространство кода" на главном.

  3. Подождите несколько минут, пока пространство кода инициализируется. После готовности вы увидите полностью настроенную среду VS Code в браузере.

2. Развертывание примера архитектуры

  1. В терминале войдите в Azure с помощью интерфейса командной строки разработчика Azure:

    azd auth login

    Следуйте инструкциям, чтобы завершить процесс проверки подлинности.

  2. Подготовьте ресурсы Azure с помощью шаблона AZD:

    azd provision

  3. При появлении запроса укажите следующие ответы:

    Вопрос Ответ
    Введите новое имя среды: Введите уникальное имя.
    Выберите Azure подписку для использования: Выберите подписку.
    Выберите группу ресурсов для использования: Выберите команду Создать группу ресурсов.
    Выберите расположение для создания группы ресурсов в: Выберите любой регион. Ресурсы будут созданы на востоке США 2.
    Введите имя новой группы ресурсов: Нажмите Enter.

  4. Дождитесь завершения развертывания. Этот процесс:

    • Создайте все необходимые Azure ресурсы.
    • Разверните приложение в Azure App Service.
    • Настройте безопасную проверку подлинности между службами с помощью управляемых удостоверений.
    • Настройте необходимые назначения ролей для безопасного доступа между службами.

    Замечание

    Дополнительные сведения о работе управляемых удостоверений см. в статье Что такое управляемые удостоверения для ресурсов Azure? и Как использовать управляемые удостоверения со службой приложений.

  5. После успешного развертывания вы увидите URL-адрес развернутого приложения. Запишите этот URL-адрес, но еще не получите доступ к нему, так как вам по-прежнему нужно настроить индекс поиска.

3. Отправка документов и создание индекса поиска

Теперь, когда инфраструктура развернута, необходимо отправить документы и создать индекс поиска, который будет использовать приложение:

  1. На портале Azure перейдите к учетной записи хранения, созданной развертыванием. Имя начинается с имени среды, предоставленного ранее.

  2. Выберитеконтейнеры> данных в меню навигации слева и откройте контейнер документов.

  3. Отправьте примеры документов, нажав кнопку "Отправить". Примеры документов можно использовать из папки sample-docs в репозитории или собственных PDF-файлов, Word или текстовых файлов.

    Снимок экрана: отправка документов в контейнер хранилища.

  4. Перейдите к службе Azure AI Search на портале Azure.

  5. Выберите "Импорт данных" (новое), чтобы начать процесс создания индекса поиска.

    Снимок экрана с кнопкой импорта и векторизации данных в Azure AI Search.

  6. На шаге подключения к данным :

    • Выберите Azure Blob Storage в качестве источника данных.
    • Выберите RAG.
    • Выберите учетную запись хранения и контейнер документов .
    • Выберите Аутентификация с использованием управляемого удостоверения.
    • Нажмите кнопку Далее.

  7. На шаге векторизации текста выполните следующие действия:

    • Выберите службу OpenAI Azure.
    • Выберите text-embedding-ada-002 в качестве модели внедрения. Шаблон AZD уже развернул эту модель.
    • Выберите назначенное системой удостоверение для проверки подлинности .
    • Установите флажок согласия за дополнительные расходы.
    • Нажмите кнопку Далее.

    Подсказка

    Узнайте больше о векторном поиске в Azure AI Search и текстовых встраиваниях в Azure OpenAI.

  8. На шаге векторизация и обогащение изображений:

    • Сохраните параметры по умолчанию.
    • Нажмите кнопку Далее.

  9. На шаге "Дополнительные параметры" выполните следующие действия.

    • Убедитесь, что выбран семантический ранжировщик.
    • (Необязательно) Выберите расписание индексирования. Это полезно, если вы хотите регулярно обновлять индекс с помощью последних изменений в файле.
    • Нажмите кнопку Далее.

  10. На шаге проверки и создания :

    • Скопируйте значение префикса имени объектов . Это имя индекса поиска.
    • Нажмите кнопку "Создать", чтобы запустить процесс индексирования.

  11. Дождитесь завершения процесса индексирования. Это может занять несколько минут в зависимости от размера и количества документов.

  12. Чтобы проверить импорт данных, нажмите кнопку "Начать поиск " и попробуйте выполнить поисковый запрос, например "Расскажите мне о вашей компании".

  13. Вернитесь в терминал Codespace, задайте имя индекса поиска в качестве переменной среды AZD:

    azd env set SEARCH_INDEX_NAME <your-search-index-name>

    Замените <your-search-index-name> на имя индекса, которое вы скопировали ранее. AZD использует эту переменную в последующих развертываниях для задания параметра приложения службы приложений.

4. Тестирование приложения и развертывание

Если вы предпочитаете протестировать приложение локально до или после развертывания, его можно запустить непосредственно из пространства Codespace:

  1. В терминале Codespace получите значения среды AZD:

    azd env get-values

  2. Откройте .env. Используя выходные данные терминала, обновите следующие значения в соответствующих заполнителях <input-manually-for-local-testing>:

    • AZURE_OPENAI_ENDPOINT
    • AZURE_SEARCH_SERVICE_URL
    • AZURE_SEARCH_INDEX_NAME

  3. Войдите в Azure с помощью Azure CLI:

    az login

    Это позволяет клиентской библиотеке удостоверений Azure в примере кода получать токен аутентификации для пользователя, вошедшего в систему.

  4. Запустите приложение локально:

    pip install -r requirements.txt
uvicorn main:app

  5. Когда вы увидите Ваше приложение, запущенное на порту 8000, доступно в выводе, выберите "Открыть в браузере".

  6. Попробуйте задать несколько вопросов в интерфейсе чата. Если вы получите ответ, приложение успешно подключается к ресурсу OpenAI Azure.

  7. Остановите сервер разработки с помощью CTRL+C.

  8. Примените новую конфигурацию SEARCH_INDEX_NAME в Azure и разверните пример кода приложения:

    azd up

5. Тестирование развернутого приложения RAG

После полного развертывания и настройки приложения теперь можно протестировать функциональные возможности RAG:

  1. Откройте URL-адрес приложения, предоставленный в конце развертывания.

  2. Вы увидите интерфейс чата, где можно ввести вопросы о содержимом отправленных документов.

    Снимок экрана: интерфейс чата Blazor.

  3. Попробуйте задать вопросы, относящиеся к содержимому документов. Например, если вы отправили документы в папку sample-docs , попробуйте выполнить следующие вопросы:

    • Как Contoso использует персональные данные?
    • Как подать заявление о гарантии?

  4. Обратите внимание на то, как ответы включают ссылки на исходные документы. Эти ссылки помогают пользователям проверить точность информации и найти дополнительные сведения в исходном материале.

    Снимок экрана: ответ со ссылкой на исходные документы.

  5. Проверьте возможности гибридного поиска, задав вопросы, которые могут быть полезными при использовании различных подходов к поиску.

    • Вопросы с определенной терминологией (хорошо подходит для поиска ключевых слов).
    • Вопросы о понятиях, которые могут быть описаны с помощью различных терминов (хорошо подходит для векторного поиска).
    • Сложные вопросы, требующие понимания контекста (хорошо подходит для семантического ранжирования).

Очистите ресурсы

После завершения работы с приложением можно удалить все ресурсы, чтобы избежать дополнительных затрат:

azd down --purge

Эта команда удаляет все ресурсы, связанные с приложением.

Часто задаваемые вопросы

Как пример кода извлекает цитаты из результатов завершения чата OpenAI Azure?

В примере при использовании Azure AI Search для клиента чата извлекаются цитаты из источника данных. При запросе завершения чата ответ включает объект citations, входящий в контекст сообщения. Пример приложения передает объект ответа клиентскому коду, который извлекает ссылки следующим образом:

fetch('/api/chat/completion', {
    // ...
})
// ...
.then(data => {

    // ...
    const message = choice.message;
    const content = message.content;
    
    // Extract citations from context
    const citations = message.context?.citations || [];
    
    // ...
})

В ответном сообщении содержимое использует [doc#] нотацию для ссылки на соответствующую ссылку в списке, позволяя пользователям трассировать информацию обратно в исходные исходные документы. Дополнительные сведения можно найти здесь

Каковы преимущества использования управляемых удостоверений в этом решении?

Управляемые удостоверения устраняют необходимость хранения учетных данных в коде или конфигурации. С помощью управляемых удостоверений приложение может безопасно получать доступ к службам Azure, таким как Azure OpenAI и Azure AI Search без управления секретами. Этот подход следует принципам безопасности Zero Trust и снижает риск утечки учетных данных.

Как назначаемое системой управляемое удостоверение используется в этой архитектуре и образце приложения?

Развертывание AZD создает управляемые удостоверения, назначаемые системой, для Azure App Service, Azure OpenAI и Azure AI Search. Он также делает соответствующие назначения ролей для каждого из них (см. файл main.bicep ). Сведения о необходимых назначениях ролей см. в разделе Network и конфигурации доступа для Azure OpenAI On Your Data.

В образце приложения FastAPI, Azure SDKs используют это управляемое удостоверение для безопасной аутентификации, поэтому вам не нужно хранить учетные данные или секреты где-либо. Например, клиент AsyncAzureOpenAI инициализирован с помощью DefaultAzureCredential, который автоматически использует управляемое удостоверение при запуске в Azure:

self.credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(
    self.credential,
    "https://cognitiveservices.azure.com/.default"
)

self.openai_client = AsyncAzureOpenAI(
    azure_endpoint=self.openai_endpoint,
    azure_ad_token_provider=token_provider,
    api_version="2024-10-21"
)

Аналогичным образом, при настройке источника данных для Azure AI Search, управляемая идентификация указывается для аутентификации.

data_source = {
    "type": "azure_search",
    "parameters": {
        "endpoint": self.search_url,
        "index_name": self.search_index_name,
        "authentication": {
            "type": "system_assigned_managed_identity"
        },
        # ...
    }
}

response = await self.openai_client.chat.completions.create(
    model=self.gpt_deployment,
    messages=messages,
    extra_body={
        "data_sources": [data_source]
    },
    stream=False
)

Эта настройка обеспечивает безопасное, без пароля взаимодействие между приложением FastAPI и службами Azure, следуя рекомендациям по обеспечению безопасности Zero Trust. Дополнительные сведения о DefaultAzureCredential и клиентской библиотеке Azure Identity для Python.

Как гибридный поиск с семантическим рангером реализован в примере приложения?

Пример приложения настраивает гибридный поиск с семантической ранжированием с помощью пакета SDK Azure OpenAI. В серверной части источник данных настраивается следующим образом:

data_source = {
    "type": "azure_search",
    "parameters": {
        # ...
        "query_type": "vector_semantic_hybrid",
        "semantic_configuration": f"{self.search_index_name}-semantic-configuration",
        "embedding_dependency": {
            "type": "deployment_name",
            "deployment_name": self.embedding_deployment
        }
    }
}

Эта конфигурация позволяет приложению объединять векторный поиск (семантическое сходство), сопоставление ключевых слов и семантический ранжирование в одном запросе. Семантический рангировщик переупорядочения результатов возвращает наиболее релевантные и контекстно соответствующие ответы, которые затем используются Azure OpenAI для создания ответов.

Имя семантической конфигурации определяется автоматически процессом интегрированной векторизации. Он использует имя индекса поиска в качестве префикса и добавляет -semantic-configuration в качестве суффикса. Это гарантирует, что семантическая конфигурация однозначно связана с соответствующим индексом и соответствует согласованному соглашению об именовании.

Почему все ресурсы создаются в восточной части США 2?

В примере используются модели gpt-4o-mini и text-embedding-ada-002 , оба из которых доступны с типом развертывания Standard в восточной части США 2. Эти модели также выбираются, так как они не планируются на снятие с эксплуатации в ближайшее время, обеспечивая стабильность при развертывании. Доступность модели и типы развертывания могут различаться по регионам, поэтому выбрана Восточный США 2, чтобы убедиться, что пример работает сразу. Если вы хотите использовать другой регион или модели, обязательно выберите модели, доступные для одного типа развертывания в одном регионе. При выборе собственных моделей проверьте их доступность и даты выхода на пенсию, чтобы избежать сбоев.

Можно ли использовать собственные модели OpenAI вместо тех, которые предоставляются Azure?

Это решение предназначено для работы с Azure OpenAI Service. Хотя вы можете изменить код для использования других моделей OpenAI, вы потеряете интегрированные функции безопасности, поддержку управляемых удостоверений и простую интеграцию с Azure AI Search, которую предоставляет это решение.

Как улучшить качество ответов?

Вы можете улучшить качество отклика, выполнив следующие действия.

  • Отправка более качественных, более релевантных документов.
  • Настройка стратегий разбиения на части в конвейере индексирования Azure AI Search. Однако вы не можете настроить блоки с помощью встроенной векторизации, показанной в этом руководстве.
  • Экспериментирование с различными шаблонами запросов в коде приложения.
  • Тонкая настройка поиска с другими характеристиками в источнике данных type: "azure_search.
  • Использование более специализированных Azure моделей OpenAI для конкретного домена.

Дополнительные ресурсы

  • Last updated on