KoboldAI · 浏览器端 AI 写作与文字冒险前端 · 本地部署与使用全指南
项目仓库： https://github.com/KoboldAI/KoboldAI-Client
开源协议：见仓库 LICENSE · 运行时：Python / conda 自包含运行时 ·
启动入口：aiserver.py · 启动脚本：play.sh /
play.bat ·
依赖环境文件：huggingface.yml（CUDA）/
rocm.yml（ROCm）· 仓库分支：main
重要提示（官方 README 顶部）：当前页面是旧版软件，它已经无法运行现代模型。官方 README 开头明确写明 "You are currently on the page of the old software which will not run modern models"。现代本地模型请使用同源的 KoboldCpp（见本站对应指南）。本文按官方 README 给出旧版客户端的完整安装路径，供需要维护旧环境的读者参考。
1 项目简介
KoboldAI 是一个浏览器端的 AI 辅助写作前端，可接入多种本地与远程 AI 模型。它提供 Memory（记忆）、Author's Note（作者注）、World Info（世界信息）、存档/读档、可调 AI 参数、格式化选项，以及导入已有 AI Dungeon 冒险的能力；还可开启 Adventure 模式，像玩 AI Dungeon 一样进行文字冒险。
故事可以像小说、文字冒险游戏或聊天机器人三种方式游玩，通过界面切换即可。它支持 Google Colab、本地高端显卡、带 API Key 的在线服务（如 OpenAI、Inferkit），也能在 CPU 上较慢运行。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | KoboldAI（KoboldAI-Client） |
| 仓库地址 | github.com/KoboldAI/KoboldAI-Client |
| 项目定位 | 浏览器端 AI 写作 / 文字冒险前端 |
| 运行时 | Python + conda 自包含运行时（runtime/ 子目录） |
| 服务入口 | aiserver.py |
| Linux 启动脚本 | play.sh（AMD ROCm 用 play-rocm.sh） |
| Windows 安装 | install_requirements.bat（管理员运行）→
play.bat |
| 环境文件 | huggingface.yml（CUDA）/
rocm.yml（ROCm） |
| NVIDIA 要求 | Compute Capability 5.0 及以上 |
| 仓库分支 | main |
1.2 适用场景
- 想用浏览器界面做 AI 写作、文字冒险或聊天，后端接本地或远程模型。
- 已有一套自包含 conda 运行时，避免污染系统 Python。
- 需要在 Windows / Linux 上以安装脚本方式拉起整套环境。
1.3 能力边界（官方口径）
- 旧版客户端无法运行现代模型（官方 README 顶部声明），现代模型请用 KoboldCpp。
- 项目依赖庞大，Python 版本冲突是常见问题；官方建议机器上 Python 版本越少越好。
- AMD GPU 仅在 Linux 且 ROCm 兼容型号上可用，Windows 不支持。
2 功能特性
- 三种玩法：小说、文字冒险、聊天机器人，界面一键切换。
- 写作工具集：Memory、Author's Note、World Info、存档/读档、可调 AI 参数、格式化。
- 多后端：本地 GPU、Google Colab（TPU/GPU）、远程 API（OpenAI、Inferkit）、CPU。
- Adventure 模式：可像 AI Dungeon 一样游玩，支持自定义或随机 prompt。
- 自包含运行时：依赖装在仓库
runtime/子目录，不污染系统。
3 官方界面预览
本仓库 README 以文字说明与模型清单为主，未提供界面截图；实际界面以本地启动后浏览器访问为准。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | https://github.com/KoboldAI/KoboldAI-Client | 源码、安装脚本、环境文件 |
| Colab TPU 版 | TPU.ipynb | 免费在线 TPU 版 |
| Colab GPU 版 | GPU.ipynb | 免费在线 GPU 版 |
| Windows 离线安装包 | SourceForge | 离线安装器 |
| 推荐运行时环境 | huggingface.yml / rocm.yml |
CUDA / ROCm conda 环境 |
5 前置要求与服务器配置
5.1 软件前提
- Git：克隆仓库。
- Miniconda（手动安装）：官方推荐用 conda 管理依赖，可从 docs.conda.io 获取。
- NVIDIA 驱动 / CUDA（GPU 推理）：GPU 需 Compute Capability 5.0+。
- AMD ROCm（仅 Linux + 兼容型号）。
5.2 硬件建议
| 项目 | 建议 |
|---|---|
| 磁盘 | 约 20 GB 空闲（不含模型权重） |
| GPU | NVIDIA 显卡，Compute Capability ≥ 5.0 |
| 系统 | Windows 10+ 或 Linux；macOS 仅手动安装 |
6 方式一：Linux 运行时脚本（推荐）
官方 README 给出的 Linux 路径：
# 1. 克隆仓库
git clone https://github.com/KoboldAI/KoboldAI-Client.git
cd KoboldAI-Client
# 2. AMD 用户先装好 ROCm；NVIDIA 用户直接运行
bash play.sh
# AMD ROCm 显卡
bash play-rocm.sh脚本会自动配置自包含 conda 依赖并启动，依赖文件放在
runtime/ 子目录。如需强制重装运行时，运行
install_requirements.sh。
7 方式二：手动 conda 环境（Mac / 自定义）
官方说明：手动安装需具备 Python/conda 经验，用仓库自带环境文件创建 conda 环境：
# CUDA 用户（推荐）
conda env create -f huggingface.yml
# ROCm 用户
conda env create -f rocm.yml
# 手动启动（不要用 play.bat/play.sh）
python aiserver.py官方强调：手动安装路线不要用 play.bat/play.sh，应直接运行
aiserver.py。
8 配置项说明
| 配置 | 位置 | 说明 |
|---|---|---|
| 运行时目录 | runtime/ |
自包含 conda 依赖，不污染系统 |
| CUDA 版本 | environments/finetuneanon.yml |
如需 CUDA 10，在 dependencies 下加
- cudatoolkit=10.2 |
| 环境文件 | huggingface.yml / rocm.yml |
CUDA / ROCm 环境 |
| Windows 安装模式 | 安装时选 Temporary B: 盘 | 官方强烈推荐，规避长路径问题 |
9 常用运维命令
# Linux 启动
bash play.sh
# 强制重装运行时
bash install_requirements.sh
# 手动启动（conda 环境内）
python aiserver.py10 常见故障排查
- ModuleNotFoundError：官方称这通常是下载/安装失败或与其他 Python 版本冲突所致。路径含空格、杀毒软件沙箱、磁盘不足、未开启长路径都可能导致。机器上 Python 版本越多越易出错。
- GPU not found：要么没有合格的 NVIDIA GPU（需 CC
5.0+），要么所用 GPU 不被当前 CUDA 支持。官方建议卸载手动安装的 CUDA
后重试；需 CUDA 10 则修改
finetuneanon.yml加- cudatoolkit=10.2。 - Windows 安装报错：以管理员运行
install_requirements.bat，安装模式选 Temporary B: 盘，必要时临时关闭杀毒软件。 - 现代模型跑不起来：这是旧版客户端已知限制，官方推荐改用 KoboldCpp。
11 风险与合规说明
- 项目已为旧版：官方 README 顶部声明其无法运行现代模型，新项目请直接使用 KoboldCpp。
- 模型许可证：如 OPT 等模型禁止商业用途、仅限研究，选用模型时需核对各自许可。
- 内容合规：写作内容需自行负责，不得生成违法违规内容。
- 非官方声明：本文基于官方 README 整理，脚本与环境文件名以仓库 main 分支最新为准。