1. 项目概述一个本地化、多智能体驱动的龙与地下城游戏引擎最近在折腾一个挺有意思的项目叫 TD-LLM-DND。简单来说这是一个让你能在自己电脑上用本地运行的大语言模型LLM来跑一场“龙与地下城”DD风格文字冒险的工具。它不是一个成品游戏更像是一个游戏引擎或框架核心是把传统跑团中“地下城主”DM和“玩家”的角色都交给了AI来扮演。对于喜欢DD但苦于找不到固定团友或者对AI角色扮演、多智能体交互感兴趣的技术爱好者来说这个项目提供了一个绝佳的实验场。你不需要连接任何外部API所有计算和“思考”都在本地完成通过Ollama来管理和调用各种开源模型。项目用Streamlit构建了一个简洁的Web界面让你可以像操作一个Web应用一样生成角色、开启冒险并观察AI们如何互动推进剧情。我花了一些时间深入研究了它的代码和运行逻辑发现其设计思路非常清晰但在实际部署和玩法深度上有不少值得挖掘和优化的地方。接下来我将从设计思路、环境搭建、核心玩法实现到深度定制为你完整拆解这个项目并分享我在实操中踩过的坑和总结的经验。2. 核心架构与设计思路拆解2.1 为何选择“本地LLM 多智能体”架构这个项目的核心价值在于其架构选择。它没有采用调用云端大模型API如OpenAI的GPT系列的方式而是完全基于本地部署的Ollama。这么做有几个关键考量隐私与数据安全所有的角色背景、冒险剧情、对话内容都不会离开你的本地机器。对于创作敏感故事或单纯注重隐私的用户来说这是首要优势。成本可控一旦部署完成除了电费几乎没有额外开销。你可以无限次地生成冒险而不必担心API调用费用。模型选择的灵活性Ollama支持众多开源模型如Llama 2/3、Mistral、Gemma等。你可以根据电脑性能主要是显存选择不同尺寸的模型甚至为DM和玩家角色分配不同的模型观察其互动差异。可玩性与实验性将DM和每个玩家都抽象为一个独立的AI智能体Agent它们之间通过结构化的提示词Prompt和游戏状态进行交互。这本身就是一个研究多智能体协作与竞争、角色一致性的有趣沙盒。项目的架构可以简化为下图所示的数据流[Streamlit UI] - [游戏状态管理] - [DM智能体 (LLM)] - [玩家智能体们 (LLM)] - [本地向量数据库 (可选)]Streamlit界面负责展示和接收最基础的操作指令如“下一回合”。游戏的核心逻辑状态机、回合制推进由Python代码管理。在每个关键节点如需要DM描述场景或决定玩家角色的行动相应的模块会构造一个详细的提示词发送给Ollama服务获取LLM的文本响应再解析响应并更新游戏状态。2.2 项目模块化解析浏览项目代码可以发现几个核心模块app.pyStreamlit应用的主入口负责界面布局、用户交互和最高层级的游戏流程控制生成队伍、开始冒险、下一回合。game/目录核心游戏逻辑所在。state.py定义了游戏状态类GameState保存当前冒险的所有信息如队伍成员、当前场景、回合计数、历史记录等。这是整个游戏的“记忆中枢”。agents/包含dm_agent.py和player_agent.py分别定义了地下城主和玩家智能体的类。它们的核心方法是根据当前游戏状态生成发送给LLM的提示词Prompt并处理LLM的返回结果。llm_client.py一个封装好的Ollama API客户端所有智能体都通过它来与本地模型通信。这里集中处理网络请求和错误重试。utils/目录包含一些工具函数如角色生成器character_generator.py可能利用LLM为玩家创建随机的姓名、种族、职业和背景故事。这种模块化设计使得功能扩展变得清晰。例如如果你想增加一个“物品鉴定系统”很可能只需要在game/state.py中增加相关状态并在agents/dm_agent.py的提示词模板中加入相应的判断逻辑。3. 从零开始的环境搭建与配置详解原项目的README给出了基础的安装步骤但在实际操作中有几个细节直接关系到能否成功运行。3.1 基础环境准备Python与虚拟环境确保你的系统已安装Python 3.8或更高版本。我强烈推荐使用虚拟环境这能避免包依赖冲突。# 1. 克隆项目 git clone https://github.com/tegridydev/dnd-llm-game.git cd dnd-llm-game # 2. 创建虚拟环境以venv为例 python -m venv venv # 3. 激活虚拟环境 # Linux/macOS: source venv/bin/activate # Windows: # venv\Scripts\activate # 激活后命令行提示符前通常会显示 (venv)3.2 依赖安装与潜在坑点运行pip install -r requirements.txt是标准操作。但根据我的经验有两点需要特别注意LangChain版本原项目的requirements.txt可能指定了某个版本的LangChain。LangChain更新较快新版本可能会有API变动。如果运行时出现LangChain相关导入错误可以尝试固定到一个稍旧的稳定版本例如pip install langchain0.0.350 # 只是一个例子请根据错误信息调整系统依赖某些Python包如chromadb用于向量数据库可能有系统级的依赖。在Linux上你可能需要安装g等编译工具。如果安装过程中报错仔细阅读错误信息通常搜索引擎能帮你找到缺失的系统包。3.3 Ollama的安装与模型部署这是项目的核心依赖。Ollama的安装非常简单去其官网下载对应操作系统的安装包即可。安装完成后你需要拉取至少一个LLM模型。# 启动Ollama服务通常安装后会自动运行也可手动启动 ollama serve # 在另一个终端窗口拉取模型。对于入门7B参数的模型对硬件要求较低。 # 例如拉取Mistral 7B ollama pull mistral:7b # 或者Llama 3 8B ollama pull llama3:8b实操心得模型选择模型的大小直接决定了生成速度和质量。7B/8B的模型在16GB内存的电脑上可以流畅运行。如果你有足够的GPU显存如8GB以上可以尝试更大的模型如13B、70BDM的描述和玩家的决策会更具创造性和连贯性。你可以同时拉取多个模型在应用的“管理模型”界面中进行切换测试。3.4 环境变量与项目配置按照要求创建.env文件。这里每个变量的作用如下OLLAMA_API_ENDPOINThttp://localhost:11434/api/generate # Ollama服务的默认API地址通常不需要修改。 PDF_FOLDERpdf # 项目预留的功能可能用于上传背景资料PDF并存入向量数据库供DM参考。如果不用文件夹为空即可。 CHROMA_DB_DIR./chroma_db # Chroma向量数据库的存储目录。如果你启用了“知识库”功能如让DM参考PDF内容对话的上下文或PDF内容会被处理成向量存储在这里。 TURN_LIMIT10 # 冒险的最大回合数限制防止游戏无限循环。达到限制后游戏可能会自动结束或提示。确保这些路径在你的项目根目录下存在或可创建。4. 核心玩法流程与代码级实操解析环境配置好后通过streamlit run app.py启动应用。界面通常分为几个主要区域侧边栏用于模型管理、队伍生成、主区域显示游戏日志、当前场景、队伍状态。4.1 生成你的AI冒险队伍点击“Generate New Party”按钮。背后发生了什么前端触发Streamlit按钮触发一个回调函数。调用生成器该函数会调用utils/character_generator.py中的逻辑。构造Prompt生成器会向Ollama发送一个精心设计的Prompt例如“你是一个奇幻角色生成器。请生成一个DD 5e角色包含1.一个有趣的姓名2.种族如人类、精灵、矮人3.职业如战士、法师、游荡者4.一段简短的背景故事50字内5.一件起始物品。”解析与存储获取LLM的回复后代码会尝试解析文本提取出结构化信息并创建一个Character对象添加到GameState.party列表中。界面更新Streamlit重新渲染在界面上展示新生成的角色卡片。注意事项生成结果的随机性LLM的生成是随机的有时回复的格式可能不符合预期导致解析失败角色信息显示不全。这是当前基于文本解析方式的通病。更稳健的方法是使用LLM的“函数调用”Function Calling或“结构化输出”Structured Output功能但需要模型本身支持且Ollama的API兼容性需要测试。4.2 开启一场新的冒险点击“Start New Adventure”。这是游戏真正的开始。状态初始化GameState对象被重置或创建。回合数turn_count设为0历史记录history清空当前场景current_scene设置为一个初始值如“你们站在一片古老森林的边缘”。DM的首次登场游戏逻辑会调用dm_agent.py中的generate_response方法。DM的Prompt工程该方法会构造一个非常详细的Prompt给DM模型内容包括角色设定“你是地下城主DM负责主持一个DD 5e风格的冒险。”游戏状态“当前队伍成员是[列出所有角色]。当前场景是[初始场景]。”行动指令“请为玩家们描述这个场景的开场包括环境、氛围、以及任何明显的线索或挑战。描述要生动长度在3-5句话。”格式要求“只输出场景描述不要以DM的口吻说话如‘你们看到…’直接进行叙述。”推进游戏DM模型生成的场景描述会被添加到游戏历史并显示在主界面上。游戏状态进入“等待玩家行动”阶段。4.3 回合制推进与多智能体交互点击“Next Turn”这是最精彩的部分——多智能体交互。回合更新turn_count加1。玩家智能体行动对于队伍中的每个AI玩家角色游戏循环会 a. 调用player_agent.py中的take_action方法。 b. 该方法构造给该玩家AI的Prompt包含角色自身信息、当前场景描述、游戏历史、以及指令如“根据你的角色性格和当前情况决定你要做什么或说什么。只输出你的行动描述。”。 c. 每个玩家AI独立生成自己的行动例如“精灵法师仔细检查地上的符文痕迹”“矮人战士举起盾牌挡在队伍前方戒备”。 d. 所有玩家的行动被收集、汇总并添加到游戏日志。DM智能体响应 a. 基于更新后的游戏历史包含了玩家们的新行动再次调用DM智能体。 b. 这次的Prompt会指令DM根据玩家的行动描述世界如何反应推动剧情发展可能包括环境变化、NPC对话、遭遇战斗、技能检定结果等。 c. DM的响应再次更新游戏状态和场景。循环界面更新展示本轮所有玩家行动和DM的叙述游戏再次进入“等待下一回合”状态。实操心得Prompt是游戏的灵魂这个游戏的可玩性几乎完全取决于给DM和玩家AI的Prompt质量。原项目的Prompt可能比较基础。你可以通过修改game/agents/下的代码来优化Prompt。例如为DM的Prompt加入“请确保挑战的难度适中”、“每3个回合需要提供一个明确的剧情线索”等规则。为玩家AI的Prompt加入“你的决策必须符合你的角色背景例如一个贪财的游荡者会更关注宝藏”等约束。这是深度定制游戏体验的关键。5. 常见问题排查与性能优化技巧在实际运行中你可能会遇到以下问题5.1 应用启动失败或模型加载错误问题现象可能原因解决方案运行streamlit run app.py时报错提示连接Ollama失败1. Ollama服务未启动。2..env中的OLLAMA_API_ENDPOINT地址或端口错误。1. 新开终端运行ollama serve并确保无报错。2. 检查Ollama服务是否运行在默认的11434端口。可用命令curl http://localhost:11434/api/tags测试。在App界面中无法看到或选择模型1. 未成功拉取任何模型。2. 项目读取模型列表的代码有误。1. 在终端用ollama list确认已有模型。2. 检查应用内模型管理部分的代码看其是否调用Ollama的/api/tags接口成功。生成角色或进行回合时界面长时间转圈后报超时错误1. 模型太大硬件推理速度慢。2. Prompt过长或复杂导致生成时间超时。1. 换用更小的模型如7B。2. 在代码中如llm_client.py增加Ollama API调用的超时时间timeout参数。3. 简化Prompt。5.2 游戏逻辑与内容生成问题问题现象可能原因解决方案生成的角色信息混乱或无法解析LLM回复格式自由难以用简单规则解析。1. 优化character_generator.py中的解析逻辑使用更灵活的正则表达式或分步提取。2. 在Prompt中强制要求JSON格式输出并升级代码以支持JSON解析需模型支持。冒险剧情散漫缺乏目标DM智能体的Prompt缺乏方向性指引。修改dm_agent.py的Prompt加入明确的冒险主线或场景目标。例如“本次冒险的主题是‘寻找失落的神庙’。请始终围绕此主题推进剧情。”玩家AI行动重复或不合逻辑玩家智能体的Prompt未能充分体现角色差异化和当前上下文。1. 在player_agent.py的Prompt中更强调角色自身的背景、性格和职业特性。2. 在Prompt中提供更精简但关键的游戏历史上下文避免信息过载。游戏很快陷入循环或无聊状态缺乏外部刺激和状态变化。1. 在游戏状态GameState中引入更多变量如“队伍士气”、“资源食物、水”、“时间昼夜”并在DM的Prompt中让这些因素影响叙述。2. 设计随机事件表在特定回合由DM触发。5.3 性能优化与体验提升使用更高效的模型格式Ollama支持GGUF格式的模型。你可以从Hugging Face等平台下载特定量化等级如Q4_K_M的模型并用ollama create自定义模型通常在速度和效果间有更好的平衡。利用缓存Streamlit有缓存机制st.cache_data。可以将一些不常变化的数据如初始化的游戏规则、静态描述缓存起来减少重复计算和模型调用。实现“暂停”与“保存”原项目可能缺少游戏状态的保存/加载功能。你可以扩展GameState类使其能够序列化为JSON文件并保存到本地下次启动时再加载回来实现持续冒险。引入简单的规则引擎目前所有决策包括战斗胜负、技能检定都依赖LLM的“自由发挥”。可以引入一个简单的DD 5e规则引擎当DM描述涉及检定时后台实际进行一次掷骰计算并将结果注入给DM的Prompt使游戏更有“规则感”。例如在state.py中增加一个roll_dice(sides)方法并在DM生成描述前由逻辑层决定是否需要掷骰以及结果如何。这个项目就像一个乐高底座提供了本地LLM和多智能体交互的核心框架。真正的乐趣和挑战在于如何通过修改Prompt、扩展现有状态和逻辑来塑造出你心目中独一无二、生动有趣的AI地下城冒险。从简单的调整角色生成Prompt开始逐步尝试为DM添加更多叙事约束再到引入简单的游戏规则每一步的修改都能立刻在游戏中看到反馈这种即时成就感正是此类开源项目最大的魅力所在。