这次我们来看一个专门为桌面角色扮演游戏TTRPG设计的AI工具——Table Canon。它不是一个生成图像或语音的模型而是一个“战役记忆引擎”核心目标是利用大语言模型LLM来解决跑团过程中最头疼的问题信息遗忘和记录混乱。对于GM游戏主持人和玩家来说一场持续数周甚至数月的战役会产生海量的对话、角色、地点和事件。传统的手写笔记或零散的文档很难追溯和关联。Table Canon 正是为此而生它能够自动或半自动地整理游戏会话内容构建一个可查询、可追溯的“战役知识库”让整个游戏世界的历史清晰可见。本文将带你全面了解 Table Canon它的核心能力是什么、部署起来麻不麻烦、如何与你的实际游戏流程结合、以及作为开源项目它的扩展性如何。如果你是一名TTRPG爱好者或者对AI Agent、RAG检索增强生成在垂直领域的应用感兴趣这篇文章会提供从部署到实战的完整指南。1. 核心能力速览Table Canon 作为一个AI驱动的战役记忆引擎其价值不在于炫酷的生成能力而在于对非结构化游戏文本的智能理解与组织。下表概括了它的核心特性能力项说明项目类型AI应用 / 信息管理工具 / TTRPG辅助工具核心功能自动解析游戏会话记录提取实体角色、地点、物品等与关系构建可查询的知识图谱。技术栈基于大语言模型LLM结合检索增强生成RAG技术。部署方式本地部署推荐也可配置使用云端API。硬件门槛主要依赖LLM的推理能力。本地部署需考虑LLM的硬件需求显存/内存使用云端API则对本地硬件要求极低。输入形式游戏会话的文本记录如Discord聊天记录、笔记文档。输出形式结构化的知识库支持自然语言问答如“上周那个矮人铁匠提到了什么秘密”。是否开源是项目已在GitHub开源。适合场景长期运行的TTRPG战役管理GM的剧情筹备与回顾玩家的角色日志整理。简单来说你可以把它想象成一个专为跑团设计的“智能秘书”。你喂给它杂乱无章的聊天记录它帮你整理出谁是谁、发生了什么、东西在哪。这对于提升游戏沉浸感和叙事连贯性有巨大帮助。2. 适用场景与使用边界谁适合使用 Table Canon游戏主持人GM尤其是主持长线、复杂世界观战役的GM。可以用它快速回顾过往剧情确保NPC言行一致避免吃书剧情矛盾。深度角色扮演玩家希望为自己的角色撰写详细日志并与其他角色、事件建立关联的玩家。TTRPG社区或播客用于管理公开跑团活动的剧情档案方便观众或新成员了解故事背景。AI应用开发者作为一个将LLM与RAG技术应用于垂直领域游戏的典型案例具有很高的学习参考价值。它能解决什么问题信息碎片化游戏中的信息分散在多个会话、多个平台中。记忆负担重GM和玩家很难记住数月前发生的细节。检索效率低在成百上千条聊天记录中手动查找特定信息非常耗时。剧情连贯性挑战随着战役推进容易遗忘早期设定导致剧情出现漏洞。使用边界与注意事项并非游戏引擎Table Canon 不负责掷骰子、管理角色卡或生成地图。它是一个后台信息处理与检索工具。依赖输入质量其输出效果很大程度上取决于输入文本的质量。清晰、完整的会话记录能得到更好的分析结果。LLM的局限性知识提取可能受所用LLM的能力限制存在“幻觉”生成不准确信息的可能重要信息仍需人工复核。隐私考虑如果处理的是真实游戏群的聊天记录需注意隐私问题。建议在部署和使用时确保所有参与者知情并同意。版权与合规处理的内容应为原创或已获授权的游戏剧情避免输入受版权保护的第三方设定文本进行商用。3. 环境准备与前置条件在部署 Table Canon 之前你需要准备好以下环境。由于它是一个LLM应用核心在于为它配备一个“大脑”。3.1 基础软件环境操作系统推荐 Linux (Ubuntu 20.04) 或 macOS。Windows 可通过 WSL2 获得较好支持。Python版本 3.9 或 3.10。这是运行大多数AI框架的推荐版本。包管理工具pip或conda。版本控制git用于克隆项目仓库。3.2 LLM 引擎准备核心Table Canon 需要一个大语言模型来执行文本理解和生成任务。你有两种主要选择方案A使用本地LLM数据隐私性好但硬件要求高模型选择需要一款具有较强文本理解与摘要能力的开源模型如Llama 3、Mistral、Qwen系列。硬件要求GPU推荐显存大小取决于模型参数量。例如运行70亿参数7B的量化模型如GGUF格式可能需要8GB以上显存。更大的模型需要更多显存。CPU可以运行量化模型但推理速度会慢很多。需要足够的内存RAM通常模型大小的1.5倍以上。推理框架需要安装ollama、llama.cpp或vLLM等本地推理框架来加载和运行模型。方案B使用云端LLM API部署简单但涉及网络调用和费用API选择OpenAI GPT系列、Anthropic Claude、DeepSeek、智谱AI等。硬件要求本地只需能运行Python脚本的普通电脑即可。必要条件有效的API Key以及稳定的网络连接。3.3 Table Canon 项目本身获取代码从GitHub克隆项目仓库。磁盘空间预留至少几个GB的空间用于存放代码、依赖和可能的向量数据库。4. 安装部署与启动方式这里我们以本地部署并使用ollama运行本地LLM为例展示典型的安装流程。使用云端API的流程会更简单主要区别在于配置API Key。4.1 步骤一获取项目代码打开终端执行以下命令克隆项目git clone Table-Canon-项目GitHub地址 cd table-canon请将Table-Canon-项目GitHub地址替换为实际的仓库URL4.2 步骤二创建Python虚拟环境并安装依赖强烈建议使用虚拟环境隔离依赖。# 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate # 安装项目依赖通常通过 requirements.txt pip install -r requirements.txt如果项目没有提供requirements.txt你可能需要根据其文档手动安装langchain、chromadb或其它向量数据库、ollama的Python客户端等库。4.3 步骤三部署并启动本地LLM服务以Ollama为例安装Ollama访问Ollama官网根据你的操作系统下载并安装。拉取并运行模型在终端中运行以下命令拉取一个合适的模型。这里以llama3.2:1b一个较小的模型适合测试为例。ollama pull llama3.2:1b ollama run llama3.2:1b运行后Ollama会在本地启动一个API服务默认端口11434。保持这个终端运行。注意对于生产用途建议使用更大、能力更强的模型如llama3.2:3b、mistral或qwen2.5:7b但这需要更高的硬件资源。4.4 步骤四配置 Table Canon在项目目录下你需要找到一个配置文件可能是.env文件、config.yaml或config.py并配置LLM的连接信息。 例如创建一个.env文件# .env 文件示例 LLM_PROVIDERollama OLLAMA_BASE_URLhttp://localhost:11434 OLLAMA_MODELllama3.2:1b # 如果使用OpenAI API则配置如下 # LLM_PROVIDERopenai # OPENAI_API_KEYsk-your-api-key-here # OPENAI_MODELgpt-3.5-turbo # 向量数据库配置如果使用 VECTOR_DB_TYPEchromadb PERSIST_DIRECTORY./chroma_db4.5 步骤五启动 Table Canon 服务根据项目的设计它可能是一个Web UI服务也可能是一个命令行工具。假设它是一个Web服务启动命令可能类似于python app.py # 或 uvicorn main:app --reload --host 0.0.0.0 --port 8000启动成功后终端会显示访问地址例如http://127.0.0.1:8000。在浏览器中打开该地址即可进入Table Canon的操作界面。5. 功能测试与效果验证部署完成后我们需要验证Table Canon的核心工作流程是否顺畅。整个过程可以概括为导入会话 - 处理分析 - 知识查询。5.1 测试一导入游戏会话文本测试目的验证系统是否能正确接收并预处理原始文本。在Table Canon的Web界面中找到“导入”或“新增会话”功能。准备一份测试用的游戏会话文本。可以手动编写一小段例如[GM]你们走进了破旧旅店“沉睡巨人”。空气中有霉味和麦酒香。 [玩家-艾莉]我警惕地看了看四周问问酒保最近有没有生面孔。 [酒保-汤姆]擦着杯子生面孔除了你们就是楼上那位总锁着门的法师了。 [玩家-博德]法师他长什么样 [酒保-汤姆]裹着深蓝色斗篷很少下楼。对了他昨天打听过去古老矿坑的路。将文本粘贴或上传到系统。选择这次会话所属的战役例如“失落矿坑战役”。点击“导入”或“处理”。系统应提示导入成功并开始后台处理。5.2 测试二查看处理结果与知识提取测试目的验证LLM是否能从文本中正确提取实体和关系。处理完成后在界面中找到“知识库”、“实体”或“时间线”视图。检查系统是否自动识别出了以下信息实体地点-“沉睡巨人旅店”人物-“艾莉玩家”、“博德玩家”、“汤姆酒保”、“法师未命名”物品-“麦酒”地点-“古老矿坑”。关系/事件“法师”打听“古老矿坑”的路“法师”住在“沉睡巨人旅店”楼上。成功标准系统能够提取出关键名词并将其分类甚至能总结出简单的事件关系。提取的准确度取决于LLM的能力和文本的清晰度。5.3 测试三进行自然语言问答测试目的验证检索增强生成RAG流程是否工作即系统能否根据存储的知识回答问题。在界面的“问答”或“查询”框中输入基于测试文本的问题。简单事实查询“旅店的名字是什么”关联查询“谁提到了古老矿坑”推理查询可能更具挑战性“法师可能对什么感兴趣”查看系统返回的答案。理想情况答案准确引用原文信息例如“旅店叫‘沉睡巨人’。”、“酒保汤姆提到法师打听过去古老矿坑的路。”可接受情况答案基本正确但表述是生成的。需注意情况答案包含未在原文中出现的信息幻觉或完全答非所问。成功标准系统能基于导入的文本正确回答出文中明确提及的事实。对于推理性问题可以接受合理的推测但需标注不确定性。6. 接口 API 与批量任务对于希望将 Table Canon 集成到自己工具链如 Discord Bot、Notion 自动化的开发者其API能力至关重要。6.1 API 服务启动通常Table Canon 的Web后端本身就是一个API服务器。以上述uvicorn启动方式为例它已经提供了一个标准的FastAPI或类似框架的接口。你可以查阅项目的API文档通常是/docs或/redoc路径如http://127.0.0.1:8000/docs来查看所有可用端点。6.2 核心API调用示例假设项目提供了以下端点POST /api/session导入新的游戏会话。GET /api/entities获取所有实体。POST /api/query进行自然语言问答。以下是一个使用Pythonrequests库进行问答查询的示例import requests import json # Table Canon 服务地址 BASE_URL http://localhost:8000 # 查询请求 query_payload { campaign_id: lost-mine-of-phandelver, # 战役ID question: 旅店的名字是什么, use_context: True # 是否使用历史上下文 } try: response requests.post( f{BASE_URL}/api/query, jsonquery_payload, timeout30 ) response.raise_for_status() # 检查HTTP错误 result response.json() print(f问题{query_payload[question]}) print(f答案{result.get(answer, No answer found)}) print(f来源{result.get(sources, [])}) # 显示答案引用的原文片段 except requests.exceptions.RequestException as e: print(fAPI请求失败{e})6.3 批量任务处理对于有大量历史聊天记录需要导入的用户手动操作不现实。你需要编写脚本进行批量处理。批量导入脚本思路准备数据将历史记录整理成一个个文本文件或JSON文件每个文件代表一次游戏会话。遍历处理编写脚本循环读取每个文件调用POST /api/session接口进行导入。增加容错在脚本中加入错误处理和日志记录防止个别文件导入失败导致整个任务中断。控制速率如果使用云端API注意控制请求频率以避免触发限流。import os import requests import json import time BASE_URL http://localhost:8000 SESSIONS_DIR ./path/to/your/session_logs def import_session(file_path, campaign_id): with open(file_path, r, encodingutf-8) as f: content f.read() payload { campaign_id: campaign_id, session_text: content, session_date: os.path.basename(file_path)[:10] # 假设文件名包含日期 } try: resp requests.post(f{BASE_URL}/api/session, jsonpayload, timeout60) resp.raise_for_status() print(f成功导入{file_path}) return True except Exception as e: print(f导入失败 {file_path}: {e}) return False # 主循环 campaign_id my-epic-campaign for filename in os.listdir(SESSIONS_DIR): if filename.endswith(.txt): filepath os.path.join(SESSIONS_DIR, filename) success import_session(filepath, campaign_id) if not success: # 可以在这里加入重试逻辑 pass time.sleep(1) # 避免请求过于频繁7. 资源占用与性能观察Table Canon 的性能瓶颈主要在于LLM的推理部分以及向量数据库的检索部分。7.1 LLM 推理资源占用本地LLMOllama运行ollama run后可以使用nvidia-smiNVIDIA GPU或ollama ps命令查看资源占用。显存占用取决于模型大小和量化程度。一个7B参数的q4量化模型在推理时可能占用4-6GB显存。加载模型瞬间的峰值占用会更高。内存占用CPU模式下模型会完全加载到内存中占用与模型文件大小相当的内存。云端LLM API本地资源占用可忽略不计性能取决于网络延迟和API的响应速度。7.2 向量数据库资源占用Table Canon 使用向量数据库如ChromaDB来存储文本片段的嵌入向量以实现快速检索。这部分占用主要是磁盘空间和内存。对于数百万token的文本向量数据库可能占用几百MB到几GB的磁盘空间。查询时索引会被加载到内存中以加速检索。7.3 性能优化建议模型选择在效果和资源之间权衡。对于本地部署从较小的量化模型开始测试。文本分块在导入长文本时合理的分块策略如按对话轮次、按段落能提升检索精度和处理效率。需在项目配置中调整。异步处理对于批量导入任务应采用异步队列避免阻塞主线程。缓存机制对于常见查询可以考虑引入缓存避免重复调用LLM。8. 常见问题与排查方法在部署和使用过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案启动服务失败提示依赖错误Python环境不匹配或依赖包版本冲突。查看错误日志确认缺失的包或版本号。1. 确保使用虚拟环境。2. 检查requirements.txt尝试使用pip install -r requirements.txt --upgrade。3. 根据错误信息单独安装或降级特定包。导入会话后知识库为空或提取错误1. LLM服务未连接或模型未加载。2. 文本格式过于混乱LLM无法理解。3. API Key配置错误云端LLM。1. 检查LLM服务如Ollama是否在运行且端口正确。2. 查看项目后台日志确认LLM调用是否返回错误。3. 尝试输入一段结构清晰、简单的文本测试。1. 重启LLM服务确认模型名配置无误。2. 预处理输入文本尽量规范格式如明确标注[GM]、[玩家]。3. 核对云端API Key和模型名称。问答时返回“未找到相关信息”1. 向量数据库检索失败。2. 问题与存储的知识关联度太低。3. 检索返回的文本片段数量设置过少。1. 检查向量数据库目录是否存在且已初始化。2. 尝试一个在原文中明确存在答案的简单问题。3. 查看项目配置中关于检索“top_k”参数的设置。1. 重新导入会话数据重建向量数据库索引。2. 优化问题表述使其更接近原文用语。3. 适当增加检索返回的文本片段数量。问答答案出现“幻觉”编造信息这是LLM的固有问题当检索到的上下文不足或模糊时LLM倾向于生成看似合理但错误的内容。检查系统返回的“来源”片段看LLM是否基于错误的上下文生成答案。1. 在查询时要求系统同时返回引用的原文片段用于人工复核。2. 调整检索策略提高召回率。3. 在提示词Prompt中加强指令要求“严格基于上下文回答”。批量导入时进程卡死或内存溢出1. 单次导入文本过长。2. 内存/显存不足。3. 脚本未做错误处理导致死循环。1. 监控系统资源使用情况任务管理器、htop等。2. 查看应用日志看是否在某个文件处卡住。1. 对长文本进行分块处理分批导入。2. 升级硬件或使用更小的模型。3. 在批量脚本中加入超时和异常捕获机制。Web界面无法访问1. 服务未成功启动。2. 端口被占用。3. 防火墙阻止。1. 检查启动命令的终端是否有错误输出。2. 使用netstat -an | grep 端口号或lsof -i:端口号检查端口占用。3. 尝试用curl http://localhost:端口号测试本地连通性。1. 根据错误日志修复启动问题。2. 在启动命令中更换端口号如将8000改为8001。3. 配置防火墙允许该端口的入站连接。9. 最佳实践与使用建议为了让 Table Canon 更好地服务于你的游戏这里有一些实践建议会话记录规范化在游戏过程中鼓励或事后整理使用清晰的发言格式如[角色名]对话内容。这能极大提升实体提取的准确性。分战役管理为每个独立的战役创建不同的知识库空间避免信息交叉污染。定期维护知识库对于LLM提取错误的实体关系如果系统提供编辑功能进行手动修正。一个干净的知识库是高质量问答的基础。结合人工摘要在每次游戏结束后GM可以撰写一段简短的段落式摘要然后与原始聊天记录一起导入。摘要能提供更高层次、更准确的事件脉络。善用查询而非完全依赖将Table Canon视为一个强大的“记忆辅助”和“信息检索”工具而不是绝对权威。重要的剧情决策和设定仍应以GM的手稿为准。隐私与授权如果处理线上跑团的真实聊天记录务必在开始前告知所有参与者明确这些数据将用于AI分析并获得同意。备份数据定期备份你的向量数据库文件和项目配置。这些数据是独一无二的游戏记忆。10. 总结与下一步Table Canon 展示了一个非常具体的LLM应用场景将前沿的AI技术RAG融入传统的桌面角色扮演游戏解决了一个真实、普遍的痛点。它的价值不在于替代GM或玩家的创造力而在于充当一个不知疲倦的档案馆管理员让创作者们能从繁琐的信息管理中解放出来更专注于叙事和扮演。对于想要尝试的玩家或GM第一步不是追求完美部署而是快速验证核心流程用一小段精心编写的测试会话跑通“导入-提取-问答”的闭环。这能立刻让你感受到它的能力边界和潜力。最容易踩的坑主要集中在LLM的部署与配置上。如果本地硬件有限强烈建议先从云端API方案入手快速体验功能。待流程熟悉后再考虑本地化部署以追求更好的隐私性和可控性。下一步你可以探索深度集成将其与Discord Bot结合实现游戏过程中实时记录与查询。提示词工程优化系统提示词让LLM更准确地理解TTRPG领域的专有名词和叙事结构。扩展输出不限于问答尝试让系统自动生成本次游戏的“战报摘要”或“角色动态”。多模态探索如果未来支持将游戏地图图片、角色肖像与知识库关联构建更丰富的世界观档案。开源项目的魅力在于可扩展性。如果你有开发能力完全可以基于Table Canon的理念定制更适合自己游戏规则如COC、PF2e或社区需求的专属工具。这个项目提供了一个坚实的起点。 Table Canon：基于LLM与RAG的TTRPG战役记忆引擎部署与实战指南
这次我们来看一个专门为桌面角色扮演游戏TTRPG设计的AI工具——Table Canon。它不是一个生成图像或语音的模型而是一个“战役记忆引擎”核心目标是利用大语言模型LLM来解决跑团过程中最头疼的问题信息遗忘和记录混乱。对于GM游戏主持人和玩家来说一场持续数周甚至数月的战役会产生海量的对话、角色、地点和事件。传统的手写笔记或零散的文档很难追溯和关联。Table Canon 正是为此而生它能够自动或半自动地整理游戏会话内容构建一个可查询、可追溯的“战役知识库”让整个游戏世界的历史清晰可见。本文将带你全面了解 Table Canon它的核心能力是什么、部署起来麻不麻烦、如何与你的实际游戏流程结合、以及作为开源项目它的扩展性如何。如果你是一名TTRPG爱好者或者对AI Agent、RAG检索增强生成在垂直领域的应用感兴趣这篇文章会提供从部署到实战的完整指南。1. 核心能力速览Table Canon 作为一个AI驱动的战役记忆引擎其价值不在于炫酷的生成能力而在于对非结构化游戏文本的智能理解与组织。下表概括了它的核心特性能力项说明项目类型AI应用 / 信息管理工具 / TTRPG辅助工具核心功能自动解析游戏会话记录提取实体角色、地点、物品等与关系构建可查询的知识图谱。技术栈基于大语言模型LLM结合检索增强生成RAG技术。部署方式本地部署推荐也可配置使用云端API。硬件门槛主要依赖LLM的推理能力。本地部署需考虑LLM的硬件需求显存/内存使用云端API则对本地硬件要求极低。输入形式游戏会话的文本记录如Discord聊天记录、笔记文档。输出形式结构化的知识库支持自然语言问答如“上周那个矮人铁匠提到了什么秘密”。是否开源是项目已在GitHub开源。适合场景长期运行的TTRPG战役管理GM的剧情筹备与回顾玩家的角色日志整理。简单来说你可以把它想象成一个专为跑团设计的“智能秘书”。你喂给它杂乱无章的聊天记录它帮你整理出谁是谁、发生了什么、东西在哪。这对于提升游戏沉浸感和叙事连贯性有巨大帮助。2. 适用场景与使用边界谁适合使用 Table Canon游戏主持人GM尤其是主持长线、复杂世界观战役的GM。可以用它快速回顾过往剧情确保NPC言行一致避免吃书剧情矛盾。深度角色扮演玩家希望为自己的角色撰写详细日志并与其他角色、事件建立关联的玩家。TTRPG社区或播客用于管理公开跑团活动的剧情档案方便观众或新成员了解故事背景。AI应用开发者作为一个将LLM与RAG技术应用于垂直领域游戏的典型案例具有很高的学习参考价值。它能解决什么问题信息碎片化游戏中的信息分散在多个会话、多个平台中。记忆负担重GM和玩家很难记住数月前发生的细节。检索效率低在成百上千条聊天记录中手动查找特定信息非常耗时。剧情连贯性挑战随着战役推进容易遗忘早期设定导致剧情出现漏洞。使用边界与注意事项并非游戏引擎Table Canon 不负责掷骰子、管理角色卡或生成地图。它是一个后台信息处理与检索工具。依赖输入质量其输出效果很大程度上取决于输入文本的质量。清晰、完整的会话记录能得到更好的分析结果。LLM的局限性知识提取可能受所用LLM的能力限制存在“幻觉”生成不准确信息的可能重要信息仍需人工复核。隐私考虑如果处理的是真实游戏群的聊天记录需注意隐私问题。建议在部署和使用时确保所有参与者知情并同意。版权与合规处理的内容应为原创或已获授权的游戏剧情避免输入受版权保护的第三方设定文本进行商用。3. 环境准备与前置条件在部署 Table Canon 之前你需要准备好以下环境。由于它是一个LLM应用核心在于为它配备一个“大脑”。3.1 基础软件环境操作系统推荐 Linux (Ubuntu 20.04) 或 macOS。Windows 可通过 WSL2 获得较好支持。Python版本 3.9 或 3.10。这是运行大多数AI框架的推荐版本。包管理工具pip或conda。版本控制git用于克隆项目仓库。3.2 LLM 引擎准备核心Table Canon 需要一个大语言模型来执行文本理解和生成任务。你有两种主要选择方案A使用本地LLM数据隐私性好但硬件要求高模型选择需要一款具有较强文本理解与摘要能力的开源模型如Llama 3、Mistral、Qwen系列。硬件要求GPU推荐显存大小取决于模型参数量。例如运行70亿参数7B的量化模型如GGUF格式可能需要8GB以上显存。更大的模型需要更多显存。CPU可以运行量化模型但推理速度会慢很多。需要足够的内存RAM通常模型大小的1.5倍以上。推理框架需要安装ollama、llama.cpp或vLLM等本地推理框架来加载和运行模型。方案B使用云端LLM API部署简单但涉及网络调用和费用API选择OpenAI GPT系列、Anthropic Claude、DeepSeek、智谱AI等。硬件要求本地只需能运行Python脚本的普通电脑即可。必要条件有效的API Key以及稳定的网络连接。3.3 Table Canon 项目本身获取代码从GitHub克隆项目仓库。磁盘空间预留至少几个GB的空间用于存放代码、依赖和可能的向量数据库。4. 安装部署与启动方式这里我们以本地部署并使用ollama运行本地LLM为例展示典型的安装流程。使用云端API的流程会更简单主要区别在于配置API Key。4.1 步骤一获取项目代码打开终端执行以下命令克隆项目git clone Table-Canon-项目GitHub地址 cd table-canon请将Table-Canon-项目GitHub地址替换为实际的仓库URL4.2 步骤二创建Python虚拟环境并安装依赖强烈建议使用虚拟环境隔离依赖。# 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate # 安装项目依赖通常通过 requirements.txt pip install -r requirements.txt如果项目没有提供requirements.txt你可能需要根据其文档手动安装langchain、chromadb或其它向量数据库、ollama的Python客户端等库。4.3 步骤三部署并启动本地LLM服务以Ollama为例安装Ollama访问Ollama官网根据你的操作系统下载并安装。拉取并运行模型在终端中运行以下命令拉取一个合适的模型。这里以llama3.2:1b一个较小的模型适合测试为例。ollama pull llama3.2:1b ollama run llama3.2:1b运行后Ollama会在本地启动一个API服务默认端口11434。保持这个终端运行。注意对于生产用途建议使用更大、能力更强的模型如llama3.2:3b、mistral或qwen2.5:7b但这需要更高的硬件资源。4.4 步骤四配置 Table Canon在项目目录下你需要找到一个配置文件可能是.env文件、config.yaml或config.py并配置LLM的连接信息。 例如创建一个.env文件# .env 文件示例 LLM_PROVIDERollama OLLAMA_BASE_URLhttp://localhost:11434 OLLAMA_MODELllama3.2:1b # 如果使用OpenAI API则配置如下 # LLM_PROVIDERopenai # OPENAI_API_KEYsk-your-api-key-here # OPENAI_MODELgpt-3.5-turbo # 向量数据库配置如果使用 VECTOR_DB_TYPEchromadb PERSIST_DIRECTORY./chroma_db4.5 步骤五启动 Table Canon 服务根据项目的设计它可能是一个Web UI服务也可能是一个命令行工具。假设它是一个Web服务启动命令可能类似于python app.py # 或 uvicorn main:app --reload --host 0.0.0.0 --port 8000启动成功后终端会显示访问地址例如http://127.0.0.1:8000。在浏览器中打开该地址即可进入Table Canon的操作界面。5. 功能测试与效果验证部署完成后我们需要验证Table Canon的核心工作流程是否顺畅。整个过程可以概括为导入会话 - 处理分析 - 知识查询。5.1 测试一导入游戏会话文本测试目的验证系统是否能正确接收并预处理原始文本。在Table Canon的Web界面中找到“导入”或“新增会话”功能。准备一份测试用的游戏会话文本。可以手动编写一小段例如[GM]你们走进了破旧旅店“沉睡巨人”。空气中有霉味和麦酒香。 [玩家-艾莉]我警惕地看了看四周问问酒保最近有没有生面孔。 [酒保-汤姆]擦着杯子生面孔除了你们就是楼上那位总锁着门的法师了。 [玩家-博德]法师他长什么样 [酒保-汤姆]裹着深蓝色斗篷很少下楼。对了他昨天打听过去古老矿坑的路。将文本粘贴或上传到系统。选择这次会话所属的战役例如“失落矿坑战役”。点击“导入”或“处理”。系统应提示导入成功并开始后台处理。5.2 测试二查看处理结果与知识提取测试目的验证LLM是否能从文本中正确提取实体和关系。处理完成后在界面中找到“知识库”、“实体”或“时间线”视图。检查系统是否自动识别出了以下信息实体地点-“沉睡巨人旅店”人物-“艾莉玩家”、“博德玩家”、“汤姆酒保”、“法师未命名”物品-“麦酒”地点-“古老矿坑”。关系/事件“法师”打听“古老矿坑”的路“法师”住在“沉睡巨人旅店”楼上。成功标准系统能够提取出关键名词并将其分类甚至能总结出简单的事件关系。提取的准确度取决于LLM的能力和文本的清晰度。5.3 测试三进行自然语言问答测试目的验证检索增强生成RAG流程是否工作即系统能否根据存储的知识回答问题。在界面的“问答”或“查询”框中输入基于测试文本的问题。简单事实查询“旅店的名字是什么”关联查询“谁提到了古老矿坑”推理查询可能更具挑战性“法师可能对什么感兴趣”查看系统返回的答案。理想情况答案准确引用原文信息例如“旅店叫‘沉睡巨人’。”、“酒保汤姆提到法师打听过去古老矿坑的路。”可接受情况答案基本正确但表述是生成的。需注意情况答案包含未在原文中出现的信息幻觉或完全答非所问。成功标准系统能基于导入的文本正确回答出文中明确提及的事实。对于推理性问题可以接受合理的推测但需标注不确定性。6. 接口 API 与批量任务对于希望将 Table Canon 集成到自己工具链如 Discord Bot、Notion 自动化的开发者其API能力至关重要。6.1 API 服务启动通常Table Canon 的Web后端本身就是一个API服务器。以上述uvicorn启动方式为例它已经提供了一个标准的FastAPI或类似框架的接口。你可以查阅项目的API文档通常是/docs或/redoc路径如http://127.0.0.1:8000/docs来查看所有可用端点。6.2 核心API调用示例假设项目提供了以下端点POST /api/session导入新的游戏会话。GET /api/entities获取所有实体。POST /api/query进行自然语言问答。以下是一个使用Pythonrequests库进行问答查询的示例import requests import json # Table Canon 服务地址 BASE_URL http://localhost:8000 # 查询请求 query_payload { campaign_id: lost-mine-of-phandelver, # 战役ID question: 旅店的名字是什么, use_context: True # 是否使用历史上下文 } try: response requests.post( f{BASE_URL}/api/query, jsonquery_payload, timeout30 ) response.raise_for_status() # 检查HTTP错误 result response.json() print(f问题{query_payload[question]}) print(f答案{result.get(answer, No answer found)}) print(f来源{result.get(sources, [])}) # 显示答案引用的原文片段 except requests.exceptions.RequestException as e: print(fAPI请求失败{e})6.3 批量任务处理对于有大量历史聊天记录需要导入的用户手动操作不现实。你需要编写脚本进行批量处理。批量导入脚本思路准备数据将历史记录整理成一个个文本文件或JSON文件每个文件代表一次游戏会话。遍历处理编写脚本循环读取每个文件调用POST /api/session接口进行导入。增加容错在脚本中加入错误处理和日志记录防止个别文件导入失败导致整个任务中断。控制速率如果使用云端API注意控制请求频率以避免触发限流。import os import requests import json import time BASE_URL http://localhost:8000 SESSIONS_DIR ./path/to/your/session_logs def import_session(file_path, campaign_id): with open(file_path, r, encodingutf-8) as f: content f.read() payload { campaign_id: campaign_id, session_text: content, session_date: os.path.basename(file_path)[:10] # 假设文件名包含日期 } try: resp requests.post(f{BASE_URL}/api/session, jsonpayload, timeout60) resp.raise_for_status() print(f成功导入{file_path}) return True except Exception as e: print(f导入失败 {file_path}: {e}) return False # 主循环 campaign_id my-epic-campaign for filename in os.listdir(SESSIONS_DIR): if filename.endswith(.txt): filepath os.path.join(SESSIONS_DIR, filename) success import_session(filepath, campaign_id) if not success: # 可以在这里加入重试逻辑 pass time.sleep(1) # 避免请求过于频繁7. 资源占用与性能观察Table Canon 的性能瓶颈主要在于LLM的推理部分以及向量数据库的检索部分。7.1 LLM 推理资源占用本地LLMOllama运行ollama run后可以使用nvidia-smiNVIDIA GPU或ollama ps命令查看资源占用。显存占用取决于模型大小和量化程度。一个7B参数的q4量化模型在推理时可能占用4-6GB显存。加载模型瞬间的峰值占用会更高。内存占用CPU模式下模型会完全加载到内存中占用与模型文件大小相当的内存。云端LLM API本地资源占用可忽略不计性能取决于网络延迟和API的响应速度。7.2 向量数据库资源占用Table Canon 使用向量数据库如ChromaDB来存储文本片段的嵌入向量以实现快速检索。这部分占用主要是磁盘空间和内存。对于数百万token的文本向量数据库可能占用几百MB到几GB的磁盘空间。查询时索引会被加载到内存中以加速检索。7.3 性能优化建议模型选择在效果和资源之间权衡。对于本地部署从较小的量化模型开始测试。文本分块在导入长文本时合理的分块策略如按对话轮次、按段落能提升检索精度和处理效率。需在项目配置中调整。异步处理对于批量导入任务应采用异步队列避免阻塞主线程。缓存机制对于常见查询可以考虑引入缓存避免重复调用LLM。8. 常见问题与排查方法在部署和使用过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案启动服务失败提示依赖错误Python环境不匹配或依赖包版本冲突。查看错误日志确认缺失的包或版本号。1. 确保使用虚拟环境。2. 检查requirements.txt尝试使用pip install -r requirements.txt --upgrade。3. 根据错误信息单独安装或降级特定包。导入会话后知识库为空或提取错误1. LLM服务未连接或模型未加载。2. 文本格式过于混乱LLM无法理解。3. API Key配置错误云端LLM。1. 检查LLM服务如Ollama是否在运行且端口正确。2. 查看项目后台日志确认LLM调用是否返回错误。3. 尝试输入一段结构清晰、简单的文本测试。1. 重启LLM服务确认模型名配置无误。2. 预处理输入文本尽量规范格式如明确标注[GM]、[玩家]。3. 核对云端API Key和模型名称。问答时返回“未找到相关信息”1. 向量数据库检索失败。2. 问题与存储的知识关联度太低。3. 检索返回的文本片段数量设置过少。1. 检查向量数据库目录是否存在且已初始化。2. 尝试一个在原文中明确存在答案的简单问题。3. 查看项目配置中关于检索“top_k”参数的设置。1. 重新导入会话数据重建向量数据库索引。2. 优化问题表述使其更接近原文用语。3. 适当增加检索返回的文本片段数量。问答答案出现“幻觉”编造信息这是LLM的固有问题当检索到的上下文不足或模糊时LLM倾向于生成看似合理但错误的内容。检查系统返回的“来源”片段看LLM是否基于错误的上下文生成答案。1. 在查询时要求系统同时返回引用的原文片段用于人工复核。2. 调整检索策略提高召回率。3. 在提示词Prompt中加强指令要求“严格基于上下文回答”。批量导入时进程卡死或内存溢出1. 单次导入文本过长。2. 内存/显存不足。3. 脚本未做错误处理导致死循环。1. 监控系统资源使用情况任务管理器、htop等。2. 查看应用日志看是否在某个文件处卡住。1. 对长文本进行分块处理分批导入。2. 升级硬件或使用更小的模型。3. 在批量脚本中加入超时和异常捕获机制。Web界面无法访问1. 服务未成功启动。2. 端口被占用。3. 防火墙阻止。1. 检查启动命令的终端是否有错误输出。2. 使用netstat -an | grep 端口号或lsof -i:端口号检查端口占用。3. 尝试用curl http://localhost:端口号测试本地连通性。1. 根据错误日志修复启动问题。2. 在启动命令中更换端口号如将8000改为8001。3. 配置防火墙允许该端口的入站连接。9. 最佳实践与使用建议为了让 Table Canon 更好地服务于你的游戏这里有一些实践建议会话记录规范化在游戏过程中鼓励或事后整理使用清晰的发言格式如[角色名]对话内容。这能极大提升实体提取的准确性。分战役管理为每个独立的战役创建不同的知识库空间避免信息交叉污染。定期维护知识库对于LLM提取错误的实体关系如果系统提供编辑功能进行手动修正。一个干净的知识库是高质量问答的基础。结合人工摘要在每次游戏结束后GM可以撰写一段简短的段落式摘要然后与原始聊天记录一起导入。摘要能提供更高层次、更准确的事件脉络。善用查询而非完全依赖将Table Canon视为一个强大的“记忆辅助”和“信息检索”工具而不是绝对权威。重要的剧情决策和设定仍应以GM的手稿为准。隐私与授权如果处理线上跑团的真实聊天记录务必在开始前告知所有参与者明确这些数据将用于AI分析并获得同意。备份数据定期备份你的向量数据库文件和项目配置。这些数据是独一无二的游戏记忆。10. 总结与下一步Table Canon 展示了一个非常具体的LLM应用场景将前沿的AI技术RAG融入传统的桌面角色扮演游戏解决了一个真实、普遍的痛点。它的价值不在于替代GM或玩家的创造力而在于充当一个不知疲倦的档案馆管理员让创作者们能从繁琐的信息管理中解放出来更专注于叙事和扮演。对于想要尝试的玩家或GM第一步不是追求完美部署而是快速验证核心流程用一小段精心编写的测试会话跑通“导入-提取-问答”的闭环。这能立刻让你感受到它的能力边界和潜力。最容易踩的坑主要集中在LLM的部署与配置上。如果本地硬件有限强烈建议先从云端API方案入手快速体验功能。待流程熟悉后再考虑本地化部署以追求更好的隐私性和可控性。下一步你可以探索深度集成将其与Discord Bot结合实现游戏过程中实时记录与查询。提示词工程优化系统提示词让LLM更准确地理解TTRPG领域的专有名词和叙事结构。扩展输出不限于问答尝试让系统自动生成本次游戏的“战报摘要”或“角色动态”。多模态探索如果未来支持将游戏地图图片、角色肖像与知识库关联构建更丰富的世界观档案。开源项目的魅力在于可扩展性。如果你有开发能力完全可以基于Table Canon的理念定制更适合自己游戏规则如COC、PF2e或社区需求的专属工具。这个项目提供了一个坚实的起点。