Azure Search OpenAI Demo开发环境配置：VS Code与Docker-优快云博客

Azure Search OpenAI Demo开发环境配置：VS Code与Docker

【免费下载链接】azure-search-openai-demo A sample app for the Retrieval-Augmented Generation pattern running in Azure, using Azure AI Search for retrieval and Azure OpenAI large language models to power ChatGPT-style and Q&A experiences. 项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo

引言：告别环境配置痛点

你是否曾因复杂的开发环境配置而推迟Azure Search OpenAI Demo项目的启动？是否在VS Code与Docker的集成中遇到过调试困难？本文将系统化解决这些问题，通过10个步骤完成从环境准备到容器化部署的全流程配置，确保你在30分钟内拥有可立即开发的标准化环境。读完本文后，你将掌握：

一键启动前后端热重载开发服务器的技巧
Docker容器化部署的最佳实践
VS Code调试配置的高级用法
本地LLM替代方案的成本优化策略

环境准备：系统要求与依赖安装

基础环境要求

软件/工具	最低版本	推荐版本	作用
Python	3.8	3.11	后端运行环境
Node.js	14.x	18.x	前端构建工具
Docker Desktop	20.10	25.0.0+	容器化部署环境
VS Code	1.70.0	1.85.0+	集成开发环境
Git	2.30.0	2.40.0+	版本控制

必装依赖安装命令

# Ubuntu/Debian系统
sudo apt update && sudo apt install -y python3 python3-venv nodejs npm docker.io
# macOS (使用Homebrew)
brew install python node docker git
# Windows (使用Chocolatey)
choco install python nodejs-lts docker-desktop git

注意：安装完成后需重启系统，确保Docker服务正常运行。在Windows系统中，需启用WSL2功能以获得最佳Docker性能。

VS Code开发环境深度配置

扩展ID	功能描述	必要性
ms-python.python	Python语言支持与调试	必需
ms-azuretools.vscode-docker	Docker文件支持与容器管理	必需
dbaeumer.vscode-eslint	JavaScript/TypeScript代码检查	推荐
ms-vscode.vscode-typescript-next	TypeScript最新特性支持	可选
humao.rest-client	HTTP请求测试工具	推荐

任务配置全解析（tasks.json）

VS Code的任务系统可实现前后端服务一键启动。项目内置的.vscode/tasks.json定义了四个关键任务：

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Start App",
            "type": "shell",
            "command": "${workspaceFolder}/app/start.sh",
            "windows": {
                "command": "pwsh ${workspaceFolder}/app/start.ps1"
            }
        },
        {
            "label": "Development",
            "dependsOn": ["Frontend: npm run dev", "Backend: quart run"]
        },
        // 更多任务配置...
    ]
}

关键任务说明：

Start App：执行start.sh脚本，创建虚拟环境并启动完整应用
Development：并行启动前后端热重载服务
Frontend: npm run dev：启动Vite开发服务器（端口5173）
Backend: quart run：启动Python后端服务（端口50505）

启动方式：Ctrl+Shift+B (运行生成任务) → 选择"Development"

调试配置实战（launch.json）

复合调试配置允许同时调试前后端代码：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Backend (Python)",
            "type": "debugpy",
            "request": "launch",
            "module": "quart",
            "args": ["run", "--no-reload", "-p", "50505"],
            "cwd": "${workspaceFolder}/app/backend"
        },
        {
            "name": "Frontend",
            "type": "node-terminal",
            "request": "launch",
            "command": "npm run dev",
            "cwd": "${workspaceFolder}/app/frontend"
        }
    ],
    "compounds": [
        {
            "name": "Frontend & Backend",
            "configurations": ["Backend (Python)", "Frontend"]
        }
    ]
}

使用方法：

打开调试面板（Ctrl+Shift+D）
选择"Frontend & Backend"配置
点击启动按钮（F5），自动附加到两个进程

Docker容器化部署全攻略

Dockerfile深度解析

项目后端Dockerfile位于app/backend/Dockerfile，采用多阶段构建优化：

FROM python:3.11-bullseye AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /app/wheels -r requirements.txt

FROM python:3.11-slim-bullseye
WORKDIR /app
COPY --from=builder /app/wheels /wheels
RUN pip install --no-cache /wheels/*
COPY . .
CMD ["python3", "-m", "gunicorn", "-b", "0.0.0.0:8000", "main:app"]

优化点说明：

采用wheels缓存减少重复依赖安装
使用slim基础镜像减小最终镜像体积（约300MB→150MB）
Gunicorn作为生产级WSGI服务器，性能优于开发服务器

构建与运行命令速查表

操作	命令	说明
构建镜像	`docker build -t azure-search-openai:latest ./app/backend`	从后端目录构建
运行容器	`docker run -p 8000:8000 -e OPENAI_API_KEY=xxx azure-search-openai`	映射端口并传环境变量
后台运行	`docker run -d --name demo-app -p 8000:8000 azure-search-openai`	命名容器并后台运行
查看日志	`docker logs -f demo-app`	实时查看应用输出
停止容器	`docker stop demo-app && docker rm demo-app`	停止并删除容器

多容器开发环境配置（docker-compose示例）

虽然项目未提供官方docker-compose.yml，但可创建以下配置实现完整开发环境：

version: '3.8'
services:
  backend:
    build: ./app/backend
    ports:
      - "50505:50505"
    volumes:
      - ./app/backend:/app
    command: python -m quart run --reload -p 50505
    environment:
      - QUART_ENV=development
      
  frontend:
    build: ./app/frontend
    ports:
      - "5173:5173"
    volumes:
      - ./app/frontend:/app
      - /app/node_modules
    command: npm run dev

启动命令：docker-compose up -d，访问http://localhost:5173即可开发。

本地开发与调试高级技巧

热重载工作流优化

通过VS Code任务实现"保存即更新"的开发体验：

启动"Development"任务（Ctrl+Shift+B）
前端修改：Vite HMR实时更新（无需刷新浏览器）
后端修改：Quart自动重启（断点会临时失效需重新附加）

性能优化：在.vscode/settings.json中添加：

{
    "files.watcherExclude": {
        "**/.venv/**": true,
        "**/node_modules/**": true
    }
}

本地LLM替代方案配置

为降低开发成本，可使用Ollama运行本地模型替代Azure OpenAI：

# 安装Ollama并拉取模型
curl https://ollama.ai/install.sh | sh
ollama pull llama3.1:8b

# 配置环境变量
azd env set OPENAI_HOST local
azd env set OPENAI_BASE_URL http://host.docker.internal:11434/v1
azd env set AZURE_OPENAI_CHATGPT_MODEL llama3.1:8b
azd env set USE_VECTORS false

限制：本地模型不支持函数调用和向量搜索，仅用于基础问答功能测试。

调试常见问题解决

问题现象	可能原因	解决方案
后端启动报端口占用	50505端口被占用	修改tasks.json中的端口号，如改为50506
前端无法连接后端API	跨域配置问题	检查vite.config.ts中的proxy配置
Docker构建失败	依赖安装错误	执行`docker build --no-cache`强制重新构建
断点不命中	调试配置错误	确认launch.json中的cwd路径正确

总结与下一步行动

本文系统讲解了Azure Search OpenAI Demo的开发环境配置，包括VS Code任务调试配置、Docker容器化部署、热重载工作流优化等关键技能。通过这些步骤，你已拥有与生产环境一致的本地开发系统，可高效进行功能开发和问题排查。

立即行动：

按照步骤配置开发环境
尝试修改app/frontend/src/pages/ChatPage.tsx添加自定义组件
使用Docker构建镜像并测试部署
收藏本文以备后续环境迁移参考

下期预告：将深入探讨Azure Search OpenAI Demo的自定义数据接入方案，包括PDF文档解析、向量存储优化和多源数据融合技术。保持关注，持续提升你的RAG应用开发能力！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Azure Search OpenAI Demo开发环境配置：VS Code与Docker