0-pydanticai-openai-comm-agent.py 代码说明

这份脚本和 6/2-prog/0-pydanticai-comm-agent.py 做的是同一件事：

• 调用本地 Ollama
• 使用 PydanticAI
• 让模型通过工具调用，解决一个通信领域的小问题

但这一版更重要的教学意义在于：

• 它更短
• 它更省事
• 它更能说明“接口兼容”为什么重要

因为这一次，我们不再自己写 Ollama /api/chat 适配层，而是直接使用：

• OpenAIChatModel
• OpenAIProvider

也就是说，只要新版 Ollama 的 /v1 OpenAI 兼容接口可用，很多中间翻译代码都可以省掉。

这份脚本整体在做什么

它的完整流程是：

1. 读取一个通信题目
2. 创建一个 PydanticAI Agent
3. 把本地 Ollama /v1 当成 OpenAI 兼容模型接进来
4. 注册两个工具函数
5. 让模型决定何时调用工具
6. 最后输出中文分析结果

和 6/2-prog 相比，最大的差别不是“任务变了”，而是：

• 接模型这一层变简单了

先看整体结构

这份代码可以分成 5 块：

1. 导入依赖
2. 定义默认题目
3. 清理代理环境
4. 创建 agent 和工具
5. 写命令行入口 main()

如果你对照 6/2-prog 去看，会发现这里少掉了一整大块：

• 没有手写消息格式翻译
• 没有手写 tool schema 翻译
• 没有手写 urllib 请求到 /api/chat
• 没有手写 FunctionModel 适配层

这正是这一版最值得理解的地方。

第一部分：导入依赖

from __future__ import annotations

这一行和前面一样，主要是为了让类型标注写起来更自然。

下面这些是标准库：

import argparse
import math
import os
import sys

它们分别做什么：

• argparse
  • 处理命令行参数
• math
  • 做路径损耗、噪声底、容量等数学计算
• os
  • 处理环境变量
• sys
  • 在报错时把信息输出到错误流

下面这些是 PydanticAI 相关导入：

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

这里最关键的两个新对象是：

• OpenAIChatModel
• OpenAIProvider

你可以先这样理解：

• OpenAIChatModel
  • 告诉 PydanticAI：我要接一个“OpenAI 风格的聊天模型”
• OpenAIProvider
  • 告诉 PydanticAI：这个模型具体在哪儿
  • 这里就是本地 Ollama /v1

第二部分：默认题目 DEFAULT_PROMPT

DEFAULT_PROMPT = (
    "请分析一个 2.4 GHz 校园无线链路..."
)

这一段和 6/2-prog 基本一样。

它给模型提供了：

• 频率
• 距离
• 发射功率
• 天线增益
• 其他损耗
• 带宽
• 噪声系数

并明确要求：

• 必须调用工具
• 尽量减少工具调用轮次
• 最后给出调制建议

这说明一个很重要的事情：

• 即使底层接口换了
• prompt 设计的重要性并没有变

第三部分：clear_proxy_env()

def clear_proxy_env() -> None:

这个函数仍然保留了下来。

为什么？

因为即使现在走的是：

http://localhost:11434/v1

它本质上仍然是本地网络请求。
如果电脑上开了代理，有时本地请求也会被代理干扰。

所以这里删掉了：

"http_proxy",
"https_proxy",
"HTTP_PROXY",
"HTTPS_PROXY",
"all_proxy",
"ALL_PROXY",

对初学者来说，可以记住这一点：

• 本地模型请求经常怕代理

第四部分：创建 agent

build_agent(model_name, base_url)

def build_agent(model_name: str, base_url: str) -> Agent[None, str]:

这个函数的作用是：

• 创建一个完整的 agent

输入参数有两个：

• model_name
  • 模型名，例如 qwen3.5:0.8b
• base_url
  • 本地 Ollama /v1 的地址

返回值：

• 一个 Agent

这里的类型：

Agent[None, str]

可以先简单理解成：

• 这个 agent 不额外依赖复杂外部上下文对象
• 最终输出是字符串

先清理代理

clear_proxy_env()

这一步和前面讲的一样，是为了保证本地 Ollama 访问稳定。

创建模型

model = OpenAIChatModel(
    model_name,
    provider=OpenAIProvider(
        base_url=base_url,
        api_key="ollama",
    ),
)

这是整份脚本里最关键、也最“省代码”的部分。

你可以把它拆成两层看。

第一层：OpenAIProvider(...)

OpenAIProvider(
    base_url=base_url,
    api_key="ollama",
)

这里的参数：

• base_url=base_url
  • 指定接口地址
  • 这里默认是：
  • http://localhost:11434/v1
• api_key="ollama"
  • 这里不是说一定有一个真实 API key
  • 而是 OpenAI 风格客户端通常要求这个字段非空
  • 对本地 Ollama 来说，给一个占位字符串就够了

第二层：OpenAIChatModel(...)

OpenAIChatModel(
    model_name,
    provider=...
)

意思是：

• 这个模型叫 qwen3.5:0.8b
• 它通过这个 provider 被访问

这几行的意义非常大，因为它意味着：

• PydanticAI 已经知道怎么和这个模型说话
• 不需要你再去自己拼 JSON 请求
• 也不需要你手写消息和工具的翻译器

为什么这一版比 6/2-prog 短这么多

因为在 6/2-prog 里，我们要自己做这些事：

• 把 PydanticAI 的消息翻译成 Ollama /api/chat 格式
• 把工具定义翻译成 tools schema
• 把 Ollama 的返回再翻译回 ModelResponse
• 自己构造 FunctionModel

而这一版里，这些都被：

• OpenAIChatModel
• OpenAIProvider

接管了。

也就是说：

• 接口一旦兼容，框架代码就会短很多

这就是为什么行业里大家一直很在意“OpenAI 兼容接口”。

创建 agent 本体

agent = Agent(
    model=model,
    system_prompt=(...),
    output_type=str,
)

这三项分别表示：

• model=model
  • 这个 agent 用哪个模型
• system_prompt=(...)
  • 给模型一组系统级规则
• output_type=str
  • 最后输出普通字符串

system_prompt 在这里做了什么

这里写了很多句子，其实每一句都在约束 agent 的行为：

• 你是一名通信系统助教
• 遇到可计算的问题时优先调用工具
• 尽量减少不必要轮次
• 优先使用 analyze_wireless_link
• 再使用 suggest_modulation
• 总结时必须严格使用工具返回数值
• 不要输出过长思考过程

这说明：

• system prompt 不是“备注”
• 它本身就是 agent 程序的一部分

第五部分：注册工具

@agent.tool_plain

当你看到：

@agent.tool_plain
def analyze_wireless_link(...):

它的意思是：

• 把下面这个普通 Python 函数
• 注册成 agent 可以调用的工具

这就是 PydanticAI 最适合教学的地方之一：

• 工具不是神秘对象
• 就是函数

工具一：analyze_wireless_link(...)

def analyze_wireless_link(
    frequency_ghz: float,
    distance_km: float,
    tx_power_dbm: float,
    tx_gain_dbi: float,
    rx_gain_dbi: float,
    other_loss_db: float,
    bandwidth_mhz: float,
    noise_figure_db: float,
) -> dict[str, float]:

这个函数一次性完成整个链路预算的主要计算。

为什么要这样设计？

因为对小模型来说：

• 工具拆得太细
• 容易多绕几轮
• 中间量也更容易弄错

所以这里用一个“大一点但仍然清楚”的工具，把这些量一次算出来：

• 路径损耗
• 接收功率
• 噪声底
• SNR
• Shannon 容量

逐行看里面的计算

路径损耗

path_loss = 92.45 + 20 * math.log10(frequency_ghz) + 20 * math.log10(distance_km)

这是自由空间路径损耗 FSPL 的常见形式。

含义是：

• 频率越高，损耗越大
• 距离越远，损耗越大

接收功率

received = tx_power_dbm + tx_gain_dbi + rx_gain_dbi - path_loss - other_loss_db

这就是一个简单的链路预算表达：

• 发射功率
• 加上两端增益
• 减去路径损耗
• 再减去其他损耗

带宽从 MHz 变成 Hz

bandwidth_hz = bandwidth_mhz * 1_000_000

因为后面的热噪声和容量公式都需要 Hz。

噪声底

noise = -174 + 10 * math.log10(bandwidth_hz) + noise_figure_db

这里：

• -174
  • 热噪声底近似值，单位是 dBm/Hz
• 10 * log10(bandwidth_hz)
  • 带宽越大，总噪声越高
• noise_figure_db
  • 接收机噪声系数

SNR

snr_value = received - noise

就是：

• 接收信号功率减去噪声底

Shannon 容量

capacity_bps = bandwidth_hz * math.log2(1 + 10 ** (snr_value / 10))

这里做了两件事：

1. 把 dB 的 SNR 变成线性值

10 ** (snr_value / 10)

2. 代入 Shannon 容量公式

C = Blog₂(1 + SNR)

返回结果

return {
    "path_loss_db": round(path_loss, 3),
    "received_power_dbm": round(received, 3),
    "noise_floor_dbm": round(noise, 3),
    "snr_db": round(snr_value, 3),
    "shannon_capacity_mbps": round(capacity_bps / 1_000_000, 3),
}

这里有两个关键点：

• round(..., 3)
  • 保留三位小数
• capacity_bps / 1_000_000
  • 把 bps 转成 Mbps

所以这个工具最后返回的是一个结构化字典。

而这正是 agent 喜欢的输入：

• 清楚
• 规整
• 容易继续用

工具二：suggest_modulation(snr_db_value)

def suggest_modulation(snr_db_value: float) -> str:

这个工具很简单：

• 输入 SNR
• 输出一个粗粒度的调制建议

逻辑是分段判断：

• 小于 6 dB
• 小于 12 dB
• 小于 18 dB
• 小于 24 dB
• 否则更高

这里的重点不是“这就是严格标准答案”，而是：

• 它是一个很适合课堂演示的简单工程规则

这也说明 agent 工具并不一定都很复杂：

• 很多时候它就是一个很清楚的小规则函数

第六部分：命令行入口 main()

创建参数解析器

parser = argparse.ArgumentParser(
    description="Run a minimal PydanticAI communications agent via Ollama /v1."
)

这一步是给脚本提供命令行接口。

--model

parser.add_argument(
    "--model",
    default="qwen3.5:0.8b",
    help="Local Ollama model name, default: qwen3.5:0.8b",
)

这个参数让你可以换模型名。

默认值是：

qwen3.5:0.8b

--base-url

parser.add_argument(
    "--base-url",
    default="http://localhost:11434/v1",
    help="Ollama OpenAI-compatible base URL, default: http://localhost:11434/v1",
)

这个参数非常关键，因为它正是这一版和 6/2-prog 的最大区别：

• 上一版走 /api/chat
• 这一版走 /v1

也就是说，这一行其实是在告诉学生：

• 只要底层服务提供 OpenAI 兼容接口
• 上层 agent 框架往往就能直接复用

--prompt

parser.add_argument(
    "--prompt",
    default=DEFAULT_PROMPT,
    help="User prompt for the communications agent",
)

这个参数让你可以从命令行换题目。

真正运行 agent

agent = build_agent(model_name=args.model, base_url=args.base_url)
result = agent.run_sync(args.prompt)

这两行就是主流程：

1. 创建 agent
2. 同步执行 prompt

这里的 run_sync(...) 可以先简单理解成：

• 直接跑
• 等结果出来

异常处理

except Exception as exc:
    print(f"Failed to run the agent: {exc}", file=sys.stderr)
    return 1

这一版的异常处理比 6/2-prog 更简单。

为什么？

因为这次很多底层网络细节已经交给：

• OpenAIProvider
• OpenAIChatModel

去处理了。

所以这也再次说明：

• 当接口兼容时
• 代码不仅更短
• 错误处理通常也会更简单

最后输出结果

print(result.output)
return 0

这里：

• result.output
  • agent 最后的文本结果
• return 0
  • 程序正常结束

最后这一句：

if __name__ == "__main__":
    raise SystemExit(main())

是标准 Python 脚本入口写法。

这份脚本和 6/2-prog 最值得对照看的地方

如果你要真正学会 agent 编程，最应该比较这两版：

6/2-prog

• 好处：
  • 你能看清 agent 和模型接口之间到底发生了什么
  • 更适合深挖底层机制
• 代价：
  • 代码更长
  • 需要自己写适配层

6/3-prog

• 好处：
  • 代码更短
  • 上手更快
  • 更像真实工程里“优先复用兼容接口”的做法
• 代价：
  • 你看不到那么多底层细节
  • 更依赖 /v1 接口本身稳定可用

所以课堂上最值得学生带走的一点是：

• 协议兼容不是小事
• 它会直接决定你上层 agent 代码到底是 50 行，还是 200 行

这份脚本最该带走什么

1. PydanticAI 的工具注册方式没有变
2. 通信工具函数本身也没有变
3. 变化最大的，是模型接入层
4. /v1 一旦兼容，OpenAIProvider 会让代码明显简化
5. 这就是为什么工程里大家很在意“统一接口”

如果继续往下升级

这份脚本后面可以继续扩成：

• 加 notebook 代码说明
• 加结构化输出模型
• 加多轮对话
• 加 memory
• 加 Langfuse tracing
• 接 MCP 工具

这样它就能从“最小 demo”逐步长成一个更完整的 agent 系统。