基于Python和Docker的智能数据分析系统开发环境搭建

1. 项目概述

掌柜问数系统是一个基于自然语言处理技术的智能数据分析平台，能够理解用户用自然语言提出的数据查询需求，自动转换为SQL查询并返回结果。这个系统结合了现代AI技术和传统数据分析工具，为业务人员提供了更友好的数据交互方式。

在开始开发之前，我们需要搭建完整的开发环境。这个环境包含两个核心部分：Python虚拟环境用于运行业务代码，Docker容器化服务提供基础依赖支持。本文将详细介绍从零开始搭建这个开发环境的完整过程。

2. 开发环境准备

2.1 Python虚拟环境配置

Python虚拟环境是开发Python项目的标准实践，它可以隔离不同项目的依赖关系，避免版本冲突。对于掌柜问数系统，我们推荐使用Anaconda来管理虚拟环境，因为它提供了更完善的包管理功能。

2.1.1 创建虚拟环境

首先需要安装Anaconda或Miniconda。安装完成后，使用以下命令创建Python 3.12的虚拟环境：

bash复制conda create -n py312 python=3.12
conda activate py312

选择Python 3.12是因为它提供了最新的语言特性，同时本项目依赖的一些库（如LangChain）对Python版本有较高要求。虚拟环境创建完成后，每次开发时都需要先激活这个环境。

2.1.2 安装核心依赖

掌柜问数系统依赖多个开源库，涵盖了从Web框架到AI模型集成的各个方面。以下是完整的安装命令：

bash复制pip install asyncmy cryptography "elasticsearch[async]>=8,<9" fastapi[standard] huggingface-hub jieba langchain langchain-deepseek langchain-huggingface langgraph loguru omegaconf pyyaml qdrant-client sqlalchemy

这些依赖可以分为几大类：

1. Web框架：FastAPI提供高性能API服务
2. 数据库访问：SQLAlchemy+asyncmy实现异步MySQL操作
3. 向量检索：Qdrant客户端
4. 全文检索：Elasticsearch异步客户端
5. AI应用编排：LangChain和LangGraph
6. 辅助工具：日志、配置管理等

注意：安装过程中可能会遇到依赖冲突问题。如果出现这种情况，可以先安装主要依赖，再逐个安装其他依赖，或者使用conda来安装某些特定的包。

2.2 依赖包详细说明

了解每个依赖包的作用对于后续开发和问题排查非常重要。以下是主要依赖的详细说明：

在实际开发中，可能会根据具体需求调整这些依赖的版本。建议使用requirements.txt文件来固定版本，确保开发环境的一致性。

3. 容器化服务部署

3.1 Docker环境准备

掌柜问数系统依赖多个服务，包括MySQL、Qdrant、Elasticsearch等。使用Docker Compose可以方便地管理这些服务。首先确保系统已经安装了Docker和Docker Compose。

3.1.1 Docker安装

在CentOS上安装Docker的步骤如下：

bash复制sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io
sudo systemctl start docker
sudo systemctl enable docker

安装完成后，可以运行docker version验证安装是否成功。

3.1.2 Docker Compose安装

Docker Compose可以通过以下命令安装：

bash复制sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

3.2 服务配置与启动

3.2.1 docker-compose.yaml配置

掌柜问数系统需要以下服务：

1. MySQL：存储元数据和业务数据
2. Qdrant：向量数据库
3. Elasticsearch：全文检索引擎
4. Kibana：Elasticsearch可视化工具
5. Text Embedding Inference：文本向量化服务

一个典型的docker-compose.yaml配置如下：

yaml复制version: '3.8'

services:
  mysql:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: 123456
      MYSQL_DATABASE: metadata
    volumes:
      - mysql_data:/var/lib/mysql

  qdrant:
    image: qdrant/qdrant:v1.7.4
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_data:/qdrant/storage

  elasticsearch:
    image: elasticsearch:8.11.1
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"
    volumes:
      - es_data:/usr/share/elasticsearch/data

  kibana:
    image: kibana:8.11.1
    ports:
      - "5601:5601"
    depends_on:
      - elasticsearch

  tei:
    image: ghcr.io/huggingface/text-embeddings-inference:latest
    ports:
      - "8080:8080"
    environment:
      - MODEL_ID=BAAI/bge-small-zh-v1.5
    deploy:
      resources:
        limits:
          memory: 2G

volumes:
  mysql_data:
  qdrant_data:
  es_data:

3.2.2 服务启动与管理

将上述配置保存为docker-compose.yaml后，可以运行以下命令启动服务：

bash复制docker compose up -d

启动后，可以使用以下命令查看服务状态：

bash复制docker compose ps

如果需要停止服务，可以运行：

bash复制docker compose down

提示：第一次启动时，下载镜像可能需要较长时间。可以考虑预先下载镜像或使用本地镜像仓库加速这个过程。

4. 环境验证与测试

4.1 服务连通性测试

环境搭建完成后，需要验证各个服务是否正常运行。可以编写一个测试脚本来检查所有关键服务的连通性：

python复制# test_services.py
import asyncio
from sqlalchemy import text
from sqlalchemy.ext.asyncio import create_async_engine
from qdrant_client import QdrantClient
from elasticsearch import AsyncElasticsearch

async def test_mysql():
    try:
        engine = create_async_engine("mysql+asyncmy://root:123456@localhost:3306/metadata")
        async with engine.connect() as conn:
            result = await conn.execute(text("SELECT 1"))
            print("✅ MySQL连接成功")
    except Exception as e:
        print(f"❌ MySQL连接失败: {str(e)}")

def test_qdrant():
    try:
        client = QdrantClient("http://localhost:6333")
        collections = client.get_collections()
        print("✅ Qdrant连接成功")
    except Exception as e:
        print(f"❌ Qdrant连接失败: {str(e)}")

async def test_es():
    try:
        es = AsyncElasticsearch("http://localhost:9200")
        info = await es.info()
        print("✅ Elasticsearch连接成功")
    except Exception as e:
        print(f"❌ Elasticsearch连接失败: {str(e)}")

async def main():
    await test_mysql()
    test_qdrant()
    await test_es()

if __name__ == "__main__":
    asyncio.run(main())

运行这个脚本，应该看到所有服务的连接成功信息。如果有服务连接失败，需要根据错误信息进行排查。

4.2 性能基准测试

除了连通性测试外，还可以进行简单的性能测试：

1. MySQL性能测试：执行简单的查询，检查响应时间
2. Qdrant性能测试：创建集合并插入少量向量数据
3. Elasticsearch性能测试：创建索引并执行搜索

这些测试可以帮助确认服务是否配置正确，以及性能是否满足开发需求。

5. 常见问题与解决方案

5.1 依赖安装问题

问题1：安装某些依赖时出现版本冲突

解决方案：

1. 先安装主要依赖（如fastapi, sqlalchemy）
2. 再安装其他依赖，可以尝试指定版本号
3. 使用conda安装某些复杂的依赖

问题2：Python版本不兼容

解决方案：

1. 确认Python版本是3.12
2. 使用pyenv或conda管理多个Python版本
3. 检查依赖包的版本要求

5.2 Docker相关问题

问题1：端口冲突

解决方案：

1. 检查哪些端口被占用：netstat -tuln
2. 修改docker-compose.yaml中的端口映射
3. 停止占用端口的服务

问题2：容器启动失败

解决方案：

1. 查看容器日志：docker logs <container_name>
2. 检查资源限制（特别是内存）
3. 验证配置文件是否正确

5.3 服务连接问题

问题1：MySQL连接被拒绝

解决方案：

1. 检查MySQL是否正常运行
2. 验证用户名和密码
3. 检查网络连接和防火墙设置

问题2：Elasticsearch健康状态为red

解决方案：

1. 检查磁盘空间
2. 查看Elasticsearch日志
3. 可能需要重新创建索引

6. 开发环境优化建议

6.1 本地开发配置

1. 使用VS Code或PyCharm等现代IDE，配置Python解释器为创建的虚拟环境
2. 安装必要的插件：Python、Docker、数据库工具等
3. 配置代码格式化工具（black, isort）和linter（pylint）

6.2 性能优化

1. 为Docker分配足够的资源（CPU和内存）
2. 配置适当的数据库索引
3. 使用连接池管理数据库连接

6.3 调试技巧

1. 使用loguru进行结构化日志记录
2. 配置FastAPI的调试模式
3. 使用Postman或Swagger UI测试API

在实际开发中，可能会遇到各种环境相关的问题。建议保持开发环境的干净和一致性，定期更新依赖，并做好文档记录。这样可以帮助团队成员快速搭建开发环境，提高开发效率。