Руководство по созданию приложения для получения дополненного поколения в Службе приложений Azure с помощью Azure OpenAI и поиска ИИ Azure (FastAPI)

2025-05-20

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

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

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

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

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

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

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

Предпосылки

Учетная запись Azure с активной подпиской — создание учетной записи бесплатно.
Учетная запись GitHub, необходимая для использования GitHub Codespaces - Подробнее о пространствах кода GitHub.

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

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

Перейдите в репозиторий GitHub по адресу https://github.com/Azure-Samples/app-service-rag-openai-ai-search-python.
Нажмите кнопку "Код" , перейдите на вкладку "Пространства кода" и нажмите кнопку "Создать пространство кода" на главном.
Подождите несколько минут, пока пространство кода инициализируется. После готовности вы увидите полностью настроенную среду VS Code в браузере.

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

В терминале войдите в Azure с помощью Интерфейса командной строки разработчика Azure:
```
azd auth login
```
Следуйте инструкциям, чтобы завершить процесс проверки подлинности.
Подготовьте ресурсы Azure с помощью шаблона AZD:
```
azd provision
```

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

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

Дождитесь завершения развертывания. Этот процесс:
- Создайте все необходимые ресурсы Azure.
- Разверните приложение Blazor в Службе приложений Azure.
- Настройте безопасную проверку подлинности между службами с помощью управляемых удостоверений.
- Настройте необходимые назначения ролей для безопасного доступа между службами.
Замечание

Дополнительные сведения о работе управляемых удостоверений см. в статье "Что такое управляемые удостоверения для ресурсов Azure" и "Как использовать управляемые удостоверения с службой приложений".
После успешного развертывания вы увидите URL-адрес развернутого приложения. Запишите этот URL-адрес, но еще не получите доступ к нему, так как вам по-прежнему нужно настроить индекс поиска.

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

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

На портале Azure перейдите к учетной записи хранения, созданной развертыванием. Имя начинается с имени среды, предоставленного ранее.
Выберите контейнеры из меню навигации слева и откройте контейнер документов .
Отправьте примеры документов, нажав кнопку "Отправить". Вы можете использовать примеры документов из sample-docs папки в репозитории или собственные PDF-файлы, Word или текстовые файлы.
Перейдите в службу поиска ИИ Azure на портале Azure.
Выберите "Импорт и векторизация данных ", чтобы начать процесс создания индекса поиска.
На шаге подключения к данным :
- Выберите хранилище BLOB-объектов Azure в качестве источника данных.
- Выберите RAG.
- Выберите учетную запись хранения и контейнер документов .
- Убедитесь, что выбрана проверка подлинности с управляемым удостоверением.
- Нажмите кнопку Далее.
На шаге векторизации текста выполните следующие действия:
- Выберите службу Azure OpenAI.
- Выберите text-embedding-ada-002 в качестве модели внедрения. Шаблон AZD уже развернул эту модель.
- Выберите назначенное системой удостоверение для проверки подлинности .
- Установите флажок признания для учета дополнительных затрат.
- Нажмите кнопку Далее.
Подсказка

Дополнительные сведения о векторном поиске в Azure ИИ и внедрении текста в Azure OpenAI.
На шаге векторизация и обогащение изображений:
- Сохраните параметры по умолчанию.
- Нажмите кнопку Далее.
На шаге "Дополнительные параметры" выполните следующие действия.
- Убедитесь, что выбран семантический ранжировщик.
- (Необязательно) Выберите расписание индексирования. Это полезно, если вы хотите регулярно обновлять индекс с помощью последних изменений в файле.
- Нажмите кнопку Далее.
На шаге проверки и создания :
- Скопируйте значение префикса имени объектов . Это имя индекса поиска.
- Нажмите кнопку "Создать", чтобы запустить процесс индексирования.
Дождитесь завершения процесса индексирования. Это может занять несколько минут в зависимости от размера и количества документов.
Чтобы проверить импорт данных, нажмите кнопку "Начать поиск " и попробуйте выполнить поисковый запрос, например "Расскажите мне о вашей компании".
Вернитесь в терминал Codespace, задайте имя индекса поиска в качестве переменной среды AZD:
```
azd env set SEARCH_INDEX_NAME <your-search-index-name>
```
Замените <your-search-index-name> на имя индекса, которое вы скопировали ранее. AZD использует эту переменную в последующих развертываниях для задания параметра приложения службы приложений.

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

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

В терминале Codespace получите значения среды AZD:
```
azd env get-values
```
Откройте .env. Используя выходные данные терминала, обновите следующие значения в соответствующих заполнителях <input-manually-for-local-testing>:
- AZURE_OPENAI_ENDPOINT
- AZURE_SEARCH_SERVICE_URL
- AZURE_SEARCH_INDEX_NAME
Войдите в Azure с помощью Azure CLI:
```
az login
```
Это позволяет клиентской библиотеке удостоверений Azure в примере кода получать маркер проверки подлинности для пользователя, вошедшего в систему.
Запустите приложение локально:
```
pip install -r requirements.txt
uvicorn main:app
```
Когда вы увидите Ваше приложение, запущенное на порту 8000, доступно в выводе, выберите "Открыть в браузере".
Попробуйте задать несколько вопросов в интерфейсе чата. Если вы получите ответ, приложение успешно подключается к ресурсу Azure OpenAI.
Остановите сервер разработки с помощью CTRL+C.
Примените новую SEARCH_INDEX_NAME конфигурацию в Azure и разверните пример кода приложения:
```
azd up
```

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

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

Откройте URL-адрес приложения, предоставленный в конце развертывания.
Вы увидите интерфейс чата, где можно ввести вопросы о содержимом отправленных документов.
Попробуйте задать вопросы, относящиеся к содержимому документов. Например, если вы отправили документы в папку sample-docs , попробуйте выполнить следующие вопросы:
- Как Contoso использует персональные данные?
- Как подать заявление о гарантии?
Обратите внимание на то, как ответы включают ссылки на исходные документы. Эти ссылки помогают пользователям проверить точность информации и найти дополнительные сведения в исходном материале.
Проверьте возможности гибридного поиска, задав вопросы, которые могут быть полезными при использовании различных подходов к поиску.
- Вопросы с определенной терминологией (хорошо подходит для поиска ключевых слов).
- Вопросы о понятиях, которые могут быть описаны с помощью различных терминов (хорошо подходит для векторного поиска).
- Сложные вопросы, требующие понимания контекста (хорошо подходит для семантического ранжирования).

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

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

azd down --purge

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

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

Как пример кода извлекает ссылки из завершения чата Azure OpenAI?
Каковы преимущества использования управляемых удостоверений в этом решении?
Как назначаемое системой управляемое удостоверение используется в этой архитектуре и образце приложения?
Как гибридный поиск с семантическим рангером реализован в примере приложения?
Почему все ресурсы создаются в восточной части США 2?
Можно ли использовать собственные модели OpenAI вместо тех, которые предоставлены Azure?
Как улучшить качество ответов?

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

В примере извлекаются цитаты с использованием источника данных и 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 без управления секретами. Этот подход следует принципам безопасности нулевого доверия и снижает риск воздействия учетных данных.

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

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

В примере приложения FastAPI пакеты SDK Azure используют это управляемое удостоверение для безопасной проверки подлинности, поэтому вам не нужно хранить учетные данные или секреты в любом месте. Например, 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, для проверки подлинности указывается управляемое удостоверение.

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, следуя рекомендациям по обеспечению безопасности Нулевого доверия. Дополнительные сведения о DefaultAzureCredential и клиентской библиотеке удостоверений Azure для 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 в качестве суффикса. Это гарантирует, что семантическая конфигурация однозначно связана с соответствующим индексом и соответствует согласованному соглашению об именовании.

Почему все ресурсы создаются в регионе East US 2?

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

Доступность модели: модели Azure OpenAI Service
Даты снятия моделей с обслуживания: устаревание и снятие моделей Azure OpenAI Service с обслуживания.

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

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

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

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

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