折腾了一个周末总算把 Drama Skills 在 Ubuntu 服务器上完整跑通了。这个项目本质上是把大语言模型的能力编排成一套可执行的“剧本技能流”——角色设定、剧情分支、情绪状态跟踪这些模块全部以配置文件驱动通过本地的推理服务来实时生成内容。比起我先前在 Windows 环境下试过的同类方案它在 Ubuntu 上部署有两个最实在的好处一是 Python 生态和 CUDA 驱动链更干净二是 systemd 托管服务非常顺手重启后自动拉起完全不用手动干预。这篇教程就按我实际踩坑后的完整流程来写目标是让一个对命令行不算陌生的读者照着一步步操作也能把服务端跑起来。适用人群准备在自己服务器上跑大模型推理、想做角色扮演类聊天应用或者单纯想研究技能化 Prompt 编排的开发者。如果你之前只玩过调用闭源 API这算是往本地部署迈出的第一步。1. 部署前的方案选型与核心思路1.1 Drama Skills 到底是什么简单说Drama Skills 是一个“技能编排框架”。它不像普通聊天机器人那样一句 prompt 走天下而是把一个复杂的生成任务拆成多个小步骤每个步骤对应一个独立的技能模块。比如一个“侦探破案”场景系统会先让模型扮演叙述者描述现场再切换到嫌疑人的视角输出证词最后才让玩家角色做出选择。每一步都有单独的 prompt 模板、参数设置和状态约束。这意味着部署的时候不只是起一个 Web 服务那么简单你还需要关心模型推理引擎、技能配置目录、上下文管理策略以及它们之间的数据流转。很多人在这一步翻车是因为以为“跑起来一个 gradio 界面就算成功”实际上一旦技能链路稍微复杂一点对显存、上下文长度、推理延迟的要求完全不一样。建议先想清楚你要用什么样尺寸的模型。7B 到 14B 的量化模型单张消费级显卡12GB 到 24GB 显存可以比较舒服地跑起来34B 以上的模型老实上双卡或者干脆用云 GPU 实例。1.2 为什么选择 Ubuntu 作为宿主机就我个人的经验来看在 Windows 上部署这类项目和 Ubuntu 完全是两种体验。Drama Skills 的依赖链条里有大量编译型组件——比如 tokenizer、向量索引相关的原生库Windows 下经常需要预编译 wheel而这些 wheel 对特定 Python 版本和 CUDA 版本极其挑剔有时候官方仓库还没跟上你就得自己去拉源码编非常耗时间。Ubuntu 这边几乎是反过来的。项目文档里给的依赖清单基本都是面向 Linux 写死的apt 装系统库、pip 装 Python 包路径清晰、权限明确。更关键的是NVIDIA 驱动和 CUDA toolkit 在 Ubuntu 18.04 到 24.04 这几代系统上的安装流程非常成熟基本不会出现驱动签名或者版本错乱的问题。另外 Ubuntu 对内存和句柄数的默认限制比 Windows 宽松很多。Drama Skills 在生成长文本时Python 进程的内存占用可能到好几 GB还要同时保持多个模型的并行加载。Windows 下偶发的内存碎片问题在 Ubuntu 上几乎没碰到过。1.3 整体部署架构预览我把部署链路分成四层基础层Ubuntu 系统本身 NVIDIA 驱动 CUDA Python 虚拟环境推理层模型推理引擎也就是 Ollama或者 vLLM应用层Drama Skills 项目代码包括技能配置、服务端逻辑、API 接口接入层systemd 服务托管 反向代理可选这套架构的好处是每层相对独立。驱动版本出问题不会影响模型文件模型损坏也只需重新拉取应用代码写崩了重启服务就好不用动系统环境。2. 环境准备与基础依赖安装2.1 确认系统版本和硬件资源开始动手之前先执行下面几条命令确认机器状态lsb_release -a nvidia-smi free -h df -h /我建议系统最好在 20.04 或更高版本。内核太老的话部分新版本的 CUDA 驱动装不上会导致后面推理引擎无法调用 GPU。显卡这块nvidia-smi如果显示驱动版本过低或者提示No devices were found那要先装驱动再继续。内存方面除了系统本身占用的量建议给模型推理留下足够余量。跑 7B Q4 量化模型推理时大概需要 6GB 到 8GB 的显存同时 CPU 内存至少保留 8GB 给 Python 进程和缓存用。要是机器配置捉急内存不够的话模型服务很容易一启动就被内核 OOM Kill。2.2 安装 NVIDIA 驱动与 CUDA 工具链在 Ubuntu 上装驱动我比较推荐用软件仓库里的nvidia-driver-系列包而不是去官网下.run文件。理由很简单仓库包和当前内核的版本冲突概率小卸载干净回滚也容易。sudo apt update sudo apt install -y ubuntu-drivers-common ubuntu-drivers devices sudo apt install -y nvidia-driver-535装完重启再次执行nvidia-smi看到类似下面的输出就说明驱动没问题----------------------------------------------------------------------------- | NVIDIA-SMI 535.154.05 Driver Version: 535.154.05 CUDA Version: 12.2 |之后安装 CUDA toolkit。这里有一个容易搞混的点驱动自带的 CUDA version 只是最高兼容上限程序运行时实际用的是你自己装的 CUDA runtime 或 PyTorch 自带的 CUDA 库。所以如果你只是用 PyTorch 或 Ollama其实不一定需要单独装完整版 CUDA toolkit。但为了以防后续编译扩展我还是建议装一套 base toolkitsudo apt install -y nvidia-cuda-toolkit nvcc --version我在实际部署时很大一部分时间花在了 Python 环境上。Python 3.10 是兼容性最好的版本Drama Skills 依赖的很多库比如 pydantic、fastapi在新版本 Python 下有时会有编译问题所以用 conda 固定版本最省心。2.3 配置 Python 虚拟环境与基础工具先安装 conda我选的是 Miniconda体积小、够用wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh source ~/.bashrc然后创建虚拟环境并安装项目依赖。以 Drama Skills 为例官方要求的依赖都写在了requirements.txt里但这里有一个非常关键的操作尽量把 torch 和 flash-attention 这类编译型依赖装成预编译版不要现场编译否则折腾几小时都打不住。conda create -n drama python3.10 -y conda activate drama pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 pip install -r requirements.txt这里再给一个建议。装完依赖后立刻用python -c import torch; print(torch.cuda.is_available())验证一下 PyTorch 能不能正常看到 GPU。很多人到这一步没有任何输出或者直接报错就是因为 CUDA 和 PyTorch 的版本对应不上。3. 获取项目代码与核心配置详解3.1 拉取代码与目录结构说明Drama Skills 的代码放在代码托管平台上直接用 git 拉取到工作目录mkdir -p ~/apps cd ~/apps git clone https://github.com/your-project-source/drama-skills.git cd drama-skills拉下来之后你会看到几个核心目录skills/存放所有技能模块的配置目录每个子目录代表一个技能models/模型存放位置一般会通过软链接指到空间更大的磁盘configs/全局配置包括数据库连接、Redis 地址、模型加载参数runtime/运行时日志、缓存建议从一开始就把模型目录和数据目录分开。系统盘一般不大模型文件动辄十几 GB直接放项目目录里很容易把根分区写满。可以在项目里建软链接mkdir -p /data/models mv ~/apps/drama-skills/models/* /data/models/ 2/dev/null ln -s /data/models ~/apps/drama-skills/models3.2 配置文件核心参数解析Drama Skills 的主配置文件直接决定了服务怎么启动。下面我把关键的几个配置项和它们背后的逻辑讲清楚。server: host: 0.0.0.0 port: 8000 workers: 1 model: backend: ollama name: qwen2.5:14b-instruct-q4_K_M context_length: 8192 max_tokens: 2048 temperature: 0.8 top_p: 0.9 repeat_penalty: 1.15 skill: directory: skills auto_reload: true auth_token: your-secret-token runtime: log_level: INFO cache_type: memory先看model部分。backend指定了推理引擎我选的 ollama 是因为它自带模型管理、API 接口和上下文缓存很适合中小型项目。name要填具体的模型标签标签必须和你本地ollama list里显示的名字完全一致否则服务启动后调用模型时会一直报模型不存在。temperature和top_p这两个参数直接影响戏剧生成的质量——数值太高模型容易放飞自我前后矛盾数值太低则输出干巴巴的。做角色扮演类场景0.7 到 0.9 是不错的区间。context_length如果要调大一定要先确认显卡显存撑得住。上下文长度越长KV cache 占用的显存越高14B 模型的 8K 上下文大概会额外占掉 4GB 到 6GB 的显存空间这个开销经常被忽略。我建议先用 4096 测试跑稳定了再慢慢往上加。workers设为 1 是刻意为之。Drama Skills 的技能执行链路状态存在内存里多 worker 模式下请求打到不同进程技能状态就串不起来了。如果一定要提高并发应该在应用层做横向扩展而不是单机开多进程。auto_reload在开发阶段非常方便——修改技能配置后不用重启服务就能生效。但在生产环境里我建议把它关掉避免有人改了配置导致线上服务完全重载。3.3 模型获取与本地化部署项目配置文件指向的模型需要提前用推理引擎拉取到本地。以 Ollama 为例curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:14b-instruct-q4_K_Mollama pull会根据你本地的磁盘空间、网络带宽拉取对应精度的模型。这一步很慢也很容易断我分享一下我的经验断线后直接再执行一次同样的命令Ollama 支持断点续传多试几次总能拉完。模型文件默认放在/usr/share/ollama/.ollama/models如果你的磁盘紧张可以通过环境变量OLLAMA_MODELS指定一个新的存储路径再重启服务。拉完以后用一条命令验证模型能不能正常响应ollama run qwen2.5:14b-instruct-q4_K_M 你好简单介绍一下你自己能正常输出内容就说明推理链路已经通了。这时候再启动 Drama Skills 服务问题就只剩应用层了。4. 服务启动与技能功能验证4.1 首次启动与日志解读确认模型没问题后就可以启动 Drama Skills 了cd ~/apps/drama-skills conda activate drama python main.py --config configs/config.yaml第一次启动时服务会做几件事加载技能配置、初始化缓存、建立与推理引擎的长连接。日志正常情况下会显示类似内容[INFO] Loading skill package: narrative_scene [INFO] Skill narrative_scene registered with 12 actions [INFO] Loading skill package: dialogue_actor [INFO] Skill dialogue_actor registered with 8 actions [INFO] Connected to model backend ollama, model qwen2.5:14b-instruct-q4_K_M [INFO] HTTP server started on http://0.0.0.0:8000如果日志卡在某个 skill 加载失败多半是技能目录下的 YAML 配置写错了比如引用了不存在的 prompt 模板文件。这时候日志里会明确提示哪个文件哪一行出错顺着改就行。服务启动后默认监听在 8000 端口。要验证外部能不能访问先在本机测curl -X POST http://127.0.0.1:8000/v1/chat \ -H Authorization: Bearer your-secret-token \ -H Content-Type: application/json \ -d {message: 深夜的街道上你看到一盏路灯忽明忽暗一个戴着旧帽子的男人朝你走来接下来会发生什么}如果一切正常几秒钟内会返回一段漂亮的剧情文字并且响应内容会根据技能配置中的角色模板自动带入场景氛围。4.2 Web 界面和 API 调试技巧Drama Skills 默认带一个简单的 Web 调试界面访问http://你的服务器IP:8000/就能看到聊天窗口。这个页面主要是方便确认技能链路是否正常不适合直接给终端用户用性能和样式都没优化过。如果你打算做二次开发建议用 API 文档自动生成的调试页可以快速测试每个接口参数。同时配合一个 WebSocket 接口来实时推送生成过程中的增量内容这样玩家侧体验会更流畅。官方调试界面只是提供一个参考实现真正要上生产还是要自己写前端。调试技能时有个捷径直接改技能的 YAML 配置文件把temperature调低到 0.5、repeat_penalty调高快速排查是不是参数导致生成质量崩了。改完刷新页面前后对比会非常直观。4.3 用 systemd 托管服务实现开机自启手动启动的服务SSH 断开或者服务器重启就没了。要用 systemd 把它托管起来sudo tee /etc/systemd/system/drama-skills.service /dev/null EOF [Unit] DescriptionDrama Skills Service Afternetwork-online.target ollama.service Wantsnetwork-online.target [Service] Typesimple Userubuntu WorkingDirectory/home/ubuntu/apps/drama-skills ExecStart/home/ubuntu/miniconda3/envs/drama/bin/python main.py --config configs/config.yaml Restarton-failure RestartSec10 EnvironmentCUDA_VISIBLE_DEVICES0 [Install] WantedBymulti-user.target EOF写完后刷新并启动sudo systemctl daemon-reload sudo systemctl enable --now drama-skills sudo systemctl status drama-skills有一点要特别提醒User字段决定了服务以哪个权限运行因为模型文件路径、日志目录如果有权限限制启动会直接失败。所以我建议统一用一个普通用户把所有脚本和数据都放在这个用户的目录下避免用 root 跑模型服务导致的安全问题。4.4 反向代理与域名访问配置8000 端口直接暴露在公网上不安全也不方便对接已有的 Web 服务。我在前面套了一层 Nginx用子路径或者子域名转发server { listen 80; server_name drama.example.com; location / { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_read_timeout 300s; } }proxy_read_timeout我特意调到 300 秒Drama Skills 生成一段长剧情的时候接口响应可能超过默认的 60 秒超时不做调整的话前端会报网关超时这是很多人改完还是频繁断连的一个隐藏坑。5. 常见问题与实战排查记录5.1 模型加载阶段的问题我在整个部署过程中遇到最多的问题集中在模型加载阶段。这里挑几个典型的记录一下。第一个是 CUDA out of memory。我一开始跑 14B 模型配置文件里把上下文设到了 16K结果服务刚启动没几分钟进程就被系统杀掉查看dmesg日志发现是 OOM。原因就是 KV cache 占的显存实在太大加上模型本身、Python 运行时轻松突破显存上限。解法很简单把context_length降到 4096关闭多余的后台程序再试。第二个是Ollama服务起不来报错提示模型文件损坏。这种情况绝大多数是之前ollama pull的时候网络中断导致的。多执行几次ollama pull让它重新校验文件即可。如果校验一直失败可以用ollama rm把模型删掉再重新拉取。注意不要在模型还在下载的时候重启机器。第三个是模型下载完成后Drama Skills 还是报模型名不存在。排查方向先从 API 调用方式入手Ollama 的调用名和ollama list显示的名称不一定完全一致有的版本需要在名称后加上:latest标签。用ollama list查看准确名称再同步到配置文件里。5.2 推理性能与生成质量问题的调优策略生成速度慢是另一个高频问题。第一次跑的时候我发现生成一段 500 字的剧情要等差不多 20 秒这交互体验太差了。先简单算一笔账14B Q4 量化模型在 4090 上理论速度大概是每秒 40 到 50 个 token但如果开了 8K 上下文生成长文本时首 token 延迟会明显增加。优化手段有几个降低上下文长度只保留剧情必要的记忆窗口启用推理引擎的 KV cache 量化能力减少显存读写压力对冷门模型做一次融合优化把多层权重合并减少计算量生成质量方面如果模型输出的内容开始严重脱离角色通常是温度参数太高。Drama Skills 里不同技能可以覆盖全局 temperature可以单独给某个技能指定比较低的值不用全局改动。另一个常见问题是模型的重复率很高角色反复说同一句话这时把repeat_penalty往上调。5.3 部署后如何检测服务健康服务跑起来以后我习惯用一个轻量级的脚本做健康检查每隔一段时间就调用一次 API看响应时间是否在预期范围内。可以拿 curl 简单实现也可以写成一个独立脚本在异常时重启服务。实际过程中我还遇到过一个隐蔽的问题GPU 温度在连续生成长篇剧情时会飙到 85 度左右这时候显卡会自动降频推理速度直线下降。排查时注意观察nvidia-smi的功耗和温度一旦长时间超过 80 度要考虑给服务器加强散热或者降低并发压力。6. 项目后续扩展思路与个人经验总结Drama Skills 部署完成只是整个项目的第一步。真正让它在实际场景里发挥价值还需要围绕它做几个方向的扩展。首先是技能库的持续完善。默认带的技能模板偏通用如果想要做出独特风格的互动叙事最好自己动手写技能配置文件。比如设计一个“古风江湖”的专属技能定义好门派、人物关系、武功招式这些状态变量再配合相应的 prompt 模板生成效果会完全不一样。其次是多模型路由。我把一个轻量模型如 7B用在快速意图识别场景把重量级模型如 34B用在最终文本生成场景。Drama Skills 支持配置多后端按实际需要切换能很好地平衡成本和体验。再有一个建议是接入外部记忆系统。默认的缓存方式是把上下文存在内存里服务重启后所有状态清空。如果想让剧情有长期的连续性比如让角色记住玩家之前做过的选择就需要把记忆持久化到数据库里。可以选用关系型数据库或轻量级向量库来存储历史消息摘要每次生成前先做一次语义检索把相关记忆带回上下文。最后从我的实际体会来说部署这类项目最核心的不是把命令敲对而是理解每一层之间的关系。模型、推理引擎、应用配置每一层都有自己的一套规则只有把它们之间的边界理顺了后面调优才不至于一头雾水。你在部署过程中如果也遇到什么奇怪的问题不妨先把日志级别调成 DEBUG很多时候答案早就写在日志里了只是我们没有静下心来看。