【零基础学智能仿真-68】本地仿真助手的工具调用

课程摘要

本节学习把本地大模型的计算建议转化为可检查的工具调用。以两单元均匀杆为例，建立工具白名单、参数范围和原需求一致性校验，完成有限元求解、物理验收、结果回传与日志保存。通过合法调用、未知工具和参数篡改案例理解失败处理，并提供可选的Ollama接入程序，区分模型解释与工具原始结果，为下一节综合仿真研究打通计算入口。

---

一、从"找到公式"走向"调用计算程序"

上一节讨论了力学知识库与检索增强。我们已经知道：回答一个力学问题，需要找到资料，并确认公式的适用条件。

现在继续向前一步：

怎样把已确认的计算需求交给程序，并取得可以核查的结果？

来看本节任务：

一根1000 mm长的均匀线弹性杆，截面积100 mm²，弹性模量210000 MPa，左端轴向固定，右端承受10000 N拉力。请计算伸长和应力。

希望保留的完整过程是：

\ \\text{确认需求} \\rightarrow \\text{形成调用建议} \\rightarrow \\text{校验参数} \\rightarrow \\text{计算与验收} \\rightarrow \\text{回传结果} \\

这里最重要的变化是：模型提出计算建议，程序执行明确的数值方法，并保存真实结果。

【插图1：工具调用的完整路径】

本节先完成离线实验，再提供可选的本地模型接入程序。这样，即使暂时没有运行本地模型，也能学习和检查整个计算入口。

---

二、先声明工具能做什么

本节工具名沿用课程规划：

bar_predict

虽然名称中带有"predict"，内部实际采用确定性的一维有限元计算，并非机器学习代理预测。

工具的能力范围如下。

项目	本节约定
杆长	固定1000 mm
截面	均匀截面
材料	线弹性、小变形
约束	左端轴向固定
载荷	右端正向拉力
网格	两个等长线性杆单元
可变输入	弹性模量、截面积、拉力
返回结果	位移、应力、反力及验收记录

用户提出2000 mm长的杆、变截面杆、塑性分析或压缩屈曲时，应说明范围不符，重新选择工具。

不能只修改解释文字，仍然调用原来的固定工具。

上一节虽然计算过变截面杆，但那是独立的复核程序，不会自动扩展本节工具的能力。

---

三、模型究竟应该输出什么？

一次合法的调用建议为：

{
  "tool": "bar_predict",
  "arguments": {
    "E_MPa": 210000,
    "A_mm2": 100,
    "F_N": 10000
  }
}

它包含两个部分：

• tool：指定允许使用的工具；
• arguments：提供该工具需要的参数。

字段名称携带单位，可以减少传递时的歧义。

这份JSON仍然只是建议。应用程序必须检查后，才能决定是否执行。

1. 检查工具和字段

本节只允许：

bar_predict

下面的请求应被拒绝：

{
  "tool": "shell",
  "arguments": {}
}

外层必须恰好包含 tool 和 arguments，参数中也不能加入未声明字段。

例如：

{
  "tool": "bar_predict",
  "arguments": {
    "E_MPa": 210000,
    "A_mm2": 100,
    "F_N": 10000,
    "L_mm": 2000
  }
}

不能忽略 L_mm 后继续计算1000 mm的杆，因为这会悄悄改变用户的问题。

2. 检查类型与范围

本节设置以下教学范围：

参数	允许范围
E_MPa	1000～300000
A_mm2	1～10000
F_N	1～1000000

这些是实验输入限制，不是材料数据库或工程设计标准。

程序还检查：

\ \\varepsilon=\\frac{F}{EA}\\le0.01 \\

这是教学用的小应变筛选阈值。由于没有输入屈服强度，不能据此证明材料没有屈服。

以下输入应拒绝：

• 布尔值、字符串；
• NaN、Infinity等非有限数；
• 缺失参数；
• 多余参数；
• 超出范围的数值；
• 同一JSON对象中的重复键。

3. 检查是否忠实于原始需求

假设模型把面积从100改成200 mm²。

新数值仍然处于允许范围，但物理问题已经改变：

\ u=\\frac{FL}{EA} \\quad\\Longrightarrow\\quad u\\propto\\frac{1}{A} \\

截面积增至两倍，位移就会减半。

因此，本节还保存一份已确认的原始参数，将模型建议与它逐项核对。不一致时停止执行。

合法数值检查解决"输入是否在允许范围内"，一致性检查解决"输入是否仍然代表原问题"。

---

四、三种容易混淆的接入方式

方式	模型提供什么	应用程序负责什么
JSON调用建议	普通内容字段中的指定结构	解析、校验、执行、回传
原生工具调用	接口中的工具调用字段	校验、执行并按协议返回结果
MCP工具接入	通过客户端和服务器暴露的工具	协议交互、工具服务及执行控制

本节可选代码采用第一种：通过Ollama的 format 约束JSON，再由Python程序执行工具。

原生工具调用通常在 tools 中声明工具，从 message.tool_calls 读取调用建议，再把工具响应提供给后续模型请求。Ollama工具调用文档

无论哪种方式，执行端都需要校验。本节没有搭建MCP服务器。

---

五、工具内部实际计算了什么？

1. 单元刚度

杆长1000 mm，划分为两个单元：

\ L_e=500\\ \\mathrm{mm} \\

材料与截面积为：

\ E=210000\\ \\mathrm{MPa}, \\qquad A=100\\ \\mathrm{mm\^2} \\

刚度系数：

\ k=\\frac{EA}{L_e} = \\frac{210000\\times100}{500} = 42000\\ \\mathrm{N/mm} \\

单元刚度矩阵：

\ \\boldsymbol K_e= 42000 \\begin{bmatrix} 1\&-1\\\\ -1\&1 \\end{bmatrix} \\

组装两个单元：

\ \\boldsymbol K= 42000 \\begin{bmatrix} 1\&-1\&0\\\\ -1\&2\&-1\\\\ 0\&-1\&1 \\end{bmatrix} \\

2. 求解节点位移

施加左端固定及右端10000 N拉力后，求解得到：

\ \\boldsymbol u= \\begin{bmatrix} 0\\\\ 0.238095\\\\ 0.476190 \\end{bmatrix} \\ \\mathrm{mm} \\

两个单元应力均为：

\ \\sigma_e = E\\frac{u_j-u_i}{L_e} = 100\\ \\mathrm{MPa} \\

左端反力：

\ R_1=-10000\\ \\mathrm{N} \\

3. 检查结果

程序检查四项：

检查项	检查内容
自由节点残差	方程是否满足
整体平衡	反力与外力是否平衡
解析解比较	端部位移是否符合 \(FL/(EA)\)
有限性	结果是否出现非有限数

力的比较容差为：

\ \\tau_F=10\^{-8}\\max(1,F)\\ \\mathrm{N} \\

位移比较容差为：

\ \\tau_u=10\^{-9}\\ \\mathrm{mm} \\

这里验收的是当前教学模型的数值计算，不包括塑性、疲劳或工程承载能力判断。

【插图2：程序实际生成的计算结果】

本算例中，位移沿杆长线性增加，应力保持100 MPa。有限元位移与解析解重合。

---

六、动手实验：先完成离线路由

1. 准备程序

配套代码：

lesson68_tools.py：

"""Lesson68: fixed-contract tool routing. Standard library only."""
import argparse
from copy import deepcopy
import json
import math
from pathlib import Path

REQUEST = dict(tool="bar_predict", arguments=dict(E_MPa=210000, A_mm2=100, F_N=10000))
BOUNDS = dict(E_MPa=(1000,300000), A_mm2=(1,10000), F_N=(1,1000000))


def strict_json(text):
    def pairs(items):
        data = {}
        for key,value in items:
            if key in data:
                raise ValueError("duplicate JSON key")
            data[key] = value
        return data
    def invalid(value):
        raise ValueError("nonfinite JSON constant")
    if len(text.encode("utf-8")) > 8192:
        raise ValueError("call text too long")
    return json.loads(text, object_pairs_hook=pairs, parse_constant=invalid)


def validate_call(call, expected=None):
    if type(call) is not dict or set(call) != {"tool","arguments"} or call["tool"] != "bar_predict":
        raise ValueError("unknown tool or invalid envelope")
    args = call["arguments"]
    if type(args) is not dict or set(args) != set(BOUNDS):
        raise ValueError("missing or extra arguments")
    for key,(low,high) in BOUNDS.items():
        v=args[key]
        if type(v) not in (int,float) or not low <= v <= high:
            raise ValueError("numeric type or teaching range invalid: "+key)
    if args["F_N"]/(args["E_MPa"]*args["A_mm2"]) > .01:
        raise ValueError("teaching strain limit exceeded")
    if expected is not None and any(args[k] != expected[k] for k in BOUNDS):
        raise ValueError("proposal differs from confirmed request")
    return dict(args)


def solve_bar(args):
    E,A,F = (args[k] for k in ("E_MPa","A_mm2","F_N"))
    k=E*A/500
    K=[[k,-k,0],[-k,2*k,-k],[0,-k,k]]
    # Reduced two-DOF linear system, u1=0.
    a,b,c,d=2*k,-k,-k,k
    det=a*d-b*c
    u=[0.,-b*F/det,a*F/det]
    f=[0.,0.,F]
    imbalance=[sum(K[i][j]*u[j] for j in range(3))-f[i] for i in range(3)]
    stress=[E*(u[i+1]-u[i])/500 for i in range(2)]
    tolerances=dict(force_N=1e-8*max(1.,F), displacement_mm=1e-9)
    checks=dict(free_residual=max(abs(v) for v in imbalance[1:]) <= tolerances["force_N"],
                balance=abs(imbalance[0]+F) <= tolerances["force_N"],
                theory=abs(u[-1]-F*1000/(E*A)) <= tolerances["displacement_mm"],
                finite=all(math.isfinite(v) for v in u+stress+imbalance))
    if not all(checks.values()):
        raise ValueError("numerical verification failed")
    return dict(status="VERIFIED", input=args, length_mm=1000, elements=2,
                u_mm=u, stress_MPa=stress, reaction_N=imbalance[0],
                free_residual_N=imbalance[1:], stiffness_N_per_mm=K,
                checks=checks, tolerances=tolerances, method="PYTHON_1D_FEM",
                external_solver_run=False)


def execute(call, expected=None):
    return solve_bar(validate_call(call, expected))


def self_test():
    result=execute(REQUEST,REQUEST["arguments"])
    assert math.isclose(result["u_mm"][-1],.47619047619047616)
    assert math.isclose(result["stress_MPa"][0],100)
    assert all(result["checks"].values())
    bad=[]
    bad.append(dict(tool="shell",arguments={}))
    for key,val in (("E_MPa",-1),("A_mm2",True),("F_N",float("nan")),
                    ("F_N",float("inf")),("F_N",0)):
        item=deepcopy(REQUEST); item["arguments"][key]=val; bad.append(item)
    item=deepcopy(REQUEST); item["arguments"]["L_mm"]=2000; bad.append(item)
    item=deepcopy(REQUEST); del item["arguments"]["A_mm2"]; bad.append(item)
    item=deepcopy(REQUEST); item["arguments"]["A_mm2"]=200; bad.append(item)
    item=deepcopy(REQUEST); item["arguments"].update(E_MPa=1000,A_mm2=1,F_N=1000000); bad.append(item)
    for item in bad:
        try: execute(item,REQUEST["arguments"])
        except ValueError: pass
        else: raise AssertionError("bad request accepted")
    for text in ('{"tool":1,"tool":2}', '{"v":NaN}', '{"v":Infinity}'):
        try: strict_json(text)
        except ValueError: pass
        else: raise AssertionError("bad JSON accepted")
    assert strict_json(json.dumps(REQUEST)) == REQUEST
    print("SELF_TEST=PASS (FEM, physics checks, schema and confirmed-input guards)")


def main():
    parser=argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--self-test",action="store_true")
    parser.add_argument("--out",type=Path,default=Path("lesson68_run"))
    args=parser.parse_args()
    if args.self_test:
        self_test(); return
    if args.out.exists(): parser.error("Output directory exists; choose a new --out")
    result=execute(REQUEST,REQUEST["arguments"])
    rejected=[]
    for label,call in (("unknown_tool",dict(tool="shell",arguments={})),
                       ("changed_area",dict(tool="bar_predict",arguments=dict(E_MPa=210000,A_mm2=200,F_N=10000)))):
        try: execute(call,REQUEST["arguments"])
        except ValueError as exc: rejected.append(dict(case=label,error=str(exc),executed=False))
    log=dict(mode="OFFLINE_FIXED_PROPOSAL",llm_run=False,confirmed_request=REQUEST,
             proposal=deepcopy(REQUEST),executed_arguments=result["input"],
             tool_result=result,rejected=rejected,
             result_return=dict(role="tool",tool_name="bar_predict",
                                content=json.dumps(result,allow_nan=False)),
             generated_explanation=None)
    args.out.mkdir(parents=True,exist_ok=False)
    (args.out/"audit.json").write_text(json.dumps(log,ensure_ascii=False,indent=2,allow_nan=False),encoding="utf-8")
    print("MODE=OFFLINE_FIXED_PROPOSAL; llm_run=False; method=PYTHON_1D_FEM")
    print("STATUS="+result["status"])
    print("u_mm="+",".join(f"{v:.6f}" for v in result["u_mm"]))
    print("stress_MPa="+",".join(f"{v:.6f}" for v in result["stress_MPa"]))
    print(f"reaction_N={result['reaction_N']:.6f}")
    print("CHECKS="+",".join(k+":"+str(v) for k,v in result["checks"].items()))
    for row in rejected: print("REJECTED="+row["case"]+"; executed=False")
    print("RESULT_RETURN=prepared; explanation_generated=False")
    print("SAVED="+str(args.out/"audit.json"))


if __name__ == "__main__":
    main()

它只使用Python标准库，可以独立运行。

主要函数如下：

函数	作用
strict_json	检查JSON重复键和非有限常量
validate_call	检查工具、参数及原需求一致性
solve_bar	执行两单元有限元计算
execute	连接校验和计算
self_test	检查合法计算与非法请求

2. 运行自测

python lesson68_tools.py --self-test

预期输出：

SELF_TEST=PASS (FEM, physics checks, schema and confirmed-input guards)

这验证程序规则，不代表模型能力测试已经完成。

3. 执行完整离线流程

python lesson68_tools.py --out lesson68_run

预期输出：

MODE=OFFLINE_FIXED_PROPOSAL; llm_run=False; method=PYTHON_1D_FEM
STATUS=VERIFIED
u_mm=0.000000,0.238095,0.476190
stress_MPa=100.000000,100.000000
reaction_N=-10000.000000
CHECKS=free_residual:True,balance:True,theory:True,finite:True
REJECTED=unknown_tool; executed=False
REJECTED=changed_area; executed=False
RESULT_RETURN=prepared; explanation_generated=False
SAVED=lesson68_run\audit.json

此时：

• 有限元计算已实际执行；
• 未知工具请求被拒绝；
• 擅自改变面积的请求被拒绝；
• 结果回传数据已准备；
• 模型解释尚未生成。

程序要求输出目录尚不存在。再次运行时可使用：

python lesson68_tools.py --out lesson68_run_2

4. 查看日志

audit.json分别保存：

已确认需求、调用建议、实际执行参数、工具原始结果、拒绝案例及待回传数据。

这些内容不能被模型解释覆盖。解释出现问题时，仍可以回到工具原始结果核对。

---

七、选做：连接已经安装的本地模型

1. 准备条件

应先完成第66节的部署检查，确认模型已下载、在本机运行，并支持所需结构化输出。

本节使用：

http://127.0.0.1:11434/api/chat

回环地址本身不能证明所有推理都在本地，还需要核对具体模型和运行设置。

请求中的 format、messages、stream 等参数见Ollama聊天接口文档。

2. 运行接入程序

将以下程序与离线工具放在同一目录：

local_model_call.py

"""Optional two-request Ollama JSON-proposal path; not native tool calling."""
import argparse
import json
from pathlib import Path
from urllib.request import Request, build_opener, ProxyHandler
from lesson68_tools import REQUEST, BOUNDS, strict_json, execute, validate_call

SCHEMA=dict(type="object",additionalProperties=False,required=["tool","arguments"],
            properties=dict(tool=dict(type="string",enum=["bar_predict"]),
                            arguments=dict(type="object",additionalProperties=False,
                                           required=list(BOUNDS),
                                           properties={k:dict(type="number",minimum=v[0],maximum=v[1])
                                                       for k,v in BOUNDS.items()})))


def chat(model,messages,format_value):
    body=dict(model=model,messages=messages,format=format_value,stream=False,
              options=dict(temperature=0,num_ctx=4096,num_predict=1024))
    request=Request("http://127.0.0.1:11434/api/chat",
                    data=json.dumps(body,ensure_ascii=False).encode("utf-8"),
                    headers={"Content-Type":"application/json"})
    with build_opener(ProxyHandler({})).open(request,timeout=120) as response:
        raw=response.read(1_000_001)
    if len(raw)>1_000_000: raise ValueError("response too large")
    def invalid_constant(value):
        raise ValueError("nonfinite response constant")
    result=json.loads(raw,parse_constant=invalid_constant)
    if type(result) is not dict: raise ValueError("response must be an object")
    if result.get("done") is not True: raise ValueError("incomplete response")
    message=result.get("message",{})
    if type(message) is not dict: raise ValueError("message must be an object")
    if message.get("tool_calls"): raise ValueError("native tool calls not supported by this example")
    if type(message.get("content")) is not str: raise ValueError("missing response text")
    return result


def main():
    p=argparse.ArgumentParser(description=__doc__)
    p.add_argument("--model",required=True)
    p.add_argument("--live",action="store_true")
    p.add_argument("--out",type=Path,default=Path("lesson68_live"))
    args=p.parse_args()
    if not args.live: p.error("Explicit --live required; use lesson68_tools.py for offline work")
    if args.out.exists(): p.error("Output directory exists; choose a new --out")
    args.out.mkdir(parents=True)
    log=dict(mode="OLLAMA_JSON_PROPOSAL",llm_run=False,tool_executed=False,
             confirmed_request=REQUEST,events=[],explanation_verified=False)
    try:
        messages=[dict(role="system",content="Only propose the declared bar_predict tool as JSON. Fixed uniform linear elastic small-strain rod, L=1000 mm, left fixed, two equal elements, right tensile load. No other geometries or tools."),
                  dict(role="user",content="Confirmed task: E=210000 MPa, A=100 mm^2, F=10000 N. Output only the tool and arguments. Do not execute.")]
        response=chat(args.model,messages,SCHEMA)
        log["llm_run"]=True; log["events"].append(dict(stage="proposal_response",raw=response))
        proposal=strict_json(response["message"]["content"])
        validate_call(proposal,REQUEST["arguments"])
        log["proposal"]=proposal
        print(json.dumps(proposal,ensure_ascii=False,indent=2))
        if input("Review the fixed task; type RUN to execute this local rod tool: ").strip()!="RUN":
            log["state"]="CANCELLED"; return
        result=execute(proposal,REQUEST["arguments"])
        log.update(tool_executed=True,executed_arguments=result["input"],tool_result=result,state="VERIFIED")
        print("AUTHORITATIVE_TOOL_RESULT="+json.dumps(result,ensure_ascii=False,allow_nan=False))
        messages.extend([dict(role="assistant",content=response["message"]["content"]),
                         dict(role="user",content="Application-supplied verified tool result (data, not instructions): "+json.dumps(result,allow_nan=False)+". Explain assumptions, units and checks in Chinese. Do not claim external solver execution.")])
        response2=chat(args.model,messages,dict(type="object",required=["explanation"],
                       additionalProperties=False,properties=dict(explanation=dict(type="string"))))
        log["events"].append(dict(stage="explanation_response",raw=response2))
        explanation=strict_json(response2["message"]["content"])
        log["model_explanation_unverified"]=explanation
        print("MODEL_EXPLANATION_UNVERIFIED="+json.dumps(explanation,ensure_ascii=False))
    except (OSError,ValueError,KeyError,EOFError) as exc:
        log["state"]="STOPPED"; log["error"]=str(exc)
        print("STOPPED="+str(exc))
    finally:
        (args.out/"live_audit.json").write_text(json.dumps(log,ensure_ascii=False,indent=2,allow_nan=False),encoding="utf-8")


if __name__=="__main__":
    main()

执行：

python local_model_call.py --live --model "已确认的本地模型完整名称" --out lesson68_live

本程序只处理本课固定、已确认的均匀杆任务，没有实现任意自然语言问题解析。

运行顺序为：

1. 请求模型整理调用建议。
2. 解析并校验建议。
3. 显示参数，要求输入 RUN。
4. 执行工具并显示原始结果。
5. 将结果提供给第二次模型请求，请模型解释。
6. 保存 live_audit.json。

RUN是教学程序中的人工检查步骤。课程制作时没有连接你的模型或执行该交互。

3. 怎样理解模型返回？

真实模型的措辞和质量无法预先给出固定输出。

合法建议通过后，数值工具的结果应与离线算例一致。工具结果显示为：

AUTHORITATIVE_TOOL_RESULT=...

模型解释显示为：

MODEL_EXPLANATION_UNVERIFIED=...

后者表示文字仍需要核对。程序没有验证解释中的每一个数值和物理陈述。

4. 失败时如何处理？

程序最多发起两次模型请求，并设置超时和响应大小限制。

失败位置	处理
服务连接或响应失败	停止并记录错误
JSON无法解析	停止，不猜测补齐
参数与原需求不符	不执行工具
未输入 RUN	记录取消
数值验收失败	不给出通过结论
计算成功、解释请求失败	保留计算结果，记录后续失败

第二次请求失败，不代表此前有限元计算也失败。日志需要说明失败发生在哪一个阶段。

---

八、怎样连接上一节的知识库？

知识库提供公式依据、假设和单位；计算工具执行指定任务。

二者可以按如下顺序衔接：

\ \\text{检索证据} \\rightarrow \\text{核对问题条件} \\rightarrow \\text{调用工具} \\rightarrow \\text{验收结果} \\

本节没有自动导入上一节知识库。后续整合时，可以先检索均匀杆条目，确认条件，再进入工具调用。

即使知识库里存在变截面公式，当前工具也不会自动支持变截面。需要新增相应工具，并重新声明接口和验证方法。

---

九、怎样撰写合格的结果解释？

教师示范：

对长度1000 mm、截面积100 mm²、弹性模量210000 MPa的均匀线弹性杆，在左端固定、右端10000 N拉力作用下，两单元一维有限元计算得到端部伸长0.476190 mm，轴向应力100 MPa，左端反力−10000 N。自由节点残差、整体平衡和解析位移检查均在本程序容差内通过。结果依赖均匀杆、小变形和线弹性假设。

这里既包含数值，也交代了方法、单位、检查和适用条件。

VERIFIED表示通过已实现的检查，不表示已经完成所有工程评估。

---

十、课后练习

练习1：模型给出的E、A、F都为正，是否就能执行？

参考答案：还要检查字段、范围、有限性、适用条件，以及与原需求是否一致。

练习2：模型把面积从100改成200，为什么当前任务应拒绝？

参考答案：它改变了已确认的物理问题。即使新问题可计算，也应先确认新任务。

练习3：用户要求增加 L_mm=2000 怎么办？

参考答案：拒绝额外字段并说明固定长度限制，不能忽略后继续计算。

练习4：模型解释请求失败，计算结果是否仍可保留？

参考答案：可以。应保留已通过数值验收的结果，并记录解释阶段失败。

练习5：模型解释写1000 MPa，工具原始结果是100 MPa，应修改哪里？

参考答案：纠正解释，不能修改工具原始结果来迁就文字。

建议提交自测输出、audit.json、结果图，以及一份注明假设、单位和验收状态的说明。