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

llm_sim是专为教育目的设计的Python项目，通过模块化架构模拟大语言模型完整推理流程（含提示构建、分词、推理代理、工具调用、逐token生成），并提供JSON执行轨迹可视化。核心价值在于透明化LLM黑盒推理过程，适合教学、调试理解或架构学习。

真实大语言模型（LLM）推理过程通常是黑盒，难以直观理解内部机制。llm_sim并非追求真实模型性能，而是专注清晰度与可观测性，通过显式记录每一步中间过程到JSON轨迹文件，让用户能深入探索模型“思考过程”，帮助学习者理解LLM工作原理。

采用模块化架构，各组件仅依赖Trace数据类，可维护性与扩展性强。核心模块包括：trace.py（执行轨迹记录）、prompt_builder.py（提示模板组合）、tokenizer.py（动态词汇分词）、llm_core.py（逐token生成逻辑）、tools.py（计算器与知识库工具）、agent.py（推理层）、pipeline.py（顶层编排）。关键设计决策：组件隔离、统一接口、动态词汇表、完整可追溯。

1.提示构建：将系统提示与用户输入包装成带标签的结构化模板；2.分词处理：正则分割文本，动态词汇表映射为ID；3.推理代理：通过启发式规则检测意图（数学计算调用计算器，事实查询调用知识库）；4.逐token生成：候选采样、评分（含重复惩罚与目标增强）、温度缩放softmax、记录完整候选表；5.结果组装：组合工具输出与生成文本为最终答案。

提供三种交互方式：1.Web界面：动画展示管道阶段，颜色编码token生成概率，支持查看完整轨迹；2.轨迹查看器：可折叠步骤卡片、JSON语法高亮、内联概率条形图、推理轨迹可视化；3.CLI工具：快速测试脚本化使用，输出JSON轨迹文件与最终答案。

会话隔离机制确保多用户数据安全：每个用户轨迹存于独立目录，审计日志（audit.jsonl）记录所有操作且不可浏览器访问。部署方式：本地开发（venv+server.py）、生产环境（Gunicorn）、Docker容器化部署。

适用于多个场景：1.教学演示：展示LLM内部原理无需复杂真实模型；2.架构学习：通过源码理解模块化设计；3.调试理解：观察中间步骤理解答案生成原因；4.原型验证：快速验证新架构想法；5.安全研究：理解工具调用与知识检索安全边界。

llm_sim是精心设计的教学工具，以透明化架构与可视化能力让LLM内部机制触手可及，虽不追求真实性能，但在可观测性与教育价值上表现突出。对开发者、研究人员、学生是极佳学习资源，模块化设计可作为基础框架扩展更复杂模拟功能。