Metadata-Version: 2.4
Name: vllm-cleaner
Version: 0.1.0
Summary: A utility to automatically kill vLLM processes and release GPU memory.
Author-email: Your Name <your.email@example.com>
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: psutil>=5.8.0

# vLLM Cleaner 🧹

一个轻量级的 Python 实用工具，用于在 LLM 评测或训练任务结束后，**自动清理 vLLM 进程并彻底释放 GPU 显存**。

## 💡 为什么需要这个工具？

在使用 `vLLM` 框架进行大模型推理、评测或训练时，经常会遇到以下痛点：
- 脚本执行完毕或因代码报错崩溃后，vLLM 进程依然在后台残留（僵尸进程）。
- GPU 显存被持续占用，导致后续的实验抛出 `CUDA Out of Memory` 错误。
- 每次都需要手动运行 `lsof` 或 `netstat` 查端口，再 `kill -9`，费时费力。

**vLLM Cleaner** 通过一行代码（装饰器）完美解决这个问题。无论是程序正常结束、异常报错，还是被手动 `Ctrl+C` 中断，它都能顺藤摸瓜找到占用端口的进程树，并将其彻底连根拔起。

## ✨ 特性

- **极简接入**：只需在主函数加上 `@auto_kill_vllm(port=...)` 装饰器即可。port参数是vllm服务的端口。
- **全场景覆盖**：基于 `try...finally` 和系统信号（`SIGINT`/`SIGTERM`）监听，防崩溃、防中断。
- **斩草除根**：自动解析占用指定端口的父进程 PID，并递归杀掉所有子进程，确保显存 100% 释放。
- **自动安装依赖**：通过 pip 安装时，会自动配置所需的 `psutil` 库。

## 📦 安装

你可以直接通过 GitHub 源码一键安装（已包含自动处理依赖）：

```bash
pip install git+[https://github.com/](https://github.com/)<你的GitHub用户名>/vllm-cleaner.git
```

## 🚀 快速开始 (Quick Start)

```python
from vllm_cleaner import auto_kill_vllm

# 在此处传入你的 vLLM 服务实际占用的端口号
@auto_kill_vllm(port=30338)
def main():
    print("🚀 开始执行大模型评测/训练任务...")
    
    # 这里是你的业务逻辑，比如启动 vLLM 服务、跑数据等
    # ...
    
    print("✅ 任务执行完毕！")

if __name__ == "__main__":
    main()
    print("🧹 此时 main 函数已结束，vLLM 进程已被全自动清理，显存已清空！")
    # 后续可以继续执行不需要 GPU 的代码...
```
