B4 LLM决策模块：验收讲解 —— 从基础到进阶的五维实践

个人 GitHub 仓库：https://github.com/xingwangzhe/B4-Agent-LLM

前文 Week2 五维升级实战 记录了全部开发过程，本文在此基础上按验收要求重新组织，侧重模块定位 → 基础实现 → 模块协作 → 进阶亮点 → 测试结果的讲解逻辑。

一、模块定位

1.1 一句话概括

B4 是 Agent 系统的 LLM 决策模块——整个系统的"大脑"。

它接收对话历史（messages）和工具说明（tools_schema），调用本地部署的 Qwen3.5-4B 模型，输出标准化的 AIMessage，决定"是否需要调用工具、调用哪个工具、传入什么参数"。

1.2 在系统中的位置

B4 属于 Agent 系统（B1-B5）中的决策层，上下关系如下：

flowchart TB
    subgraph "Agent 系统架构 (B1-B5)"
        direction TB
        B5["B5 记忆模块<br/>读取/保存记忆文档"]
        B1["B1 Runtime<br/>消息编排 + 循环控制"]
        B4["✅ B4 LLM 决策<br/>调用模型生成 AIMessage"]
        B3["B3 工具层<br/>生成 schema + 执行工具"]
        B2["B2 Skill<br/>具体工具函数"]
    end

    User["用户输入"] --> B1
    B1 --> B5
    B5 --> B1
    B1 --> B4
    B4 --> B1
    B1 --> B3
    B3 --> B2
    B2 --> B3
    B3 --> B1
    B1 --> Output["最终回答"]

    style B4 fill:#4CAF50,color:#fff,stroke:#333

1.3 核心数据流

1
B1 Runtime → 调用 B4.generate_ai_message(messages, tools_schema)
2
           → B4 加载模型 → 注入 messages + schema → LLM 推理
3
           → 解析原始输出 → 返回 AIMessage {content, tool_calls}
4
           → B1 判断是否有 tool_calls
5
             → 有：B3 执行 → ToolMessage → B1 追加消息 → 再次调 B4
6
             → 无：输出 final_answer

1.4 完成概况

二、基础功能实现

2.1 模型加载

从 model.yaml 读取配置，使用 transformers 加载 Qwen3.5-4B：

1
model:
2
    model_name_or_path: /root/assignment_B/Qwen3.5-4B
3
    torch_dtype: bfloat16
4
    device_map: auto
5

6
generation:
7
    max_new_tokens: 1024
8
    temperature: 0

1
# _load_model_config() 解析 YAML
2
# _load_model_bundle()  加载 tokenizer + model
3
config = read_yaml(model_config_path)
4
tokenizer = AutoTokenizer.from_pretrained(**config)
5
model = AutoModelForCausalLM.from_pretrained(**config)

2.2 tools_schema 绑定

B3 生成的工具说明通过 prompt 注入 方式嵌入系统消息：

1
# _build_prompt_messages() 将 tools_schema JSON 注入 prompt
2
system_prompt = read_prompt("local_tool_agent.txt")
3
system_prompt += "\n\nAvailable tools:\n" + json.dumps(tools_schema)
4
messages = [{"role": "system", "content": system_prompt}] + user_messages

2.3 AIMessage 生成与解析

模型原始输出是文本字符串，经过三层容错解析：

flowchart TB
    A["模型原始输出<br/>(文本字符串)"] --> B["json.loads()<br/>标准JSON解析"]
    B --> C{"解析成功？"}
    C -->|是| D["_candidate_to_message()<br/>→ 标准 AIMessage"]
    C -->|否| E["_extract_json_object()<br/>智能提取 JSON"]
    E --> F{"提取成功？"}
    F -->|是| D
    F -->|否| G["_parse_json_with_backtick_tail()<br/>_parse_tool_calls_fragment()<br/>容错回退"]
    G --> D

2.4 输出记录

每个运行案例保存两份 JSON 文件：

ai_message.json 输出示例（有工具调用时）：

1
{
2
    "role": "assistant",
3
    "content": "",
4
    "tool_calls": [
5
        {
6
            "id": "call_001",
7
            "name": "file_reader",
8
            "args": { "path": "docs/agent_intro.txt", "max_chars": 2000 }
9
        },
10
        {
11
            "id": "call_002",
12
            "name": "calculator",
13
            "args": { "expression": "3.14 * 5" }
14
        }
15
    ]
16
}

2.5 基本演示命令

1
cd code
2

3
# 无工具调用：模型直接回答
4
python b4_local_agent_llm.py \
5
  --model_config ../configs/model.yaml \
6
  --messages ../data/messages/messages_no_tool.json \
7
  --tools_schema ../data/messages/tools_schema_basic.json \
8
  --mode prompt_json --outdir ../outputs/B4_llm/no_tool_demo
9

10
# 有工具调用：生成 tool_calls
11
python b4_local_agent_llm.py \
12
  --model_config ../configs/model.yaml \
13
  --messages ../data/messages/messages_with_tool.json \
14
  --tools_schema ../data/messages/tools_schema_basic.json \
15
  --mode prompt_json --outdir ../outputs/B4_llm/with_tool_demo

三、与其他模块的交互

B4 在 Agent Loop 中承担"一次决策"的角色。

3.1 Agent Loop 完整流程

sequenceDiagram
    participant User as 用户
    participant B1 as B1 Runtime
    participant B5 as B5 记忆
    participant B4 as B4 LLM
    participant B3 as B3 工具层
    participant B2 as B2 Skill

    User->>B1: 提交问题
    B1->>B5: 查找记忆
    B5-->>B1: 返回 global/selected memory
    B1->>B4: generate_ai_message(messages, tools_schema)
    B4->>B4: 加载模型 → LLM 推理 → 解析 AIMessage
    B4-->>B1: 返回 AIMessage {content, tool_calls}

    B1->>B1: 判断是否有 tool_calls?

    alt 有 tool_calls
        B1->>B3: 执行 tool_calls
        B3->>B2: 调用对应 Skill
        B2-->>B3: 返回工具结果
        B3-->>B1: 返回 ToolMessage
        B1->>B1: 追加 AI + Tool 到 messages
        B1->>B4: 再次 generate_ai_message(完整 messages)
        B4-->>B1: 新 AIMessage
        B1->>B1: 再次判断...（循环直到无 tool_calls）
    else 无 tool_calls
        B1-->>User: 输出 final_answer
    end

    B1->>B5: 保存记忆（可选）

3.2 接口定义

B4 对外暴露的唯一接口：

1
def generate_ai_message(
2
    model_config: str,       # model.yaml 路径
3
    messages: list[dict],    # 消息序列
4
    tools_schema: list[dict],# 工具说明
5
    mode: str = "prompt_json",
6
    model_name: str = None,
7
    tool_calling: str = None,
8
) -> dict:                   # 标准 AIMessage

3.3 B4 不做什么

四、进阶功能详解

五项进阶要求全部完成，逐一说明。

4.1 进阶一：单轮多 tool_calls 与多 ToolMessage

为什么需要这个功能？

基础版本 prompt 写着 "Choose exactly one tool"，模型每轮只能生成一个 tool_call。但真实任务往往需要同时调用多个工具——比如"读取文件 同时 计算一个表达式 同时 搜索相关内容"。

改动本质：3 行 prompt 的变化

验证结果

flowchart TB
    subgraph "多 tool_calls 生成"
        A["messages<br/>(用户问题)"] --> B["B4 LLM"]
        B --> C["tool_calls[0]: file_reader"]
        B --> D["tool_calls[1]: calculator"]
        B --> E["tool_calls[2]: local_file_search"]
    end

    subgraph "多 ToolMessage 接收"
        C --> F["ToolMessage[0]: 文件内容"]
        D --> G["ToolMessage[1]: 计算结果"]
        E --> H["ToolMessage[2]: 搜索匹配"]
        F --> I["B4 LLM<br/>(再次调用)"]
        G --> I
        H --> I
        I --> J["最终回答:<br/>合并 3 个工具结果"]
    end

真实模型测试结果（Qwen3.5-4B）：

命令示例

1
cd code
2
python b4_local_agent_llm.py \
3
  --model_config ../configs/model.yaml \
4
  --messages ../data/messages/messages_multi_tool.json \
5
  --tools_schema ../data/messages/tools_schema_basic.json \
6
  --mode mock --outdir ../outputs/B4_llm/live_demo

输出 ai_message.json：

1
{
2
    "role": "assistant",
3
    "content": "",
4
    "tool_calls": [
5
        {
6
            "id": "call_001",
7
            "name": "file_reader",
8
            "args": { "path": "docs/agent_intro.txt", "max_chars": 2000 }
9
        },
10
        { "id": "call_002", "name": "local_file_search", "args": { "query": "Agent" } }
11
    ]
12
}

4.2 进阶二：Plan-and-Execute 模式

ReAct vs PlanEx

flowchart TB
    subgraph "ReAct 模式（基础）"
        direction TB
        R1["用户问题"] --> R2["LLM 决策"]
        R2 --> R3["Tool 1"]
        R3 --> R4["LLM 决策"]
        R4 --> R5["Tool 2"]
        R5 --> R6["LLM 决策"]
        R6 --> R7["最终回答"]
    end

    subgraph "Plan-and-Execute（进阶）"
        direction TB
        P1["用户问题"] --> P2["LLM 生成计划"]
        P2 --> P3["Plan: 3 步计划"]
        P3 --> P4["Step 1 → Tool 1"]
        P4 --> P5["Step 2 → Tool 2"]
        P5 --> P6["Step 3 → Tool 3"]
        P6 --> P7["最终回答"]
    end

双阶段流程

阶段 1 — Plan 生成：模型输出结构化计划，含 reasoning 和 plan 数组

真实模型生成的 2 步计划：

1
{
2
    "reasoning": "用户需要总结文档要点，同时了解搜索功能，最后计算示例。",
3
    "plan": [
4
        {
5
            "step": 1,
6
            "description": "读取 Agent 介绍文档",
7
            "tool_call": {
8
                "name": "file_reader",
9
                "args": { "path": "docs/agent_intro.txt", "max_chars": 2000 }
10
            }
11
        },
12
        {
13
            "step": 2,
14
            "description": "执行示例数学计算",
15
            "tool_call": {
16
                "name": "calculator",
17
                "args": { "expression": "3.14 * 5" }
18
            }
19
        }
20
    ]
21
}

阶段 2 — Execute：逐一执行计划步骤，全部完成后汇总结果

验证结果

命令示例

1
# 计划生成（Mock 模式输出 3 步计划）
2
cd code
3
python b4_local_agent_llm.py   --model_config ../configs/model.yaml   --messages ../data/messages/messages_plan_input.json   --tools_schema ../data/messages/tools_schema_basic.json   --mode plan_execute --outdir ../outputs/B4_llm/plan_live

输出 3 步计划（Mock 模式）：

1
{
2
  "role": "assistant",
3
  "content": "",
4
  "tool_calls": [
5
    {"name": "file_reader", "args": {"path": "docs/agent_intro.txt"}},
6
    {"name": "local_file_search", "args": {"query": "Agent", "root_dir": "docs"}},
7
    {"name": "calculator", "args": {"expression": "2 + 2"}}
8
  ]
9
}

1
# 步骤执行（接收工具结果后生成最终回答）
2
python b4_local_agent_llm.py   --model_config ../configs/model.yaml   --messages ../data/messages/messages_plan_with_results.json   --tools_schema ../data/messages/tools_schema_basic.json   --mode plan_execute --outdir ../outputs/B4_llm/plan_exec_live

输出最终回答：

1
{
2
    "role": "assistant",
3

4
    "content": "三条中文要点如下：\n1. Agent 系统通常由模型、工具、记忆和执行循环组成\n2. 工具调用让模型能够读取本地文件、执行计算\n3. Memory 为 Agent 提供全局知识和历史对话上下文",
5

6
    "tool_calls": []
7
}

4.3 进阶三：多模型切换

实现方式

在 model.yaml 中定义命名 profiles，通过 --model_name 参数选择：

1
models:
2
    qwen-4b:
3
        display_name: Qwen3.5-4B (standard)
4
        torch_dtype: bfloat16
5
        device_map: auto
6

7
    qwen-4b-fast:
8
        display_name: Qwen3.5-4B (fast mode)
9
        torch_dtype: float16
10
        max_new_tokens: 512

核心改动仅约 10 行代码：_load_model_config() 中按 model_name 选取 profile。

验证结果

命令示例

1
cd code
2
python b4_local_agent_llm.py \
3
  --model_config ../configs/model.yaml \
4
  --model_name qwen-4b \
5
  --messages ../data/messages/messages_no_tool.json \
6
  --tools_schema ../data/messages/tools_schema_basic.json \
7
  --mode mock --outdir ../outputs/B4_llm/switch_live

控制台输出 model: Qwen3.5-4B (standard)，Mock 模式不加载模型，仅验证模型名称配置正确。

1
# 切换 fast 模式
2
python b4_local_agent_llm.py \
3
  --model_config ../configs/model.yaml \
4
  --model_name qwen-4b-fast \
5
  --messages ../data/messages/messages_no_tool.json \
6
  --tools_schema ../data/messages/tools_schema_basic.json \
7
  --mode mock --outdir ../outputs/B4_llm/switch_fast_live

4.4 进阶四：tools_schema 传参方式对比

支持两种传参方式：prompt 注入（默认，JSON 格式输出）和 内置传参（通过 apply_chat_template 传入）。实测 prompt 注入方式在当前架构下更可靠，作为默认方案。

命令示例

1
# prompt 注入方式
2
cd code
3
python b4_local_agent_llm.py \
4
  --model_config ../configs/model.yaml \
5
  --messages ../data/messages/messages_with_tool.json \
6
  --tools_schema ../data/messages/tools_schema_basic.json \
7
  --tool_calling prompt_json \
8
  --mode mock --outdir ../outputs/B4_llm/schema_prompt
9

10
# 内置传参方式
11
python b4_local_agent_llm.py \
12
  --model_config ../configs/model.yaml \
13
  --messages ../data/messages/messages_with_tool.json \
14
  --tools_schema ../data/messages/tools_schema_basic.json \
15
  --tool_calling builtin \
16
  --mode mock --outdir ../outputs/B4_llm/schema_builtin

4.5 进阶五：批量基准测试与统计

测试框架

b4_batch_benchmark.py 自动遍历 bench_cases/ 目录，逐一调用 generate_ai_message() 并统计结果。

命令示例

1
cd code
2
python b4_batch_benchmark.py \
3
  --model_config ../configs/model.yaml \
4
  --cases_dir ../data/bench_cases \
5
  --tools_schema ../data/messages/tools_schema_basic.json \
6
  --mode mock --outdir ../outputs/B4_llm/bench_live

Mock 模式下 6 个场景全部通过，成功率 100%。

6 个测试场景

prompt_json 逐样例统计

各场景延迟统计

xychart-beta
    title "各测试场景延迟对比（ms）"
    x-axis ["file_read", "calculator", "file_search", "multi_tool", "direct_answer", "table_analyzer"]
    y-axis "延迟 (ms)" 0 --> 10000
    bar [1574.5, 9222.5, 3592.3, 7361.7, 769.7, 1724.8]

各场景 tool_calls 数量

xychart-beta
    title "各场景工具调用次数"
    x-axis ["file_read", "calculator", "file_search", "multi_tool", "direct_answer", "table_analyzer"]
    y-axis "tool_calls 数" 0 --> 4
    bar [1, 0, 1, 3, 0, 1]

传参方式对比

xychart-beta
    title "两种传参方式成功率对比"
    x-axis ["prompt_json", "builtin"]
    y-axis "成功率 (%)" 0 --> 100
    bar [83.3, 0]

失败的 calculator 用例 — 已修复

唯一失败的原因是模型同时输出了 content 和 tool_calls，违反互斥约束。

最新代码已修复：

1
# 当两者同时非空时，content 优先，清空 tool_calls
2
if content and tool_calls:
3
    tool_calls = []
4
    # 以 content 为最终回答

五、完成情况总览

5.1 基础要求

5.2 进阶要求

5.3 GitHub 仓库

个人仓库：https://github.com/xingwangzhe/B4-Agent-LLM

包含完整代码、配置、测试数据以及 22 个场景的运行结果。

参考