# python_offline_tool

**Repository Path**: allmyteacher/python_offline_tool

## Basic Information

- **Project Name**: python_offline_tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-13
- **Last Updated**: 2026-01-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 📚 文档中心

项目提供了Web文档服务器，方便浏览所有文档：

```bash
# 进入web目录
cd web

# 安装依赖（首次使用）
pip install -r requirements.txt

# 启动服务器
python app.py  # Windows: start.bat 或 Linux/Mac: bash start.sh
```

然后访问：**http://localhost:6666**

文档包括：
- 📖 [必读](docs/必读.md) - 项目概述与使用指南
- 💻 [代码说明](docs/代码说明.md) - 项目结构和代码逻辑
- 🚀 [全量安装](docs/全量安装.md) - 全量构建详细指南
- 🔄 [增量安装](docs/增量安装.md) - 增量更新详细指南
- 🔧 [Build专栏](docs/Build专栏.md) - Docker构建详细说明

---

## 最重要：
- source scripts/set_proxy.sh 127.0.0.1 7890
- echo $HTTP_PROXY
- bash scripts/docker_build.sh
- bash scripts/docker_export.sh

### 在离网环境:
 - 全量包:
   1. 将 ./output/python_packages_incremental_20260114_111229.tar.gz 复制到目标ARM64系统
   2. 解压: tar -xzf python_packages_incremental_20260114_111229.tar.gz -C /tmp/
   3. 运行: cd /tmp/incremental_package_* && ./install_incremental.sh
 - 增量包:
   1. 将 ./output/python3.12_arm64_ubuntu22_20260114_140955.tar.gz 复制到目标ARM64系统
   2. 解压: tar -xzf python3.12_arm64_ubuntu22_20260114_140955.tar.gz -C /opt/
   3. 运行: /opt/.export_temp/install.sh
   或者手动安装whl文件
   pip install --find-links "opt/.export_temp/packages" --no-index --no-cache-dir /opt/.export_temp/packages/*.whl
-----

麒麟 ARM64 离线 Agent 开发环境（Python 3.12 + 全量依赖）
> 专为内网、无网、高保密场景设计，支持一次性导入、离线部署、增量更新

Docker构建方案（Windows AMD64用户推荐），这样能在没有麒麟和arm芯片环境下，打包出来依赖。

如果你在 **Windows AMD64** 系统上，没有ARM64物理机，可以使用Docker在本地构建ARM64环境：

**快速开始（3步）：**
```bash
# 1. 构建Docker镜像（30-60分钟）
bash scripts/docker_build.sh

# 2. 导出环境包
bash scripts/docker_export.sh

# 3. 将tar.gz复制到目标ARM64系统安装
```

**详细文档：**
- 📖 [Docker构建完整指南](核心build动作专门说明.md)
- 🚀 [快速开始指南](全量安装python和默认依赖.md)
- 🔄 [增量更新指南](./INCREMENTAL_UPDATE.md) - 发现缺少包时的快速更新方案

**优势：**
- ✅ 无需ARM64物理机，Windows上即可构建
- ✅ 使用Ubuntu 22.04基础镜像（兼容麒麟V10）
- ✅ 自动编译Python 3.12和下载所有ARM64依赖
- ✅ 导出为tar.gz，可直接移植到目标系统

📦 2. 离线包内容
✅ Python 3.12（ARM64 预编译，含 pip + venv）
✅ 20+ 个分类依赖包（HTTP、DB、Auth、MQ、工具等）
✅ 所有 wheel 包（.whl），避免编译失败
✅ 自动安装脚本 install_deps.sh
✅ 增量更新脚本 update_deps.sh
✅ 示例模型：mistral-7b-v0.1.Q4_K_M.gguf + llama.cpp 二进制
✅ 安装后可直接运行 Agent 项目
⚙️ 3. 操作流程（分步）
3.1 在有网环境下打包（仅需一台 ARM64 电脑）

# 步骤1：下载并进入项目目录

# 步骤2：运行下载脚本（自动下载所有 wheel）

# 输出目录：
#   packages/  ← 满满的 .whl 包

3.2 将包刻录成光盘或 U 盘

# 将整个项目打包为一个 tar.gz
cd ..
tar -czf offline_agent_dev_arm64.tar.gz ./offline-agent-dev-arm64


3.3 在麒麟 ARM64 系统上执行安装

1. 挂载光盘
   sudo mkdir -p /mnt/disk
   sudo mount /dev/cdrom /mnt/disk

2. 解压
   sudo mkdir -p /opt/agent_dev
   sudo tar -xzf /mnt/disk/offline_agent_dev_arm64_v2.tar.gz -C /opt/

3. 配置环境变量（建议写入 ~/.bashrc）
   echo 'export PATH="/opt/agent_dev/python3.12/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

4. 进入安装目录
   cd /opt/agent_dev

5. 执行安装（完全离线）
   chmod +x scripts/install_deps.sh
   ./scripts/install_deps.sh
   ✅ 输出：

✅ Python 3.12 检测成功
✅ 虚拟环境创建成功：venv/
✅ 所有依赖安装完成！
✅ 现在可以运行：

source venv/bin/activate
python -c "import requests; print('✅ requests loaded')"
python -c "from fastapi import FastAPI; app = FastAPI(); print('✅ FastAPI ready')"


增量更新（新增需求包时）
比如你发现少了 pydantic-settings，只需：

修改 requirements.add.txt（添加新包）
执行更新脚本：

在有网环境运行
./scripts/update_deps.sh "pydantic-settings==2.4.0"
再次打包并导入新光盘。
📌 5. 常见问题 & 解决方案
问题 解决方法
出现 Cannot install wheel for xxx: platform not supported 检查 pip download 是否加了 --platform aarch64
安装失败：“unstable API” 请确保 --only-binary=:all:
找不到 pip 确保 Python 编译时加了 --with-ensurepip=install
llama.cpp 无法运行 可用 chmod +x 或换用 arm64 编译版
📚 附录：什么是 Wheel？

🔹 wheel 是 Python 的二进制分发格式，就像 .exe 之于 Windows。

.whl = .zip + 元数据，可直接 pip install xxx.whl 安装。
优点：无需编译、速度快、兼容性高、避免依赖缺失。
缺点：必须为目标平台（如 aarch64）编译或下载。
❓ 如果没有 wheel 怎么办？

遇到 no binary found 时，我们使用以下策略：

1. 优先尝试预编译 wheel
   pip download --only-binary=:all: --platform aarch64 ...

2. 若无 wheel，尝试下载源码包
   pip download --no-binary=:all: ...

3. 在麒麟上手动编译（需支持 GCC/Python-dev）
   python setup.py build_ext -I/path/to/include
   python setup.py install --user

💡 所以我们 强制要求先下载 wheel，若无则自动 fallback 下载源码包，退出时提醒用户需要“手动编译”。

🎁 6. 附赠工具包（可选）
📁 models/：包含：
mistral-7b-v0.1.Q4_K_M.gguf
phi-3-mini-4k-instruct.Q4_K_M.gguf
llama.cpp aarch64 预编译二进制
📄 usage_examples/：简单 Agent 示例代码
🖥️ start_server.sh：启动 FastAPI + llama.cpp 服务脚本