Python 包的依賴管理，有解了！詳情 - python,開發語言,python,Python,虛擬環境,JavaScript,前端開發小題大作博客

項目概述

JoyAgent-JDGenie 是一個多模塊Python項目，包含兩個主要的Python子項目：

項目結構

joyagent-jdgenie/
├── genie-client/          # FastAPI MCP客户端
│   ├── pyproject.toml     # 依賴聲明文件
│   └── uv.lock           # 依賴鎖定文件
├── genie-tool/           # 工具服務
│   ├── pyproject.toml    # 依賴聲明文件
│   └── uv.lock          # 依賴鎖定文件
├── genie-backend/        # Java後端
└── ui/                  # 前端界面

Python版本要求

genie-client: Python 3.10 - 3.13
genie-tool: Python 3.11 - 3.13

依賴管理工具介紹

為什麼使用 uv？

本項目使用 uv 作為依賴管理工具，這是一個用Rust編寫的現代化Python包管理器，相比傳統的 pip + virtualenv 方案有顯著優勢：

特性	uv	pip	poetry
安裝速度	極快（10-100x）	慢	中等
依賴解析	智能快速	簡單	較慢
虛擬環境管理	自動化	手動	自動化
跨平台一致性	優秀	一般	良好
鎖文件	uv.lock	❌	poetry.lock

uv vs pip 核心區別

# 傳統方式（pip）
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows
pip install -r requirements.txt

# 現代方式（uv）
uv sync  # 一條命令完成虛擬環境創建、依賴安裝

依賴文件詳解

1. pyproject.toml - 項目配置與依賴聲明

這是Python項目的標準配置文件（PEP 518/621規範），替代傳統的 setup.py 和 requirements.txt。

genie-client/pyproject.toml

[project]
name = "genie-client"
version = "0.1.0"
description = "FastAPI-based web service client for Model Context Protocol (MCP) servers"
readme = "README.md"
requires-python = ">=3.10,<=3.13"  # Python版本約束
dependencies = [
    "fastapi>=0.115.12",           # Web框架
    "mcp==1.9.4",                  # MCP協議庫
]

關鍵字段解析：

requires-python: 指定兼容的Python版本範圍
dependencies: 運行時必需的依賴包
使用語義化版本約束：

>=0.115.12: 最低版本要求
==1.9.4: 精確版本鎖定
^1.0.0: 兼容版本（poetry風格）

genie-tool/pyproject.toml

[project]
name = "python"
version = "0.1.0"
description = "Genie Tools"
readme = "README.md"
requires-python = ">=3.11,<4.0"
dependencies = [
    "aiosqlite>=0.21.0",           # 異步SQLite
    "asyncio>=4.0.0",              # 異步IO
    "beautifulsoup4>=4.13.4",      # HTML解析
    "elasticsearch==7.17.12",      # ES客户端
    "fastapi>=0.115.14",           # Web框架
    "pandas>=2.3.0",               # 數據分析
    "scikit-learn>=1.7.1",         # 機器學習
    "openai>=1.93.0",              # OpenAI SDK
    # ... 更多依賴
]

依賴分類：

Web框架: fastapi, uvicorn, sse-starlette
數據處理: pandas, numpy, openpyxl
AI/ML: openai, litellm, smolagents, scikit-learn
數據庫: aiosqlite, sqlmodel, elasticsearch, qdrant-client
工具庫: beautifulsoup4, jieba, loguru

2. uv.lock - 依賴鎖定文件

類似於 package-lock.json (npm) 或 poetry.lock，記錄所有依賴包的精確版本和哈希值。

作用：

確保團隊成員安裝完全相同的依賴版本
記錄傳遞依賴（dependencies of dependencies）
包含完整性校驗哈希
支持跨平台一致性

示例結構：

[[package]]
name = "fastapi"
version = "0.115.14"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "pydantic" },
    { name = "starlette" },
]
wheels = [
    { url = "...", hash = "sha256:..." },
]

3. 依賴文件對比表

文件類型	pyproject.toml	uv.lock	requirements.txt
用途	聲明直接依賴	鎖定所有依賴	聲明所有依賴
版本	範圍約束	精確版本	可精確可範圍
傳遞依賴	❌	✅	❌
可讀性	高	低（自動生成）	中等
推薦手動編輯	✅	❌	✅

PyCharm中的依賴安裝

方法一：使用PyCharm內置終端（推薦）

步驟1：安裝uv工具

在PyCharm內置終端中執行：

Windows:

# 使用pip安裝
pip install uv

# 或使用官方安裝腳本
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

# 使用pip安裝
pip install uv

# 或使用官方安裝腳本
curl -LsSf https://astral.sh/uv/install.sh | sh

步驟2：安裝項目依賴

# 進入genie-tool目錄
cd genie-tool

# 同步依賴（自動創建虛擬環境）
uv sync

# 激活虛擬環境
# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

uv sync 命令詳解：

自動讀取 pyproject.toml 和 uv.lock
自動創建 .venv 虛擬環境（如果不存在）
安裝所有鎖定版本的依賴
驗證依賴完整性

方法二：配置PyCharm解釋器（圖形界面）

步驟1：創建虛擬環境

打開 File → Settings → Project → Python Interpreter
點擊右上角 齒輪圖標 → Add Interpreter → Add Local Interpreter
選擇 Virtualenv Environment
設置：

Location: D:\work-src\joyagent-jdgenie\genie-tool\.venv
Base interpreter: 選擇 Python 3.11+
勾選 Inherit global site-packages（可選）

步驟2：安裝依賴

有兩種方式：

方式A：使用uv（推薦）
在PyCharm終端執行：

cd genie-tool
uv sync

方式B：使用pip
如果團隊不使用uv，可以導出requirements.txt：

# 從pyproject.toml生成requirements.txt
uv pip compile pyproject.toml -o requirements.txt

# 安裝依賴
pip install -r requirements.txt

方法三：使用PyCharm的uv插件（未來支持）

PyCharm 2024+ 版本可能原生支持uv，屆時可直接在項目配置中選擇uv作為包管理器。

驗證安裝

在PyCharm Python Console中測試：

import fastapi
import pandas as pd
import openai

print("依賴安裝成功！")
print(f"FastAPI version: {fastapi.__version__}")
print(f"Pandas version: {pd.__version__}")

Ubuntu系統中的依賴安裝

前置要求

# 更新系統
sudo apt update && sudo apt upgrade -y

# 安裝Python 3.11+（如果未安裝）
sudo apt install python3.11 python3.11-venv python3-pip -y

# 驗證Python版本
python3.11 --version

方法一：使用uv（推薦生產環境）

步驟1：安裝uv

# 方法A：使用官方安裝腳本（推薦）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方法B：使用pip
pip3 install uv

# 添加到PATH（如果使用官方腳本）
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 驗證安裝
uv --version

步驟2：克隆項目並安裝依賴

# 克隆項目
git clone <your-repo-url>
cd joyagent-jdgenie/genie-tool

# 同步依賴
uv sync

# 激活虛擬環境
source .venv/bin/activate

# 驗證環境
python --version
pip list

步驟3：初始化數據庫（首次運行）

python -m genie_tool.db.db_engine

步驟4：配置環境變量

# 複製環境變量模板
cp .env_template .env

# 編輯配置
nano .env  # 或使用 vim/vi

步驟5：啓動服務

# 使用uv運行
uv run python server.py

# 或激活虛擬環境後運行
source .venv/bin/activate
python server.py

方法二：使用傳統pip方式

步驟1：創建虛擬環境

cd genie-tool

# 創建虛擬環境
python3.11 -m venv .venv

# 激活虛擬環境
source .venv/bin/activate

步驟2：安裝依賴

# 方式A：使用uv導出requirements.txt
pip install uv
uv pip compile pyproject.toml -o requirements.txt
pip install -r requirements.txt

# 方式B：直接使用uv安裝（在虛擬環境中）
pip install uv
uv pip install -e .

系統服務配置（可選）

創建systemd服務自動啓動：

# 創建服務文件
sudo nano /etc/systemd/system/genie-tool.service

服務配置：

[Unit]
Description=Genie Tool Service
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/joyagent-jdgenie/genie-tool
Environment="PATH=/path/to/.venv/bin"
ExecStart=/path/to/.venv/bin/python server.py
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

啓動服務：

sudo systemctl daemon-reload
sudo systemctl enable genie-tool
sudo systemctl start genie-tool
sudo systemctl status genie-tool

Docker部署（推薦生產環境）

項目根目錄已包含 Dockerfile：

# 構建鏡像
docker build -t joyagent-genie:latest .

# 運行容器
docker run -d \
  --name genie-tool \
  -p 8000:8000 \
  -v $(pwd)/genie-tool/.env:/app/genie-tool/.env \
  joyagent-genie:latest

# 查看日誌
docker logs -f genie-tool

本文章為轉載內容，我們尊重原作者對文章享有的著作權。如有內容錯誤或侵權問題，歡迎原作者聯繫我們進行內容更正或刪除文章。

博客 / 詳情