Metadata-Version: 2.4
Name: qwen38-flash-next
Version: 0.1.6
Summary: 一键运行 Qwen3.8-Flash-Next 本地大模型：自动装环境、下模型、进对话
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.7
Requires-Dist: huggingface_hub>=0.26

# qwen38-flash-next

在本地一键运行 [Qwen3.8-Flash-Next](https://huggingface.co/unsloth/Qwen3.8-Flash-Next-GGUF)（125B MoE，6B 激活）UD-IQ1_S 量化版。

执行后自动完成：查找或安装 llama.cpp 运行时（qwen4exp 架构需要未合入的 PR #27742 构建）→ 查找或下载模型（默认走 hf-mirror.com，国内网络友好）→ 启动本地服务 → 进入交互式对话。**已存在的模型和运行时会被直接复用，不重复下载/编译。**

## 安装

```bash
pip install qwen38-flash-next        # PyPI
# 或本地源码
uv tool install ./qwen38-flash-next  # 推荐，隔离环境
```

## 使用

```bash
qwen38-flash                 # 交互式对话
qwen38-flash --say "你好"     # 单发一句（脚本/测试用）
qwen38-flash --download-only # 只下载模型
qwen38-flash --ms             # 从 ModelScope 下载（hf-mirror 不通时用）
```

首次运行需要约 74GB 磁盘与下载时间；48GB 内存机器默认 `-ngl 0` 纯 CPU 运行（Metal 会因超大嵌入层 OOM）。

交互命令：`/exit` 退出，`/clear` 清空上下文，`/save 文件` 保存对话。

## 常用选项

| 参数 / 环境变量 | 说明 |
|---|---|
| `--model PATH` / `QWEN38_MODEL` | 指向模型首分片 `...00001-of-00003.gguf`，跳过查找与下载 |
| `--server-bin PATH` / `QWEN38_LLAMA_SERVER` | 指定支持 qwen4exp 的 llama-server 二进制 |
| `--port 8080` / `--ctx 8192` / `--ngl 0` | 服务端口 / 上下文 / GPU 层数 |
| `HF_ENDPOINT` | 模型下载源，默认 `https://hf-mirror.com` |

模型与运行时路径在首次就绪后写入 `~/.qwen38-flash/config.json`，后续启动直接复用。

## 查找顺序（逐级复用）

模型：`--model`/环境变量 → 配置文件 → 常见位置（HF 缓存、ModelScope 缓存、`~/models`、本仓库工作区）→ 自动下载。
运行时：`--server-bin`/环境变量 → 配置文件 → PATH 中的 llama-server（会校验能否加载模型）→ 自动克隆 PR #27742 源码编译（需 git + cmake + Xcode CLT）。
