Python 项目创建+依赖管理+版本控制

给你一套最简单、最稳定、不踩坑的标准流程，直接跟着做就能用

一、创建项目（标准结构）

1. 新建项目文件夹

ocr_project/
├── app/
│   ├── __init__.py
│   ├── ocr_engine.py    # OCR核心类
│   └── utils.py         # 图像处理工具
├── models/              # 模型目录（可选）
├── images/              # 测试图片
├── requirements.txt      # 固定依赖 ✅
├── Dockerfile           # 你要的镜像
├── docker-compose.yml
├── .dockerignore
└── main.py              # 启动入口

 

二、创建虚拟环境（必须！）

Windows

python -m venv .venv
.venv\Scripts\activate

Linux/Mac

python3 -m venv .venv
source .venv/bin/activate

激活后，前面会出现 (.venv)

 

三、依赖管理（最重要！固定版本）

1. 创建 requirements.txt

# 核心框架
paddlepaddle==3.0.0
paddleocr==2.9.1

# 图像处理
opencv-python-headless==4.10.0.84
pymupdf==1.27.2
numpy==1.26.4
pillow==10.4.0

# 日志/工具
python-dotenv==1.0.1

 

2. 安装依赖

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 导出当前环境所有依赖

pip freeze > requirements.txt

这样能保证：本地、服务器、Docker 环境完全一致！

四、项目入口文件：main.py

from src.ocr import run_ocr

if __name__ == "__main__":
    result = run_ocr("test.jpg")
    for text in result:
       (text)

app/ocr_engine.py（OCR 核心）

import os
import cv2
import numpy as np
from paddleocr import PaddleOCR

os.environ["PADDLE_PDX_DISABLE"] = "1"
os.environ["PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK"] = "1"

class OCREngine:
    def __init__(self):
        self.ocr = PaddleOCR(
            lang="ch",
            use_gpu=False,
            show_log=False,
            use_angle_cls=True,
            ocr_version="PP-OCRv4",
            det_limit_side_len=6000
        )

    def predict(self, img_path):
        img = cv2.imread(img_path)
        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
        result = self.ocr.ocr(img, cls=True)
        texts = [line[1][0] for line in result[0]]
        return texts

五、如何创建虚拟环境（本地开发）

# 创建
python -m venv .venv

# 激活
# Windows
.venv\Scripts\activate
# Mac/Linux
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

六、docker 开发

.dockerignore

__pycache__
*.pyc
images/*
models/*
*.md

Dockerfile

FROM paddlepaddle/paddle:3.0.0

WORKDIR /app

# 系统依赖
RUN sed -i 's|deb.debian.org|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list && \
    sed -i 's|security.debian.org|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list && \
    apt-get update && \
    apt-get install -y --no-install-recommends \
    libgl1-mesa-glx libglib2.0-0 libsm6 libxrender1 libxext6 && \
    rm -rf /var/lib/apt/lists/*

# 安装固定依赖
COPY requirements.txt .
RUN pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 拷贝代码
COPY . .

# 运行
CMD ["/bin/bash"]
#CMD ["python", "main.py"]

docker-compose.yml

version: '3.8'

services:
  paddle-ocr4:
    build: .
    container_name: paddle-ocr4
    volumes:
      - ./:/app  # 本地目录 ↔ 容器 /app 自动同步
    stdin_open: true
    tty: true
    working_dir: /app

 

 

七、Git 版本管理

1. 创建 .gitignore

.venv/
__pycache__/
*.pyc
*.pyo
*.pyd
*.log
*.jpg
*.png
*.pdf
models/
build/
dist/
*.egg-info/

2. 初始化 Git

git init
git add .
git commit -m "init: paddleocr project"

3. 查看版本

git log

八、项目运行

python main.py