env/README.md

# Kimodo 本地环境部署指南

## 目录结构

```
/workspace/env/
├── conda_env/
│   └── kimodo_env.tar.gz    # 打包的 Conda 环境
├── bin/                     # 可选：额外的二进制工具
├── lib/                     # 可选：额外的库文件
├── scripts/
│   ├── unpack_env.sh        # 环境解压脚本
│   └── init_env.sh          # 环境初始化脚本
└── configs/
    ├── BINARY_DEPS.txt      # 二进制依赖说明
    ├── cuda_info.txt        # CUDA 信息
    └── system_deps.txt      # 系统依赖信息
```

## 部署步骤

### 1. 准备目标机器

目标机器需要安装以下系统工具：

- Ubuntu 20.04+ 或兼容的 Linux 发行版
- gcc/g++ (9.0+)
- cmake (3.18+)
- make
- tar/gzip

安装命令：
```bash
sudo apt-get update
sudo apt-get install -y build-essential cmake tar gzip
```

### 2. 克隆项目

```bash
git clone <your-repo-url>
cd <project-directory>
```

### 3. 解压环境

```bash
./env/scripts/unpack_env.sh
```

### 4. 初始化环境

```bash
./env/scripts/init_env.sh
```

此脚本会：
- 检查系统依赖
- 修复环境路径
- 验证环境配置

### 5. 启动项目

```bash
./start_local.sh
```

## 注意事项

### CUDA 支持

如果目标机器有 NVIDIA GPU，需要安装：
- NVIDIA Driver (470+)
- CUDA Toolkit (11.0+)
- cuDNN (8.0+)

验证 CUDA 安装：
```bash
nvidia-smi
```

### 网络要求

项目配置为完全离线模式，所有模型都已下载到本地。但首次启动时可能需要访问：
- 本地缓存目录
- 模型文件（应包含在项目中）

### 故障排除

#### Python 环境未找到
```bash
ls -la env/conda_env/kimodo/bin/python
```

#### 导入错误
```bash
env/conda_env/kimodo/bin/python -c "import kimodo; print('OK')"
```

#### CUDA 相关错误
检查 NVIDIA 驱动和 CUDA 安装：
```bash
nvidia-smi
nvcc --version
```

## 环境更新

如需更新 Python 包：

```bash
env/conda_env/kimodo/bin/pip install <package-name>
```

重新打包环境（如有需要）：
```bash
conda pack -n kimodo -o env/conda_env/kimodo_env.tar.gz
```

## 文件大小说明

- 打包后的环境：约 1.5-2GB（压缩后）
- 解压后的环境：约 9GB
- 包含的主要组件：
  - Python 3.10
  - PyTorch (CUDA 版本)
  - 所有项目依赖包
  - Kimodo 项目包

## 联系支持

如有问题，请检查：
1. `env/scripts/init_env.sh` 的输出
2. `start_local.sh` 的日志
3. 系统依赖是否完整安装