ITADN
Azure-Samples/rag-postgres-openai-python
代码 动态 Issues45 合并请求183 版本
Azure-Samples/rag-postgres-openai-python · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

基于 PostgreSQL 的 RAG

Open in GitHub Codespaces Open in Dev Containers

本项目创建一个基于 Web 的聊天应用程序，其 API 后端可以使用 OpenAI 聊天模型来回答有关 PostgreSQL 数据库表中行的问题。前端使用 React 和 FluentUI 构建，后端使用 Python 和 FastAPI 编写。

本项目旨在使用 Azure Developer CLI 部署到 Azure，将应用程序托管在 Azure Container Apps 上，数据库部署在 Azure PostgreSQL Flexible Server 中，模型部署在 Azure OpenAI 中。

功能

本项目提供以下功能：

  • 在 PostgreSQL 数据库表上进行混合搜索，使用 pgvector 扩展 进行向量搜索，并结合 全文搜索，使用 RRF（倒数排名融合）组合结果。
  • 使用 OpenAI 函数调用，可选地将用户查询转换为查询过滤条件，例如将“价格低于 30 美元的攀岩装备？”转换为“WHERE price < 30”。
  • 使用 OpenAI 嵌入 API 将用户查询转换为向量。

Screenshot of chat app with question about climbing gear

架构图

已部署的应用程序使用用户分配的托管标识来对 Azure 服务进行身份验证，并将日志存储在 Log Analytics 中。

Architecture diagram: Azure Container Apps, Azure Container Registry, Managed Identity, Azure OpenAI, Azure Database for PostgreSQL

入门指南

使用此模板开始有几种选择。 最快的入门方式是使用 GitHub Codespaces，因为它会为你设置好所有工具，但你也可以在本地进行设置。

GitHub Codespaces

你可以使用 GitHub Codespaces 以虚拟方式运行此模板。该按钮将在你的浏览器中打开一个基于 Web 的 VS Code 实例：

  1. 打开模板（这可能需要几分钟）：

    Open in GitHub Codespaces

  2. 打开一个终端窗口

  3. 继续执行部署步骤

VS Code Dev Containers

一个相关的选项是 VS Code Dev Containers，它将使用Dev Containers 扩展在本地 VS Code 中打开该项目：

  1. 启动 Docker Desktop（如果尚未安装，请先安装）

  2. 打开项目：

    Open in Dev Containers

  3. 在打开的 VS Code 窗口中，当项目文件显示出来时（这可能需要几分钟），打开一个终端窗口。

  4. 继续执行部署步骤

本地环境

  1. 确保已安装以下工具：

  2. 下载项目代码：

    azd init -t rag-postgres-openai-python

  3. 打开项目文件夹

  4. 安装所需的 Python 包和后端应用程序：

    pip install -r requirements-dev.txt
pip install -e src/backend

  5. 继续执行部署步骤

部署

一旦你在 Codespaces、Dev Containers 或本地 中打开了该项目，就可以将其部署到 Azure。

  1. 登录你的 Azure 账户：

    azd auth login

对于 GitHub Codespaces 用户，如果上一条命令失败，请尝试：

 azd auth login --use-device-code
 ```

2. 创建新的 azd 环境：

 ```shell
 azd env new
 ```

这将在您的项目中 `.azure/` 下创建一个文件夹，用于存储此部署的配置。如有需要，您可以拥有多个 azd 环境。

3. （可选）如果您希望自定义部署以 [使用现有的 Azure 资源](docs/deploy_existing.md)，您可以现在设置这些值。

4. 配置资源并部署代码：

 ```shell
 azd up
 ```

系统将要求你选择两个位置，首先为大部分资源（Container Apps、PostgreSQL）选择一个区域，然后为 Azure OpenAI 模型专门选择一个区域。本项目使用 gpt-4o-mini 和 text-embedding-3-large 模型，这些模型可能并非在所有 Azure 区域均可用。请查阅[最新的区域可用性](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability)并据此选择区域。

## 本地开发

### 设置环境文件

由于本地应用使用 OpenAI 模型，为了获得最佳体验，你应首先进行部署。

1. 将 `.env.sample` 复制为 `.env` 文件。
2. 若要使用 Azure OpenAI，请将 `OPENAI_CHAT_HOST` 和 `OPENAI_EMBED_HOST` 设置为 "azure"。然后根据已部署的值填写 `AZURE_OPENAI_ENDPOINT` 和 `AZURE_OPENAI_CHAT_DEPLOYMENT` 的值。你可以使用以下命令显示这些值：

 ```shell
 azd env get-values
 ```

3. 若要使用 OpenAI.com OpenAI，请将 `OPENAI_CHAT_HOST` 和 `OPENAI_EMBED_HOST` 设置为 "openai"。然后填写 `OPENAICOM_KEY` 的值。
4. 若要使用 Ollama，请将 `OPENAI_CHAT_HOST` 设置为 "ollama"。然后更新 `OLLAMA_ENDPOINT` 和 `OLLAMA_CHAT_MODEL` 的值，以匹配您的本地配置和模型。我们建议聊天模型使用 "llama3.1"，因为它支持函数调用；嵌入模型使用 "nomic-embed-text"，因为示例数据已使用该模型进行嵌入。如果您无法使用函数调用，请在开发者设置中关闭 "Advanced flow"。如果您无法使用嵌入模型，请在开发者设置中关闭向量搜索。

### 运行前端和后端

1. 运行以下命令，将 Web 应用安装为本地包（名为 `fastapi_app`），设置本地数据库，并用测试数据进行初始化：

 ```bash
 python -m pip install -r src/backend/requirements.txt
 python -m pip install -e src/backend
 python ./src/backend/fastapi_app/setup_postgres_database.py
 python ./src/backend/fastapi_app/setup_postgres_seeddata.py
 ```

2. 构建前端：

 ```bash
 cd src/frontend
 npm install
 npm run build
 cd ../../
 ```

在运行后端之前，必须先对静态资源进行初始构建，因为后端会从 `src/static` 目录提供静态文件。

3. 运行 FastAPI 后端（支持热重载）。这应从项目根目录运行：

 ```shell
 python -m uvicorn fastapi_app:create_app --factory --reload
 ```

或者你可以在 VS Code 的“运行和调试”菜单中运行“Backend”。

4. 运行前端（支持热重载）：

 ```bash
 cd src/frontend
 npm run dev
 ```

或者，你可以在 VS Code 的“运行和调试”菜单中运行“Frontend”或“Frontend & Backend”。

5. 在浏览器中打开 `http://localhost:5173/`，你将看到前端界面。

## 成本

价格可能因区域和使用情况而异。无法估算确切成本。
你可以尝试使用 [Azure 定价计算器](https://azure.microsoft.com/pricing/calculator/) 来估算以下资源的费用：

* Azure Container Apps：按需付费层。费用基于使用的 vCPU 和内存。[定价](https://azure.microsoft.com/pricing/details/container-apps/)
* Azure OpenAI：标准层，GPT 和 Ada 模型。按每 1K 使用的 token 计费，且每个问题至少使用 1K token。[定价](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/)
* Azure PostgreSQL Flexible Server：突发性能层，1 个 CPU 核心，32GB 存储。按小时计费。[定价](https://azure.microsoft.com/pricing/details/postgresql/flexible-server/)
* Azure Monitor：按需付费层。费用基于摄取的数据量。[定价](https://azure.microsoft.com/pricing/details/monitor/)

## 安全指南

此模板使用 [托管标识](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) 来对所使用的 Azure 服务（Azure OpenAI、Azure PostgreSQL Flexible Server）进行身份验证。

此外，我们添加了一个 [GitHub Action](https://github.com/microsoft/security-devops-action)，用于扫描基础设施即代码文件并生成包含任何检测到的问题的报告。为了确保在你自己的仓库中持续遵循最佳实践，我们建议任何基于我们的模板创建解决方案的人都确保启用 [Github 秘密扫描](https://docs.github.com/code-security/secret-scanning/about-secret-scanning) 设置。

## 指南

更多文档可在 `docs/` 文件夹中找到：

* [了解 RAG 流程](docs/rag_flow.md)
* [自定义数据](docs/customize_data.md)
* [使用现有资源部署](docs/deploy_existing.md)
* [使用 Entra 身份验证与 PostgreSQL 工具](docs/using_entra_auth.md)
* [使用 Azure Monitor 进行监控](docs/monitoring.md)
* [负载测试](docs/loadtesting.md)
* [质量评估](docs/evaluation.md)
* [安全性评估](docs/safety_evaluation.md)

如有任何问题或故障，请在问题跟踪器中发布。

## 资源

* [RAGHack 直播：使用 PostgreSQL 构建 RAG](https://www.youtube.com/watch?v=Dk65oQjYAfo)
* [使用 Azure AI Search + Python 进行 RAG 聊天](https://github.com/Azure-Samples/azure-search-openai-demo/)
* [开发使用 Azure AI 服务的 Python 应用程序](https://learn.microsoft.com/azure/developer/python/azure-ai-for-python-developers)