# llm_sim：一个可观测的大语言模型内部行为模拟器

> 一个用于教育目的的Python项目，通过模块化的架构模拟大语言模型的完整推理流程，包括提示构建、分词、推理代理、工具调用和逐token生成，并提供完整的JSON执行轨迹可视化。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-03-28T12:44:38.000Z
- 最近活动: 2026-03-28T12:48:46.773Z
- 热度: 159.9
- 关键词: LLM, 教育工具, 模拟器, 可观测性, Python, token生成, 工具调用, 教学
- 页面链接: https://www.zingnex.cn/forum/thread/llm-sim
- Canonical: https://www.zingnex.cn/forum/thread/llm-sim
- Markdown 来源: ingested_event

---

# llm_sim：一个可观测的大语言模型内部行为模拟器\n\n## 项目概述\n\nllm_sim 是一个专为教育目的设计的Python项目，它并非追求真实的模型推理性能，而是专注于**清晰度和可观测性**。这个项目通过模块化的架构，完整模拟了大语言模型从接收用户输入到生成回复的整个内部流程。每一个中间步骤都被显式地记录到JSON轨迹文件中，用户可以通过Web界面或CLI工具深入探索模型的"思考过程"。\n\n这个项目的核心价值在于**透明化**——它让原本黑盒的LLM推理过程变得完全可见，非常适合用于教学、调试理解或架构学习。\n\n## 架构设计：高度解耦的模块化系统\n\nllm_sim 采用精心设计的模块化架构，每个组件只依赖于Trace数据类，而非直接相互依赖。这种设计带来了极高的可维护性和可扩展性：\n\n### 核心模块职责\n\n- **trace.py**：提供只追加的、JSON可序列化的执行轨迹记录\n- **prompt_builder.py**：将系统提示和用户输入组合成结构化提示模板\n- **tokenizer.py**：基于正则表达式的分词器，支持动态词汇表扩展\n- **llm_core.py**：核心的逐token生成逻辑，包含评分、softmax和采样\n- **tools.py**：提供安全的计算器工具和内存知识库搜索工具\n- **agent.py**：推理层，负责意图检测和工具调度\n- **pipeline.py**：顶层编排器，将所有组件串联起来\n\n### 关键设计决策\n\n1. **组件隔离**：LLMCore与Agent完全解耦，它只接收提示字符串和目标token列表\n2. **统一接口**：所有工具返回统一的ToolResult数据类，便于替换和扩展\n3. **动态词汇表**：分词器的词汇表是动态的，新token会被即时注册\n4. **完整可追溯**：每个决策、概率表和工具调用都被捕获到结构化JSON轨迹中\n\n## 模拟流程详解\n\n### 1. 提示构建阶段\n\nPromptBuilder将用户输入和固定的系统提示包装成带标签的模板格式，使用`[SYSTEM]`、`[USER]`、`[ASSISTANT]`等标记进行结构化分隔。这种设计模拟了真实LLM中常见的对话模板格式。\n\n### 2. 分词处理\n\nSimpleTokenizer使用正则表达式在空白和标点符号处分割文本，然后通过动态增长的词汇表字典将每个词形映射为整数ID。`encode()`和`decode()`互为精确逆操作，保证了编码解码的一致性。\n\n### 3. 推理代理与工具调用\n\nReasoningAgent应用两种启发式规则进行意图检测：\n\n- **数学计算检测**：如果查询包含算术表达式和触发词（如"calculate"、"what is"等），则调用CalculatorTool\n- **事实查询检测**：如果查询包含问题前缀（如"what is"、"explain"等），则调用FakeSearchTool查找内存知识库\n\n每个决策步骤都被显式记录，用户可以完整跟踪推理过程。\n\n### 4. 逐token生成机制\n\nLLMCore.generate()模拟了真实的token生成循环：\n\n- **候选采样**：为每个目标token抽取top_k个候选（目标token + 随机词汇表词汇）\n- **评分机制**：每个候选获得伪随机基础分数，加上重复惩罚（最近上下文窗口中已见的token被惩罚75%）\n- **目标增强**：目标token获得分数提升（×2.8），确保演示保持连贯性\n- **概率分布**：使用温度缩放的softmax将分数转换为概率分布\n- **完整透明**：完整的候选表（token、分数、概率）被记录到轨迹中\n\n### 5. 结果组装\n\nPipeline将工具输出（如有）与生成的文本组合成人类可读的最终答案。\n\n## 交互界面与可视化\n\n### Web界面（推荐方式）\n\nWeb UI提供了最直观的使用体验：\n\n1. 在浏览器中输入查询（或选择示例芯片）\n2. 观看六个管道阶段依次完成的动画效果\n3. 答案以颜色编码的药丸形式呈现，显示每个token的生成概率（🟢 ≥80%、🟡 50-80%、🔴 <50%）\n4. 点击"View Trace"按钮查看完整的执行轨迹\n\n### 执行轨迹查看器\n\n轨迹查看器提供了丰富的可视化功能：\n\n- 可折叠的步骤卡片，带有步骤类型图标\n- 颜色编码的JSON语法高亮\n- 内联概率条形图，直观展示生成步骤\n- 人类可读的推理轨迹（针对Agent步骤）\n- 过滤栏，可按名称筛选步骤\n- 支持拖放JSON文件\n\n### CLI工具\n\n对于快速测试和脚本化使用，CLI提供了简洁的替代方案：\n\n```bash\npython main.py \"What is 42 * 7 + 15?\"\npython main.py \"Explain the transformer architecture\"\n```\n\n执行后会将`llm_trace.json`写入项目根目录并打印最终答案。\n\n## 会话隔离与审计日志\n\n项目实现了严格的会话隔离机制：\n\n- 每个用户的执行轨迹存储在独立的数据目录中\n- `data/traces/`目录存储每个会话的执行轨迹（每个用户一个JSON文件）\n- `data/audit.jsonl`是只追加的JSONL审计日志，记录所有操作\n- 审计日志是私有的，无法从浏览器访问\n\n这种设计确保了多用户环境下的数据安全和操作可追溯性。\n\n## 部署与运行\n\n### 本地开发环境\n\n```bash\ncd llm_sim\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\npython server.py\n```\n\n### 生产环境（Gunicorn）\n\n```bash\ngunicorn --workers 4 --bind 127.0.0.1:5000 --timeout 120 server:app\n```\n\n### Docker部署\n\n项目提供了Dockerfile，支持容器化部署。\n\n## 教育价值与应用场景\n\nllm_sim 在多个场景下具有独特的教育价值：\n\n1. **教学演示**：向学生展示LLM内部工作原理，无需处理复杂的真实模型\n2. **架构学习**：通过阅读源码理解现代LLM的模块化设计思想\n3. **调试理解**：观察每个中间步骤的输出，理解模型"为什么"给出特定答案\n4. **原型验证**：在实现真实功能前，快速验证新的架构想法\n5. **安全研究**：理解工具调用和外部知识检索的安全边界\n\n## 总结与展望\n\nllm_sim 是一个精心设计的教学工具，它通过透明化的架构和完整的可视化能力，让大语言模型的内部工作机制变得触手可及。虽然它不追求真实的性能，但它在**可观测性**和**教育价值**方面达到了很高的水准。\n\n对于希望深入理解LLM工作原理的开发者、研究人员和学生来说，这是一个极佳的学习资源。项目的模块化设计也意味着它可以作为基础框架，进一步扩展支持更复杂的模拟功能。