cyber-practice

网络安全社会实践环境准备说明

本仓库用于准备网络安全实训开发环境，包含邮件附件解析、OCR、API 连通性和 GraphRAG 的基础测试脚本。推荐统一使用 Python 3.11，并在同一个 .venv 中安装依赖。

当前已验证的主要版本：

Python 3.11.9
paddlepaddle==3.3.1
paddleocr==3.7.0
paddlex==3.7.2
graphrag==2.7.2

注意：Windows CPU 环境下，PaddleOCR 3.x 初始化时需要设置 enable_mkldnn=False，测试脚本已经处理好。

一、开发工具

Windows

安装 Python 3.11 和 Git：

winget install Python.Python.3.11
winget install Git.Git

重新打开 PowerShell，检查版本：

python --version
pip --version
git --version

进入项目目录，创建并激活虚拟环境：

cd cyber-practice
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1

如果 PowerShell 不允许执行激活脚本，先运行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

macOS

安装 Homebrew 时优先使用中国科大镜像脚本：

/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"

如果已经安装过 Homebrew，可以把源切到中国科大：

git -C "$(brew --repo)" remote set-url origin https://mirrors.ustc.edu.cn/brew.git
git -C "$(brew --repo homebrew/core)" remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git
git -C "$(brew --repo homebrew/cask)" remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles' >> ~/.zprofile
source ~/.zprofile
brew update

安装 Python 3.11、Git 和 VS Code：

brew install python@3.11 git
brew install --cask visual-studio-code

进入项目目录，创建并激活虚拟环境：

cd cyber-practice
python3.11 -m venv .venv
source .venv/bin/activate

二、库依赖

先安装通用 CPU 依赖：

Windows

python -m pip install -U pip setuptools wheel
python -m pip install -r requirements-cpu.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

macOS

python -m pip install -U pip setuptools wheel
python -m pip install -r requirements-cpu.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

如果 macOS 安装 paddlepaddle==3.3.1 时提示没有匹配版本，到 Paddle 官方安装选择器按 macOS、CPU、Python 版本生成命令：

https://www.paddlepaddle.org.cn/install/quick

GPU 说明

如果要安装 GPU 版 PaddlePaddle，先确认机器有 NVIDIA 显卡：

nvidia-smi

然后到 Paddle 官方安装选择器，根据系统、Python、CUDA 版本生成命令：

https://www.paddlepaddle.org.cn/install/quick

依赖文件用途：

• requirements-cpu.txt：通用 CPU 环境。
• requirements-graphrag.txt：GraphRAG 可选依赖。
• requirements-gpu.txt：GPU 环境参考，GPU 版 PaddlePaddle 需要按 CUDA 版本单独安装。
• requirements-lock.txt：当前机器完整冻结依赖，仅用于复现排查。

GraphRAG 可选依赖

需要测试 GraphRAG 的时候，在同一个 .venv 中继续安装。Windows 和 macOS 都执行下面命令：

python -m pip install -r requirements-graphrag.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

本仓库固定 graphrag==2.7.2。3.x 版本依赖更新较多，Windows 上可能需要额外编译环境，暂不作为默认版本。

三、测试

OCR 测试

仓库已包含 tests/test_ocr.png，可以直接运行：

python tests/ocr_test.py

成功时会看到类似输出：

paddle version: 3.3.1
cuda compiled: False
OCR_RESULT_BEGIN
网络安全 实训 OCR 123    0.95xx
Email Attachment OCR Test    0.99xx
OCR_RESULT_END

LLM API 测试

复制环境变量示例文件，并填写自己的 API Key：

copy .env.example .env

运行 API 连通性测试：

python tests/api_test.py

如果没有配置 API Key，该测试会提示缺少 key。

GraphRAG 测试

安装 requirements-graphrag.txt 后运行：

python tests/graphrag_test.py

该脚本只测试 graphrag init 和默认配置生成，不会调用大模型 API，也不会消耗额度。测试输出会写入 test_outputs/graphrag_smoke/，该目录不会提交到仓库。

如果后续要真正运行 graphrag index 或 graphrag query，需要配置可用的 GRAPHRAG_API_KEY，并根据所用模型修改 GraphRAG 配置。

一键测试

运行当前的 OCR 和 API 测试：

python tests/run_all_tests.py

GraphRAG 测试单独运行，避免没有安装可选依赖时影响基础环境检查。

API Key 获取入口

• DeepSeek API 平台：https://platform.deepseek.com/
• 智谱 GLM 开放平台：https://open.bigmodel.cn/