慕雪的寒舍

【2026】新年快乐！

2026-01-02T09:15:27.000Z

2025，可以算是人生中体感过得最快的一年，也是人生中非常重要的一年。

从这年开始，慕雪彻底告别了校园，告别了十余年的学生时代，踏入了工作岗位，迎来未知的挑战。

从此以后，再也听不到宿舍开黑的笑语，再也没有长长的寒暑假，也再也不会有人和你一起承担期末复习周的压力——出了校园，一切都靠自己。

之前在网上看到过这样一句话：好好珍惜自己的学生时代，因为只有学生时代，你的努力，才是能被你的成绩量化的。进入社会和工作后，再也没有稳定的量化指标，你的任何努力，都可能会是竹篮打水一场空，得不到任何结果。

“What’s happened’s happened. Which is an expression of faith in the mechanics of the world. It’s not an excuse to do nothing.”^[1]

This is reality.

希望能一切顺利，健康安稳。

愿2026，更加美好！

2026，新年快乐！

电影《信条》中男二尼尔在最后道别时对男主说的话：“木已成舟。这是对世间运行法则的一份笃定，而非不作为的借口。” ↩︎

【Mac】解决MacBook WiFi玄学问题“连上WiFI但是没网络”的折腾经历

2025-12-21T12:59:33.000Z

问题出现

因为之前一直用的是一个老的WiFi 5路由器，链接的设备比较多，感觉网速不太稳定，就新买了个WiFi 7路由器（TP-Link的BE3600）。结果没想到，遇到了MacBook的"玄学"问题，让我折腾了将近两个周末的时间……

刚路由器设置好，用MacBook连上WiFi，一切正常。毕竟只是换个路由器，用的也是光猫拨号（没有设置光猫桥接模式），本来就不太可能出现啥问题。但是用了几天就发现了一个问题，每次链接WiFi之后，大约过了10分钟，Mac就上不了网了，具体表现为：WiFi显示正常连接，但就是上不了网。

排查思路

问题出现了自然是要想办法解决，首先自然是这个新路由器自己是不是有点毛病。但考虑到我的windows电脑也连着这个WiFi连续打了很久的在线游戏，都没有遇到过掉包或者断网的问题，手机连着看视频啥的都正常，那大概率不是路由器自己的毛病了。

所以，问题就回到了Mac身上。

最容易想到的就是代理导致的，于是关闭代理软件，清除所有代理设置——问题依旧。

到这里我就没啥招了，暂时也不想重装系统，于是上苹果线下售后看了看，检测了硬件都是良好的。其实硬件没问题也是意料之中，不然怎么解释刚连上5G的时候能上网？硬件要是真有问题大概率是一开始就连不上这WiFi。

苹果线下售后的服务态度是真不错，就是人也是真的多，活像🏥挂号。预约的天才吧（是叫这个名字吧？）16点，最后快17点了才轮到我。

售后工程师给了个方案，就是在网络设置里面新建一个“环境”，然后切到这个新的环境去用。当时这样操作之后，网络就正常了。连续用Ping测试了40分钟都没有断网，感觉问题搞定了，于是回家。

当时售后也说了，如果这样弄还搞不定，就要考虑重装系统了

回家之后，用了几天，发现问题又来了……如法炮制又新建了一个“网络环境”，切过去还是无济于事。于是就备份资料，进入恢复模式，格式化硬盘，重置系统。

家里有个移动硬盘，平时文件整理习惯也好，所有资料都在一个data文件夹里面，把自己的数据都拷贝出去，直接重装系统就行了，唯一难受的就是得重新配开发环境。

重置系统之后，不装代理，继续使用了几个小时……问题又来了！！！！

问题解决

前面那些方法全都没搞定，本来都要放弃治疗了，无意之中想到了最后一个可能性：Mac和这个路由器不兼容！

抱着试一试的心态，我进路由器的App，把原来合并的5GHz/2.4GHz WiFi分开了：

原来是一个统一的名字，路由器和设备自动选择频段
改成两个独立的WiFi：XXX_5G和XXX_2.4G

然后让MacBook专门连接2.4GHz的那个WiFi。

奇迹发生了！连接2.4GHz WiFi后，再也没有出现过"WiFi连接正常但无网络"的问题。连续使用了好几天，网络一直稳定得不行。

不过说实话，2.4G的网速是真的慢的要死，相同位置的windows台式（和WiFi隔了一堵墙），主板内置的WiFi7的网卡，能跑满宽带300mbps的速度。但连2.4G WiFi的mac只有区区50mbps，有点可怜了。

好在我用mac多是办公娱乐为主，对网速要求并没有那么高，相比于天天整断网这一出，50mbps也勉强够用了。

写在最后

这次的"WiFi玄学问题"真的让我折腾了好久。从最开始怀疑梯子、怀疑mac自己硬件有问题，到重装系统，最后才发现是路由器不兼容的问题，真是无语了。谁能想到那么贵一苹果电脑还能和WiFi有兼容性问题……

就是不知道，如果买个小路由器当AP连主路由器，再用网线连Mac，是不是能解决网络不稳定的问题？相当于拿这个路由器当外置WiFi网卡用。

咱也没试过，毕竟整这一出还得给mac买个有网口的扩展坞，成本也不低（主要是效果未知）

注：本文记录的是个人遇到的问题和解决方案，具体问题可能因设备型号和环境不同而有所差异。

【AI】智谱AutoGLM部署教程：AutoDL云服务器+本地PhoneAgent配置

2025-12-10T14:18:52.000Z

1. 引言

开源地址：https://github.com/zai-org/Open-AutoGLM

一般情况下呢，这里得要介绍一下这个模型，背景信息啊，什么什么的。但慕雪最近很忙没时间写，直接跳过步入正题吧！

总而言之言而总之，这是智谱在25年12月9日开源的，一个专门为手机UI自动化操作开发的大模型，在今年早些时候AutoGLM的手机App就已经上线并可以通过里面的云端虚拟手机进行测试。现在，智谱把模型和本地Agent框架PhoneAgent一并开源，让我们可以自己部署AutoGLM并将其运用到各类UI自动化操作上。

因为是自部署的，数据都在你本地，也就不用担心大模型云端操作的隐私泄露问题了。

2. AutoDL部署AutoGLM模型

2.1. 创建镜像

AutoDL：https://www.autodl.com/home

根据官方在issue里面的回复，AutoGLM模型使用24G显存勉强可以运行，但实际上会占用27G的显存+共享内存，所以，需要在AutoDL上选一个32GB或48GB显存的服务器，cuda版本为12.8以上的，镜像选择PyTorch 2.8.0、Python 3.12(ubuntu22.04)、CUDA 12.8，就可以了。

创建镜像并开机之后，可以用ssh工具连这个服务器，也可以直接用控制台里面的jupyterLab链接，jupyterLab本身就带了终端持久运行的能力，不再需要我们安装tmux等其他守护进程工具了。

2.2. 下载模型

因为AutoDL是境内服务器，所以推荐去阿里的魔搭社区上下载模型：https://modelscope.cn/models/ZhipuAI/AutoGLM-Phone-9B

下载方式在魔搭社区上也有教程，执行如下命令即可。注意，在AutoDL上一定要进入/root/autodl-tmp数据盘进行操作，否则模型会直接把系统盘塞满，影响系统运行了。

1
2
3

pip install modelscope
# 下载模型到本地，注意一定要有--local_dir参数
modelscope download --model ZhipuAI/AutoGLM-Phone-9B --local_dir /root/autodl-tmp/autoglm-phone-9b

模型大约20GB，在AutoDL上下载大概需要半个小时，耐心等待一下吧。

2.3. 配置vllm运行环境

等待模型下载期间也别闲着，开另外一个终端配置一下vllm的运行环境。

AutoGLM依赖于vllm 0.12.0和transformers 5.0.0rc0，我们可以创建一个conda环境来安装。

vllm 0.12.0在官方release中说明强依赖pytorch 3.9.0和cuda 12.9，但实测在AutoDL的cuda 12.8的环境里面是能可以正常运行无报错的。

执行如下命令，创建一个conda虚拟环境

# 创建虚拟环境
conda create -n vllm python=3.12 -y
# 初始化
conda init

首次执行完毕conda init之后，会提示你开另外一个新终端，开一个新终端之后，执行如下命令

1
2
3

conda init
# 激活刚刚创建的虚拟环境
conda activate vllm

执行完毕后，我们就已经进入刚刚新创建的虚拟环境里面了，执行下面两个命令即可。AutoDL的镜像已经默认设置了阿里pypi源，不需要我们修改镜像源了。

1 2	pip install vllm==0.12.0 # 一定要先安装这个 pip install transformers==5.0.0rc0

注意，一定需要先安装vllm，然后再安装transformers^[1]，安装transformers==5.0.0rc0的时候会出现依赖不匹配的报错，因为vllm 0.12.0依赖的是4.x版本的transformers。可以直接忽略这个依赖版本不匹配的报错，智谱官方在issue里面提到了是能够兼容的，实测也确实OK。

其实不安装transformers==5.0.0rc0我也试过，模型也能运行，似乎也没啥问题。但是控制台会有加载解析器正则错误的告警，估计这就是截图里面提到的“新写法”导致的问题了。所以还是老实安装升级吧！

安装完毕这俩库之后，环境就搞定了，可以运行模型了！（当然得等模型下完了才行）

2.4. 运行模型

使用AutoGLM仓库里面给出的vllm命令，运行模型。注意这个命令需要修改我们下载好的模型本地路径，和端口号。AutoDL平台上只有6006和6008端口号是被映射到公网上的，其他端口号都不能使用。

另外，AutoDL租用的服务器提供外网服务需进行实名认证，请确保你的大模型服务不会被滥用生成违规违禁内容，避免罪责到你身上。

# 修改最后的--model模型本地路径和--port绑定端口号
python3 -m vllm.entrypoints.openai.api_server \
     --served-model-name autoglm-phone-9b \
     --allowed-local-media-path /   \
     --mm-encoder-tp-mode data \
     --mm_processor_cache_type shm \
     --mm_processor_kwargs "{\"max_pixels\":5000000}" \
     --max-model-len 25480  \
     --chat-template-content-format string \
     --limit-mm-per-prompt "{\"image\":10}" \
     --model /root/autodl-tmp/autoglm-phone-9b \
     --port 6006

执行这个命令后，vllm就会开始运行并加载模型，出现服务已上线，就是模型加载成功了。

回到控制台，点击自定义服务

把这里的6006端口号映射的URL复制一份，输入到浏览器里面。如果出现json的返回信息，且终端里面出现了请求日志，那就是模型服务部署成功了！

2.5. 完整模型加载日志

完整的模型加载日志

【Agent.10】OpenAI接口输出格式约束（response_format）

2025-11-30T13:00:00.000Z

欢迎阅读慕雪撰写的AI Agent专栏，本专栏目录如下

本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。

1. 引言

Agent专栏已经写到LangChain部分了，突然想起来，还遗漏了一个重要的OpenAI接口提供的特性没有使用：结果response_format的格式化输出。

在一般情况下，AI输出的都是自然语言，和我们人类输入的信息一样。在一般的问答Agent场景中，输出自然语言是OK的，但当我们希望使用AI来生成测试用例、分析报告、数据总结等等信息的时候，就会需要AI输出结构化的数据，这样我们才能进行有效的解析和后处理。

在继续阅读本文之前，你需要对序列化、反序列化概念有所了解，并知晓json序列化协议的基本结构。

举个最简单的例子：当我们需要AI输出针对需求的测试用例时，如果AI使用的是自然语言输出，如“链接网络，打开手机APP，点击播放视频的按钮，确认视频能正常播放”，我们就没有办法对这个测试用例进行有效拆分，从而提取出前置条件、测试步骤、预期结果。

但如果我们要求AI以json格式输出这些信息，解析这个测试用例就很容易了，比如要求AI按如下格式输出：

{
    "preStep": ["链接网络"],
    "testStep":["打开手机APP","点击播放视频的按钮"],
    "expectation":["视频能正常播放"]
}

有了这个json，我们想解析前置步骤、测试步骤、预期结果就非常简单了，直接对json进行反序列化（如python里面的json.loads）就可以加载到这串结构化的数据，进行后续的其他处理了。

2. 怎么约束输出格式？

理解了这个背景后，想必你已经知道为啥需要让AI结构化输出信息了。那要怎么做呢？

最简单的做法，就是在Prompt里面新增输出格式的要求，让AI遵循我们的要求，直接在回答里面输出json或其他可序列化的格式（xml、yaml），然后我们对返回的string进行解析，得到最终的结构化数据。

但是，这样做有非常大的弊端：

AI可能因为幻觉，不按我们预定的格式进行输出：现在的AI对Prompt遵循性相比半年之前有显著提升，这个问题出现次数减少了。
AI可能会在输出中包含其他说明文字：这个问题至今依旧没有解决，AI总是喜欢给你加点其他说明，即便Prompt里面多次说明“禁止包含其他信息”
AI可能使用markdown代码块包裹信息输出，而不是只输出结构化数据：需要我们处理返回值里面的markdown代码块

所以，OpenAI提供了json_schema格式化输出的约定字段，可以要求AI依照预定的response_format进行输出。

注意，这个字段依赖于OpenAI服务提供商对response_format支持，如果你使用的是第三方服务商提供的OpenAI兼容API，需要查看该服务商的文档，确认其支持response_format字段。目前轨迹流动是支持的，而美团的LongCat就不支持（不会遵循response_format）。

测试方式也比较简单，用本文给出的response_format设置代码去测试请求一次就能看出来AI是否有遵循response_format了。

3. 使用json_schema限定AI输出格式

使用openai的python sdk，我们可以直接在创建会话的时候，传入response_format字段对返回值进行格式控制。

代码如下所示，我们希望AI格式化解析用户提供的购物清单，精准输出购买商品的名字name、数量quantity、单位unit。

在response_format的设置中，"type": "array"代表items是一个json的list，"type": "object"则代表是一个json的对象（对应python的dict）。给定的name/quantity/unit这三个字段都是required必填字段，"strict": True则是要求AI必须严格遵循这个结构进行输出。

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv(override=True)

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "")
OPENAI_BASE_URL = os.getenv("OPENAI_BASE_URL", "https://api.siliconflow.cn/v1")
OPENAI_MODEL = os.getenv("OPENAI_MODEL", "Qwen/Qwen3-8B")

client = OpenAI(
    api_key=OPENAI_API_KEY,
    base_url=OPENAI_BASE_URL
)


def parse_shopping_list_with_schema(user_input: str):
    """使用JSON Schema解析购物清单"""
    response = client.chat.completions.create(
        model=OPENAI_MODEL,
        messages=[
            {"role": "system", "content": "解析用户输入的购物清单，生成结构化数据"},
            {"role": "user", "content": user_input}
        ],
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": "shopping_list",
                "schema": {
                    "type": "object",
                    "properties": {
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "name": {"type": "string"},
                                    "quantity": {"type": "integer"},
                                    "unit": {"type": "string"}
                                },
                                "required": ["name", "quantity", "unit"]
                            }
                        }
                    },
                    "required": ["items"],
                    "strict": True
                }
            }
        }
    )
    
    return response.choices[0].message.content

其他更复杂的格式都是在这套的基础上进行扩展，可把你的需要直接发送给编程AI助手，让他根据你的需要生成对应的json格式要求就可以了。

4. 效果对比

4.1. 使用Prompt限定代码

作为对比，这里提供了一份使用Prompt限定输出格式的OpenAI调用

def parse_shopping_list_with_prompt(user_input: str):
    """使用prompt限定格式解析购物清单"""
    system_prompt = """你是一个购物清单解析助手。请解析用户的购物清单，并严格按照以下JSON格式返回：

{
  "items": [
    {
      "name": "商品名称",
      "quantity": 数量,
      "unit": "单位"
    }
  ]
}

要求：
1. 必须返回有效的JSON格式
2. name字段为字符串类型
3. quantity字段为整数类型
4. unit字段为字符串类型
5. 所有字段都是必需的
6. 不要添加任何额外的文字说明，只返回JSON
7. 不要使用markdown代码块格式
"""

    response = client.chat.completions.create(
        model=OPENAI_MODEL,
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_input}
        ],
        temperature=0.1 # 温度越低AI回答越不容易跑偏
    )
    
    return response.choices[0].message.content

4.2. 测试结果

测试使用硅基流动的Qwen/Qwen3-8B模型

使用“我买了苹果5斤，牛奶2箱，面包3个”进行测试，可以看到，Qwen/Qwen3-8B对这种简单任务的Prompt遵循性还不错，不管是使用response_format还是使用Prompt的方式进行指定，都按照我们的要求进行输出了，且没有提供任何的说明文字。但Qwen/Qwen3-8B还是输出了markdown代码块包裹了这个json（Prompt里面要求不要使用）

测试用例 1:
用户输入: 我买了苹果5斤，牛奶2箱，面包3个

==================================================
1. 使用JSON Schema方法:
{"items": [{"name": "苹果", "quantity": 5, "unit": "斤"}, {"name": "牛奶", "quantity": 2, "unit": "箱"}, {"name": "面包", "quantity": 3, "unit": "个"}]}

------------------------------
2. 使用prompt限定格式方法:
```json
{
  "items": [
    {
      "name": "苹果",
      "quantity": 5,
      "unit": "斤"
    },
    {
      "name": "牛奶",
      "quantity": 2,
      "unit": "箱"
    },
    {
      "name": "面包",
      "quantity": 3,
      "unit": "个"
    }
  ]
}
```

相同一次运行里面的其他输入，他又可能不会输出markdown代码块（AI幻觉导致）

测试用例 3:
用户输入: 可乐2瓶，薯片5包，巧克力4块

==================================================
1. 使用JSON Schema方法:
{
  "items": [
    {
      "name": "可乐",
      "quantity": 2,
      "unit": "瓶"
    },
    {
      "name": "薯片",
      "quantity": 5,
      "unit": "包"
    },
    {
      "name": "巧克力",
      "quantity": 4,
      "unit": "块"
    }
  ]
}

------------------------------
2. 使用prompt限定格式方法:
{
  "items": [
    {
      "name": "可乐",
      "quantity": 2,
      "unit": "瓶"
    },
    {
      "name": "薯片",
      "quantity": 5,
      "unit": "包"
    },
    {
      "name": "巧克力",
      "quantity": 4,
      "unit": "块"
    }
  ]
}

因此可见，如果使用的OpenAI服务提供商支持response_format，使用response_format来控制AI输出结构是更好的方式，同时也避免我们去过多调试“约束AI生成数据结构”的Prompt了。

5. 从AI回答里面精准提取json字符串

不过呢，输出markdown代码块是一个小问题了，我们可以很轻松地编写一个json提取函数，从AI的输出里面精准提取出完整的json来，只要AI输出的json没有断。

如果你不想自己实现，可以使用pypi上已有的解析器：JsonExtractor

在很多场景下都可以使用这个json对AI的输出进行处理（即便提供了response_format也可以使用这个函数先处理一下），保证我们后续节点一定能得到一个有效的json结构。

import json
import re
from typing import Union

def extract_json_with_regex(response_str: str) -> Union[dict,list]:
    """
    使用算法从字符串中精准提取唯一的完整JSON
    
    Args:
        response_str: 包含JSON的原始回答字符串
        
    Returns:
        dict/list: 解析后的JSON对象或数组，无法解析时返回None
    """
    # 先直接进行一次json处理，失败了再往后走
    try:
        return json.loads(response_str)
    except json.JSONDecodeError as e:
        pass  # 第一次可能失败，不对异常做任何处理
    
    # 步骤1：移除Markdown代码块标记（```json、```等）
    response_str = re.sub(r'```(?:json)?\s*|\s*```', '', response_str, flags=re.IGNORECASE)
    
    # 步骤2：使用改进的算法提取JSON，支持嵌套结构
    # 由于Python re不支持递归，使用平衡括号算法
    matches = []
    
    # 提取JSON对象和数组
    for i, char in enumerate(response_str):
        if char == '{':
            json_str = _extract_balanced(response_str, i, '{', '}')
            if json_str:
                matches.append(json_str)
        elif char == '[':
            json_str = _extract_balanced(response_str, i, '[', ']')
            if json_str:
                matches.append(json_str)
    
    # 步骤3：没有找到匹配，直接返回None
    if not matches:
        return None
    
    # 取最长匹配（避免截取不完整的嵌套结构）
    json_str = max(matches, key=len).strip()
    
    # 尝试逐步清理尾部可能的无效字符
    while json_str and json_str[-1] not in '}]':
        json_str = json_str[:-1].strip()
        if json_str and json_str[-1] in ',;':
            json_str = json_str[:-1].strip()
    
    try:
        return json.loads(json_str)
    except json.JSONDecodeError as e:
        print(f"JSON解析失败：{str(e)}\n提取的内容：{json_str}")
        return None

def _extract_balanced(text: str, start_idx: int, open_char: str, close_char: str) -> str:
    """
    提取平衡的括号内容
    
    Args:
        text: 源文本
        start_idx: 起始位置（必须是开括号）
        open_char: 开括号字符
        close_char: 闭括号字符
        
    Returns:
        str: 平衡的括号内容，如果无法平衡则返回None
    """
    if text[start_idx] != open_char:
        return None
    
    stack = 1
    in_string = False
    escape_next = False
    
    for i in range(start_idx + 1, len(text)):
        char = text[i]
        
        # 处理字符串中的转义字符
        if escape_next:
            escape_next = False
            continue
            
        if char == '\\' and in_string:
            escape_next = True
            continue
            
        # 处理字符串开始和结束
        if char == '"' and not escape_next:
            in_string = not in_string
            continue
            
        # 只在非字符串状态下计算括号
        if not in_string:
            if char == open_char:
                stack += 1
            elif char == close_char:
                stack -= 1
                if stack == 0:
                    return text[start_idx:i+1]
    
    # 无法平衡，返回None
    return None

当然，这个函数没办法处理AI输出的json的结构不对的情况（比如缺key、key的名字不对、结构错乱等问题），只能保证剔除回答里面的其他无效信息，解析出一个有效的json。

同时，这个函数也不能支持回答里面有多个独立的json的情况。不推荐让AI输出多个独立的json，如果有多个独立json输出的要求，请使用一个大的json，用key包含这些json进行输出，比如指定多个大key来保存独立的json

{
    "key1": {},
    "key2": {},
    ...
}

6. The end

本文介绍了如何在调用OpenAI接口的时候约束AI的输出结构。

这个场景几乎是AI Agent开发里面最常见的场景，即便我们后续使用LangChain SDK，也一样会遇到需要要求AI输出结构化数据的场景。因此了解如何控制AI输出格式化数据，是Agent开发必备的能力。

【Agent.09】LangChain里面使用MCP工具

2025-11-30T08:50:00.000Z

欢迎阅读慕雪撰写的AI Agent专栏，本专栏目录如下

本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。

在上一篇文章中，我们学习了LangChain的基础用法和如何创建简单的Agent。本文将说明如何在LangChain中集成MCP（Model Context Protocol）工具。

本文有使用AI辅助编写

1. 什么是MCP？

MCP的介绍请移步MCP协议博客，本文不多介绍这个协议的原理。

简而言之，MCP就是在各个Agent SDK所支持的Function Calling上抽象了一层中间层，让这些Function有了一个外部统一调用和处理的协议，从而让我们的各类Tools只需要使用MCP协议编写出一个server，就可以在各个支持MCP的client里面无缝使用，不再需要针对目标工具、SDK做单独的二次工具开发，大大节省了工具兼容的开发时间。

当然，如果你的工具是Python函数，不涉及到任何兼容逻辑，也不打算切换你的Agent框架的时候，也可以不使用MCP。MCP只是提供了方便，并不代表我们的工具能力就一定要用MCP协议来编写。

在上一个Demo里面，我们使用了LangChain成功调用了直接在python里面实现的tools，本文将介绍如何在LangChain中集成MCP工具，顺带介绍如何使用fastmcp库编写MCP的server。

2. 创建MCP服务器

2.1. 环境准备

首先需要安装MCP相关的依赖，第一个是用于编写MCP服务器的库，第二个是LangChain里面的MCP客户端实现。

1	pip install fastmcp langchain-mcp-adapters

如果你使用的是uv，则使用uv add添加这些依赖。

2.2. 创建数学计算服务器

本次Demo使用一个比较简单的数学服务器作为演示。

创建一个名为01.math_server.py的文件：

from mcp.server.fastmcp import FastMCP

# 创建MCP服务器实例，"Math"是服务器名称
mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Multiply two numbers"""
    return a * b

if __name__ == "__main__":
    mcp.run(transport="stdio")

就是这么短短的几行代码，我们就已经写好了一个MCP服务器了。MCP服务器的启动方式分为两种，一个是stdio（字节流），另外一个是sse（远程）。关于sse协议，在本站也有博客详解。这里为了方便，使用了stdio协议。

同理，FastMCP框架也会使用python函数的lint和docstring来作为工具的desc，方便Agent理解工具的作用。

如果你使用的是Anthopic官方提供的MCP Python SDK，则还有另外一套更加全面的MCP服务端编写方式，支持自定义的字段更多，但编写也更加复杂。如果没有特殊需要，直接使用FastMCP就可以了，直接在原本的函数上加上一个@mcp.tool()装饰器，就能把普通的函数变成MCP Server的Tools，非常方便。

2.3. 测试MCP服务器

我们可以直接运行这个服务器来测试：

1	uv run mcp/01.math_server.py

服务器启动后会等待MCP客户端的连接，终端里面啥都不会输出。只要你观测到终端没有报错，阻塞运行了，那就说明server已经正常启动了。

3. 在LangChain中使用MCP工具

现在让我们在LangChain中集成我们刚创建的MCP工具。

继续阅读后续代码之前，请对python的await和aysnc的概念有一定了解，参考本站：python的异步和同步

3.1. 完整集成代码

import asyncio
import os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from dotenv import load_dotenv

# 加载环境变量
load_dotenv(override=True)


async def main():
    # 连接到 MCP 服务器
    client = MultiServerMCPClient({
        "math": {
            "transport": "stdio",  # 使用stdio传输协议
            "command": "uv",      # 启动命令
            "args": ["--directory", "mcp", "run", "01.math_server.py"],
        }
    })

    # 配置模型
    model = init_chat_model(
        model=os.getenv("OPENAI_MODEL"),
        model_provider="openai",
        api_key=os.getenv("OPENAI_API_KEY"),
        base_url=os.getenv("OPENAI_BASE_URL")
    )

    # 获取 MCP 服务器提供的工具
    tools = await client.get_tools()

    # 创建 Agent
    agent = create_agent(model=model, tools=tools)

    # 调用 Agent
    result = await agent.ainvoke(
        {"messages": [{
            "role": "user",
            "content": "3 加 5 等于多少？然后乘以 12？"
        }]}
    )

    print(result["messages"][-1].content)


if __name__ == "__main__":
    asyncio.run(main())

3.2. 代码解析

下面对这段代码比较关键的部分单独解释：

第一步：创建MCP客户端

client = MultiServerMCPClient({
    "math": {
        "transport": "stdio",
        "command": "uv",
        "args": ["--directory", "mcp", "run", "01.math_server.py"],
    }
})

这里我们创建了一个多服务器MCP客户端，它可以同时连接多个MCP服务器。

配置说明：

“math”：MCP服务器针对Agent暴露的名称，可以自定义。注意在prompt中也需要使用对应的名字，方便Agent确认需要使用的工具是谁。
- 一般MCP客户端会用mcp_服务器名字_工具名字之类的格式作为最终传给Agent的Function Name。
- 但在LangChain中，MCP工具传递给AI的名字就是每一个tools的名字，所以需要确保你配置的多个MCP工具里面没有重名的tools，否则无法正常识别！相关issue
transport：传输协议，可选为"stdio"、“sse”、“streamable_http”；
command：启动MCP服务器的命令（只有stdio模式下需要）
args：启动命令的参数列表（只有stdio模式下需要）
url：MCP服务器的链接地址（只有sse和streamable_http模式下需要）

使用stdio模式的时候，我们配置的command和args就是启动MCP服务器的命令。比如上面的配置本质上就是执行了如下命令：

1	uv --directory mcp run 01.math_server.py

其他MCP服务器，只要使用的是stdio模式，配置方式都是这样的。

MCP其中一个优点就在于，MCP客户端的链接配置基本上是所有支持MCP的客户端工具通用的，只要把这个json拷贝出去，就可以给其他工具（如claude-code）使用了。

这里需要注意两点：

如果配置的stdio的工具，一定要确定配置的命令能够正常执行。可以先执行一下这个命令确认是否能无报错正常启动MCP服务器。
如果配置的是sse或streamable_http的MCP Server，要确认这个远程的http服务器地址能够正常在客户端的主机上访问到。

另外，部分Agent工具在MCP服务器无法链接的时候是不会报错提示的（比如claude-code），一定要确认好Agent工具或SDK真的链接上了你提供的MCP工具，否则在缺少工具的时候Agent只会胡乱编造数据！

第二步：获取工具

1	tools = await client.get_tools()

这行代码会启动MCP服务器进程，并获取服务器提供的所有工具，tools是一个包含所有可用工具的列表。如果无法启动或链接MCP服务器，这个函数调用会抛出异常。

同时，这些工具里面也会包含FastMCP库从docstring里面解析出来的简介、参数、返回值，这些信息都会提供给Agent进行Function Calling。

[
    StructuredTool(
        name='add',
        description='Add two numbers',
        args_schema={
            'properties': {
                'a': {'title': 'A', 'type': 'integer'},
                'b': {'title': 'B', 'type': 'integer'}
            },
            'required': ['a', 'b'],
            'title': 'addArguments',
            'type': 'object'
        },
        response_format='content_and_artifact',
        coroutine=locals>.call_tool at 0x110448e00>
    ),
    StructuredTool(
        name='multiply',
        description='Multiply two numbers',
        args_schema={
            'properties': {
                'a': {'title': 'A', 'type': 'integer'},
                'b': {'title': 'B', 'type': 'integer'}
            },
            'required': ['a', 'b'],
            'title': 'multiplyArguments',
            'type': 'object'
        },
        response_format='content_and_artifact',
        coroutine=locals>.call_tool at 0x11244e980>
    )
]

第三步：创建Agent

1	agent = create_agent(model=model, tools=tools)

和之前的LangChain示例一样，我们将模型和工具传递给create_agent函数。不同的是，这里的工具来自MCP服务器。当然，我们可以在MCP工具的基础上去加其他的Function一起传入，都是OK的。

1 2	tools.append(other_tools) # 追加其他工具函数 agent = create_agent(model=model, tools=tools)

第四步：异步调用

result = await agent.ainvoke(
    {"messages": [{
        "role": "user",
        "content": "3 加 5 等于多少？然后乘以 12？"
    }]}
)

由于MCP客户端使用异步方式与服务器通信，我们需要使用ainvoke方法而不是invoke方法，同时需要在函数之前加上await。

3.3. 运行结果

运行这个程序，你会看到类似这样的输出：

1	3 加 5 等于 8，然后 8 乘以 12 等于 96。

Agent成功地：

理解了用户的数学问题
调用了add工具计算 3 + 5 = 8
调用了multiply工具计算 8 × 12 = 96
给出了完整的答案

从日志中可以看到，日志里面打印出来了CallToolRequest，也就是我们的MCP客户端去请求调用了MCP服务端的服务，这些信息是Agent根据工具调用结果返回的，而不是根据自己的理解“算”出来的。

4. The end

本文简单介绍了如何在LangChain里面使用MCP工具。

在实际项目中，你可以：

将现有的Python功能函数封装成MCP工具，方便不同的Agent使用
使用第三方提供的MCP工具，有非常多开源的牛逼MCP工具，比如serena
构建自己的工具生态系统，比如对接公司内网系统OpenAPI的各类MCP工具

本文到这里就结束啦！

【Hexo】简单记录如何在服务器上部署hexo-friend-article

2025-11-30T01:51:55.000Z

说明

本站有一个友链朋友圈页面，使用的是Rock-Candy-Tea/hexo-circle-of-friends项目。这个项目会尝试解析你的hexo博客友链页面，并去扫描你的友链们的hexo博客，获取到他们最新的博客文章，展示一个汇总页面：

但是从2025年11月24日开始，vercel的部署就一直处于失败状态，具体问题我提交了一个issue：https://github.com/Rock-Candy-Tea/hexo-circle-of-friends/issues/179

服务器部署

既然vercel的问题解决不了，那就只能换服务器部署喽，不再白嫖了。

服务器部署的教程参考：https://fcircle-doc.yyyzyyyz.cn/docs/deployment/backend.html

首先需要在服务器上git克隆这个项目，这就不多描述了。

然后，在https://github.com/Rock-Candy-Tea/hexo-circle-of-friends/releases里面下载最新的二进制可执行文件，注意选择和你服务器架构相同的可执行文件，比如我的ubuntu服务器就是下载linux-x86_64-unknown-linux-gnu.zip这个文件。

将zip上传到服务器上，解压得到fcircle_core和fcircle_api这两个可执行文件，放到hexo-circle-of-friends项目的根目录下。

~/code-tx/hexo-circle-of-friends
❯ ls
api             CHANGELOG.md    data_structures  fcircle_core          pyproject.toml    stop.sh            uv.lock
api_dependence  core            db               fc_settings.yaml      README.md         tests              vercel.json
Cargo.lock      css_rules.yaml  downloader       fc_settings.yaml.bak  requirements.txt  tools
Cargo.toml      data.db         fcircle_api      logs                  start.sh          update_version.py

搞定了之后，直接执行start.sh就可以运行项目了。

这个脚本会使用可视化的方式带你设置整个项目，首先是输入你的友链地址（比如本站的https://blog.musnow.top/link/），然后输入要绑定后端的端口号（选一个没被占用的端口就行了，默认的8000端口太常用了，不推荐）

一切正常的话，后端服务就启动成功了，可以用如下命令检查一下是否在运行

❯ netstat -ntlp | grep 10001
(Not all processes could be identified, non-owned process info
 will not be shown, you would have to be root to see it all.)
tcp        0      0 0.0.0.0:10001           0.0.0.0:*               LISTEN      2630423/./fcircle_a

然后还可以测试一下是否能获取到数据

1	curl -v http://127.0.0.1:10001/all

只要这个接口有返回json结果，那就是一切ok了。

注意，上述的操作只是完成了基本的部署，如果你需要一些进阶的配置，比如配置AI简介生成的能力，还需要根据https://fcircle-doc.yyyzyyyz.cn/docs/configuration.html里面的教程，去修改配置文件，和对应的.env环境变量（比如配置AI的key），否则某些功能不会生效。

反代设置

服务器部署完成之后，需要开放端口的防火墙，并设置反代。

这里需注意的是，自部署的版本反代里面需要加上正确的跨域请求头，否则会导致无法正常跨域访问（浏览器会拦截）

fcircle/:1  Access to fetch at 'https://hexo-friend-article.musnow.top/all' from origin 'https://blog.musnow.top' has been blocked by CORS policy: The 'Access-Control-Allow-Origin' header contains multiple values '*, https://blog.musnow.top', but only one is allowed. Have the server send the header with a valid value.

以1panel的反代设置为例，找到设置好的反向代理，点击源文就可以看到nginx的原始配置文件

需把location修改成如下的设置

location ^~ / {
    proxy_pass http://127.0.0.1:10001; 
    proxy_set_header Host $host; 
    proxy_set_header X-Real-IP $remote_addr; 
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
    proxy_set_header REMOTE-HOST $remote_addr; 
    proxy_set_header Upgrade $http_upgrade; 
    proxy_set_header Connection $http_connection; 
    proxy_set_header X-Forwarded-Proto $scheme; 
    proxy_set_header X-Forwarded-Port $server_port; 
    proxy_http_version 1.1; 
    add_header X-Cache $upstream_cache_status; 
    add_header Cache-Control no-cache; 
    proxy_ssl_server_name off; 
    proxy_ssl_name $proxy_host; 
    add_header Strict-Transport-Security "max-age=31536000"; 

    # 隐藏后端返回的CORS头，避免冲突
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Credentials;

    # 匹配musnow.top主域名+所有子域名
    set $cors_origin "";
    if ($http_origin ~* "^https?://(.*\.)?musnow\.top$") {
        set $cors_origin $http_origin;
    }

    # 动态设置CORS头
    add_header Access-Control-Allow-Origin $cors_origin;
    add_header Access-Control-Allow-Credentials "true";
    add_header Access-Control-Allow-Methods "GET, POST, OPTIONS, PUT, DELETE";
    add_header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization";

    # 专门处理OPTIONS预检请求
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin $cors_origin;
        add_header Access-Control-Allow-Credentials "true";
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS, PUT, DELETE";
        add_header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization";
        add_header Access-Control-Max-Age "3600"; # 预检结果缓存1小时
        return 204; # 直接返回204，无需转发到后端
    }
}

修改了以后，在博客页面确认能够请求成功，浏览器控制台没有报错，就OK了。

The end

有的时候免费的就是麻烦，vercel这部署的好好的突然就崩了，结果就是天天收到部署失败的邮件，又暂时没时间处理。

还是改成自己的服务器部署了，省事，后续没有遇到无法运行的bug也不用去考虑更新。如果继续用vercel，这个bug被修复之后我还得去更新一下vercel的配置才能恢复使用。

另外，如果最开始和慕雪一样用的是github+vercel的方式部署的，转成服务器部署之后，要记得把github的action给disable掉，不然还是会一直执行action的。

【ConfyUI】在MacBook上用ConfyUI部署阿里Z-Image最新开源模型

2025-11-28T12:18:52.000Z

引言

阿里巴巴通义实验室于2025.11.26开源了Z-Image图像生成模型，擅长写实摄影及中英文渲染。该系列包含多个版本，其中Turbo版已发布模型权重，Edit版和Base版即将上线。模型支持多模态输入，具备高精度语义理解能力，适用于广告、设计、内容创作等场景。开源版本可在ModelScope平台下载，为开发者提供灵活、高效的图像生成解决方案，推动AI视觉创作生态发展。

开源地址：https://modelscope.cn/models/Tongyi-MAI/Z-Image-Turbo/

可以直接在魔搭社区登录后，在线测试Z-Image模型文生图效果。本文介绍如何在mac上本地部署这个模型。注意：你的mac至少需要有32GB内存才能够部署Z-Image。

下载ConfyUI

前往github：https://github.com/Comfy-Org/desktop，下载最新的测试版本0.5.11的mac安装包（只有最新版本才能正常部署Z-Image）。可以用下面的两个地址直接下载安装

Mac (Apple Silicon): https://download.comfy.org/mac/dmg/arm64
Windows: https://download.comfy.org/windows/nsis/x64

下载完成后，拖拽ComfyUI到Application文件夹即可安装完成。首次打开时，ComfyUI需要初始化python环境，请确保你的mac上安装了homebrew和uv，保证能够正常初始化环境。因为我的电脑上本来就有uv环境，所以整个初始化环节非常顺利。

具体的安装和初始化教程可以参考：https://docs.comfy.org/zh-CN/installation/desktop/macos

前期的这些引导步骤全都选择默认就可以了，对于萌新来说没必要修改这些设置

这里有一个小点可以考虑修改，那就是这里的pypi安装镜像源，这里官方给的是错误的情况，会出现一个红x，请选择你当前网络环境中能够正常访问的镜像源来使用。

PyPI 镜像
阿里云：https://mirrors.aliyun.com/pypi/simple/
腾讯云：https://mirrors.cloud.tencent.com/pypi/simple/
中国科技大学：https://pypi.mirrors.ustc.edu.cn/simple/
上海交通大学：https://pypi.sjtu.edu.cn/simple/

Torch 镜像
阿里云: https://mirrors.aliyun.com/pytorch-wheels/cu121/

安装完成之后，就会进入桌面的UI页面，这就说明基本环境OK了

下载Z-Image模型并设置工作流

根据文档：https://comfyanonymous.github.io/ComfyUI_examples/z_image/里面的教程，下载三个模型文件，分别放到对应的目录下：

Text encoder file: qwen_3_4b.safetensors (goes in ComfyUI/models/text_encoders/).
diffusion model file: z_image_turbo_bf16.safetensors (goes in ComfyUI/models/diffusion_models/).
VAE: ae.safetensors the Flux 1 VAE if you don’t have it already (goes in ComfyUI/models/vae/)

这个目录在mac上，默认是~/Documents/ComfyUI/models，找到这个目录，把下载的三个模型文件放入文件夹即可。

这是一个默认的路径，如果你修改过，可以在~/Library/Application Support/ComfyUI/extra_models_config.yaml文件里面查看本地模型路径是哪一个

配置工作流

使用需要配置ConfyUI的工作流，作为小白的我完全不会配置，直接抄作业！

把https://comfyanonymous.github.io/ComfyUI_examples/z_image/网站上的图片，拖拽到ConfyUI里面，就可以导入工作流了！

为了避免这个原始的网站失效，这里贴出来完整的json工作流配置，可以用这个json来导入。

完整工作流json配置（未修改）

【AI】AI老是喜欢写总结文档，咋办？

2025-11-05T23:18:52.000Z

说明

最近这一年，各个类型的AI编程工具那是层出不穷，想必大家都遇到过一个问题，那就是AI在完成你给定的任务的时候，会输出非常非常非常非常非常多的文档和其他附属产物：

说明文档
使用文档
总结文档
测试代码
……

特别是claude的模型，写文档那是太喜欢了。而国产的GLM-4.6和Qwen估计是蒸馏了太多claude模型的数据，导致这俩模型也爱上了写文档，那是卡卡给你写的层出不穷。

对于程序员来说，这些文档可烦死人了，每次完成这个任务之后，都得手动把AI写的那一大堆没用的文档给删掉。而在企业级项目里，这些文档更是不可能提交到git里面去的，绝对是污染源。这还只是给用户带来的使用体验上的困扰，更别提写这么多文档要多浪费多少输出Token的AI资费了。

这时候，绝大部分朋友应该都能想到一个办法，在工具的System Prompt设置里面，让AI不要写文档。

1	除非用户明确表明，否则不要生成任何文档或测试代码。

但实际场景下，这个Prompt效果并不好，会出现AI生成文档->发现用户要求不要生成文档->删除文档的操作。相比于不加上这个Prompt，反而更耗费Token了，因为多了一个“删除文档”的工具调用。只能说无语了……

正确做法，堵不如疏

既然Agent没办法遵循我们“不写文档”的要求，那还不如给个引导，让AI把测试代码和文档都放到一个指定的.ai-docs目录下，然后，再在.gitignore里面忽略掉这个项目。

1
2
3

你是一个高效的AI助手，请遵循如下要求完成用户的任务：
- 所有生成的说明文档和测试代码都需要放入.ai-docs目录下，除非用户明确指定输出路径。
- 除非用户明确指定输出语言，所有问题都需要用中文回答，代码注释需要使用中文。

慕雪实测，这个方案效果远远好于让AI不生成文档的要求。

根据你使用的不同的AI工具，把这段话加到System Prompt或者上下文的设置里就可以了。比如~/.claude/CLAUDE.md文件中。

The end

如果你也被AI在代码仓库里面“拉屎”的问题烦到了，也可以试试慕雪的这个方案。虽然没有解决AI输出一大堆无用数据的问题，但至少不会影响仓库文件管理了。

【Agent.08】LangChain的第一个Demo：从零开始构建Agent

2025-11-02T07:26:19.000Z

欢迎阅读慕雪撰写的AI Agent专栏，本专栏目录如下

本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。

在上一篇文章中，我们了解了Agent的概念和ReAct工作原理。现在，让我们正式开始学习如何使用Agent框架来构建自己的AI Agent。本文将以业界最流行的LangChain框架为例，带大家编写第一个Agent程序。

1. 什么是LangChain？

1.1. LangChain简介

官方文档：https://docs.langchain.com/oss/python/langchain/quickstart
开源仓库：https://github.com/langchain-ai

LangChain是一个专门用于构建AI应用的框架，特别是Agent应用。它就像是AI应用开发的"瑞士军刀"，提供了构建Agent所需的各种工具和组件。

Agent SDK和基础的OpenAI接口调用的区别，在本专栏前几篇文章中已经阐述过了，这里不再赘述。AI Agent编程中，如果没有特殊需要，都推荐使用LangChain来编写，方便后续维护和拓展能力。

1.2. 为什么选择LangChain？

在众多Agent框架中，我们选择LangChain作为入门框架，主要有以下几个原因：

生态成熟：LangChain是目前最流行的Agent框架，文档完善，社区活跃
上手简单：相比其他框架，LangChain的学习曲线相对平缓
功能丰富：提供了从基础的LLM调用到复杂的Agent编排的完整工具链
兼容性好：支持多种大模型提供商，包括OpenAI、Anthropic、Goggle等

1.3. LangChain的核心组件

在开始写代码之前，让我们先了解一下LangChain的分层。

LangChain 分为三层，从下往上依次增强功能：

第一层：模型层。统一接口连接不同的 LLM。无论用 OpenAI、Claude 还是其他模型，调用方式都一样。
第二层：工具和代理。给模型添加工具能力。模型可以选择调用不同的工具去完成任务（比如搜索、数据库查询等）。
第三层：工作流编排。在LangChain的基础上，可用 LangGraph 把多个步骤连接成一个完整流程，串联整个工作流。比如先分类用户问题，再去搜索，最后生成回答。

这三层设计的好处是：你可以从简单场景开始，随着需求变复杂再往上加功能。直到达到预订目标。

2. 环境准备

2.1. 安装LangChain SDK

首先，我们需要安装LangChain。在开始之前，请确保你已经安装了Python 3.10+版本。

1	pip install langchain langchain-openai python-dotenv

这里我们安装了几个关键包：

langchain：LangChain的核心框架
langchain-openai：OpenAI模型的支持包（不安装的话没办法使用OpenAI API）
python-dotenv：环境变量管理工具（加载.env文件）

如果你使用了uv，可以直接在本专栏Agent仓库下使用uv run运行示例代码，无需关注第三方包安装。

2.2. 配置环境变量

为了安全地管理API密钥，我们使用.env文件来存储敏感信息。在项目根目录创建.env文件：

# OpenAI API配置
OPENAI_API_KEY=你的_api_key
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
OPENAI_MODEL=Qwen/Qwen2.5-7B-Instruct

慕雪小贴士：如果你是在自己的仓库里面使用.env，这个.env文件一定要记得添加到.gitignore中，避免把API密钥上传到代码仓库！

3. 第一个LangChain Agent

让我们来写一个简单的天气查询Agent。这个Agent能够回答用户关于天气的问题，虽然它只是返回一个模拟的结果。

3.1. 完整代码

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
import os
from dotenv import load_dotenv

# 加载环境变量
load_dotenv(override=True)

def get_weather(city: str) -> str:
    """获取指定城市的天气信息

    Args:
        city: 城市名称

    Returns:
        天气信息字符串
    """
    return f"{city}的天气总是晴朗的！今天的温度是25°C，非常适合出门。"

# 配置模型：设置 base URL 和 API key
model = init_chat_model(
    model=os.getenv("OPENAI_MODEL"), # 从环境变量获取模型
    model_provider="openai",  # 必须设置成openai才能正常识别格式
    api_key=os.getenv("OPENAI_API_KEY"),  # 从环境变量获取 API Key
    base_url=os.getenv("OPENAI_BASE_URL")  # 从环境变量获取 Base URL
)

# 创建Agent
agent = create_agent(
    model=model,  # 传入配置好的模型实例
    tools=[get_weather],  # 传入工具列表
    system_prompt="你是一个有帮助的助手，可以回答天气相关的问题。",
)

# 运行Agent
ret = agent.invoke(
    {"messages": [{"role": "user", "content": "北京的天气怎么样？"}]}
)

# 打印回答
print(ret.get('messages', [])[-1].content)

3.2. 代码解析

让我们一步步来解析这段代码：

第一步：导入依赖

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
import os
from dotenv import load_dotenv

这里我们导入了LangChain的核心组件：

create_agent：用于创建Agent的函数
init_chat_model：用于初始化聊天模型
os：用于读取环境变量
load_dotenv：用于加载.env文件

第二步：配置模型

model = init_chat_model(
    model=os.getenv("OPENAI_MODEL"),
    model_provider="openai",
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

这里我们使用了init_chat_model来创建一个聊天模型实例。虽然我们使用的是通义千问模型，但设置model_provider="openai"是因为LangChain的OpenAI接口最通用，兼容所有OpenAI格式的API。

第三步：定义工具函数

def get_weather(city: str) -> str:
    """获取指定城市的天气信息

    Args:
        city: 城市名称

    Returns:
        天气信息字符串
    """
    return f"{city}的天气总是晴朗的！今天的温度是25°C，非常适合出门。"

这是一个简单的工具函数，LangChain会自动识别函数的文档字符串和参数类型，并将其转换为可调用的工具。这里的返回值和之前Function Calling章节一样，都是写死的一个假的返回值。

注意：函数的文档字符串（就是"""包裹的函数注释，python中称作docstring）非常重要！LangChain会使用它作为Agent Function Calling的Desc工具描述，LLM会根据它来理解工具的功能和使用方法。

第四步：创建Agent

agent = create_agent(
    model=model,
    tools=[get_weather],
    system_prompt="你是一个有帮助的助手，可以回答天气相关的问题。",
)

这是最关键的一步，我们将模型、工具和系统提示组合在一起，创建了一个完整的Agent。

第五步：运行Agent

ret = agent.invoke(
    {"messages": [{"role": "user", "content": "北京的天气怎么样？"}]}
)

print(ret.get('messages', [])[-1].content)

我们使用invoke方法来运行Agent，传入用户的问题，然后从返回结果中提取AI的回答。

3.3. 运行结果

运行这个程序，你会看到类似这样的输出：

1	北京的天气总是晴朗的！今天的温度是25°C，非常适合出门。

可以看到，Agent成功地识别了用户的天气查询需求，自动调用了我们的get_weather工具，并给出了一个友好的回答。

4. LangChain的返回值结构

如下是上面代码中ret打印出来的结构，是一个dict。

这里的结构和我们使用OpenAI API时维护的messages数组基本一致，只不过LangChain帮我们在原始数据的基础上加了一层封装。

每个Dict结构的详细含义，在注释里面写清楚了，参考理解即可。

{
    'messages': [
        # 因为我们没有设置system prompt，所以第一条就是user message
        # langchain会给每一个消息都上一个id，方便标识和管理
        HumanMessage(content='北京的天气怎么样？',
                     additional_kwargs={},
                     response_metadata={},
                     id='88e2d0c7-fe27-486a-9acd-8b2b02e07b11'),
        # 这是ai对我们问题的回答，其中response_metadata包裹了一些当前会话的元数据
        # response_metadata是当前请求的数据，usage_metadata是当前会话累积数据
        # finish_reason标明当前AI消息的类型，tool_calls代表是一个工具调用消息
        AIMessage(content='',
                  additional_kwargs={'refusal': None},
                  response_metadata={
                      'token_usage': {
                          'completion_tokens': 22,
                          'prompt_tokens': 216,
                          'total_tokens': 238,
                          'completion_tokens_details': None,
                          'prompt_tokens_details': None,
                          'cache_write_tokens': 0,
                          'cache_read_tokens': 0,
                          'input_tokens': 0,
                          'output_tokens': 0
                      },
                      'model_provider': 'openai',
                      'model_name': 'longcat-flash-chatai-api',
                      'system_fingerprint': None,
                      'id': 'ad72c555243646738b62d2f48a552d23',
                      'finish_reason': 'tool_calls',
                      'logprobs': None
                  },
                  id='lc_run--cd5fb602-3103-4d67-8daa-640e90f255d2-0',
                  # 注意这里的tool_calls的id，会使用这个标识工具调用返回值
                  # 这里返回的tool_calls是一个list，因为AI可以一次性返回多个工具调用参数
                  tool_calls=[{
                      'name': 'get_weather',
                      'args': {
                          'city': '北京'
                      },
                      'id': '608a87b7-042d-4b82-b9a6-e285db91b54d',
                      'type': 'tool_call'
                  }],
                  usage_metadata={
                      'input_tokens': 216,
                      'output_tokens': 22,
                      'total_tokens': 238,
                      'input_token_details': {},
                      'output_token_details': {}
                  }),
        # 可以看到，这里的tool_call_id和上面的id是对应上的
        ToolMessage(content='北京的天气总是晴朗的！今天的温度是25°C，非常适合出门。',
                    name='get_weather',
                    id='b5dfa3b9-1c35-451f-a74c-611153a17f4f',
                    tool_call_id='608a87b7-042d-4b82-b9a6-e285db91b54d'),
        # AI获取到了工具调用结果，生成了最终的回答
        # finish_reason: stop代表这条消息就是终止消息了
        AIMessage(content='北京的天气总是晴朗的！今天的温度是25°C，非常适合出门。',
                  additional_kwargs={'refusal': None},
                  response_metadata={
                      'token_usage': {
                          'completion_tokens': 17,
                          'prompt_tokens': 269,
                          'total_tokens': 286,
                          'completion_tokens_details': None,
                          'prompt_tokens_details': None,
                          'cache_write_tokens': 0,
                          'cache_read_tokens': 0,
                          'input_tokens': 0,
                          'output_tokens': 0
                      },
                      'model_provider': 'openai',
                      'model_name': 'longcat-flash-chatai-api',
                      'system_fingerprint': None,
                      'id': '3b6d83b7b37c4cbbb057b95bc4329b23',
                      'finish_reason': 'stop',
                      'logprobs': None
                  },
                  id='lc_run--c9fa02c7-4b3c-461f-a1a0-04e80cb9a62f-0',
                  usage_metadata={
                      'input_tokens': 269,
                      'output_tokens': 17,
                      'total_tokens': 286,
                      'input_token_details': {},
                      'output_token_details': {}
                  })
    ]
}

对于用户而言，我们在这个期间没有关注过每一个阶段的任何返回值，全部数据都由LangChain请求并处理相应了，我们只需要关注Agent返回的最终的结果是否符合预期，以及这个过程中是否会抛出异常等等……

5. The end

本文只对LangChain的Demo做了个基本的测试和说明，下一篇文章就会开始以实际场景，构建我们的测试Agent了。

对于LangChain这些Agent框架而言，刚开始学习时，我们没有必要全知全会，多借助AI的能力去快速学习上手这些Agent的SDK，尽快从初学者变成能够使用SDK基本进行Agent开发的程序员，然后再去慢慢精进相关的知识！

【Mac】MacBookPro无法连接第2个外接显示器问题解决

2025-11-02T00:57:24.000Z

之前为了外接nuc，买了一个性价比的便携屏。现在nuc暂时出手了，便携屏还在，就想着能在mbp上接着用一下，多块屏幕肯定比少块屏幕更好嘛。没想到，typec线插上mac之后，没有任何动静，mac的系统设置里面没有出现任何第三块显示屏的信息。

由于这块便携屏有一段时间没用了，于是开始进行问题排查阶段：

屏幕本身有没有问题？
- 能亮logo，大概率没问题
typec线有没有问题？
- 一线通的c2c线，能供电说明功能没问题，但是没办法保证数据传输没问题

于是使用手机进行测试，确认线和便携屏都没问题，安卓手机能正常镜像屏幕到便携屏上。

既然屏幕没有问题，那问题肯定是出在mac上。

按住option点击左上角苹果，进入系统信息菜单，找usb端口，能够看到typec线被识别出来了，但是没有动静。

去官网二次确认了一下自己的mac能连第三个显示器（macbook air是不行的，只支持一台外接显示器，连第二台外接显示器需要关闭笔记本自己的屏幕）

官网链接：https://support.apple.com/zh-cn/guide/mac-help/mchl7c7ebe08/mac

尝试插拔了几次，更换了接口，还是没有解决。于是去b站搜索，只搜到了用usb转hdmi诱骗的方式接显示器什么的，和我现在要解决的问题没关系。

最后想到了一个问题，那就是把主接的显示器拔掉，单独接外接屏幕，亮了！

再接上主屏幕，也亮了！三显示器都显示成功。

结论就是：macbook pro想要链接第二台外接显示器，需要先把第一台外接显示器拔掉才能连接！

这不扯淡吗苹果……

【Mac】为Mac配置基本开发环境

2025-10-31T00:57:24.000Z

1. 写在前面

如果你之前用的主要是windows电脑，拿到mac的时候，一定会有些懵逼的。光是基础的开发环境，就有的一折腾。

但如果你学习过Linux，那么mac的开发环境安装就会简单很多了，因为它的很多命令行操作，就如同在ubuntu里面用apt安装软件一样，非常直接。

前排提醒：如果你在看到这篇文章的时候还没有入手mac，请谨慎判断mac是否适合你。如果你处于“不确定”自己适不适合mac的情况，最好还是选择一台windows笔记本。

本文记录一下在mac上如何安装基础的开发环境，希望能帮到第一次使用mac的你。

2. 必要环境

首先在启动台里面找到终端，mac的默认终端是zsh，和在linux里面安装的zsh基本上没有区别，同样可以安装oh my zsh对终端进行美化^[1]。

在mac上，最基础的两个命令行工具是必须要安装的，一个是xcode开发者工具，里面包含git、vim、curl等等常用的命令工具。执行这个命令后，会弹出来一个xcode的下载进度条弹窗，请耐心等待下载完毕，后续所有其他工具的安装都依赖于开发者工具里面帮我们下好的一些东西。

1	xcode-select --install # 安装xcode开发者工具

安装好xcode开发工具后，就可以配置一下git的用户名和邮箱了

1 2	git config --global user.email 邮箱 git config --global user.name 用户名

另外一个是brew（等价于ubuntu的apt）

1	/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew安装有很多需要请求github的步骤，请自行解决代理问题（咳咳）

下载完毕brew后，需要设置如下环境变量，才能使用brew安装的各类命令行工具

1	echo "export PATH=$PATH:$HOME/.local/bin" >> ~/.zshrc

默认情况下，brew的安装最后会提示你执行相关步骤，但是brew是写入了~/.zprofile里面的，慕雪遇到过某些内置终端软件（比如obsidian的内置终端插件）不会去加载这个文件里面的环境变量的场景，以防万一，可以在~/.zshrc里面也加上！

3. 基本环境

安装完毕上面两个基础软件后，可以来安装其他环境了。

3.1. Python

Python强烈推荐使用uv来管理，具体使用方式可以参考本站博客。uv的使用依赖于brew的环境，需要先安装了brew再安装uv。

1
2
3

curl -LsSf https://astral.sh/uv/install.sh | sh
# 安装3.10版本的python
uv python install 3.10

3.2. Node

mac上有不少工具都需要有node环境，使用如下命令安装，@后面的是node的版本号

1	brew install node@24

配置好后，将node的环境也加入PATH中

1	echo 'export PATH="/opt/homebrew/opt/node@24/bin:$PATH"' >> ~/.zshrc

使用npm -v和node -v命令确认安装成功。

如果需要编译node@24的库，还需要把这两个环境变量设置好，不然没法用

1 2	export LDFLAGS="-L/opt/homebrew/opt/node@24/lib" export CPPFLAGS="-I/opt/homebrew/opt/node@24/include"

node多版本管理：

很多时候我们需要使用node的多版本，这里建议使用mise工具来处理，不推荐使用rvm（容易搞坏全局node环境）

3.3. JAVA（SDKMAN）

JAVA推荐使用SDKMAN管理，这个工具和uv类似，使用参考本站博客

1	curl -s "https://get.sdkman.io" \| bash

使用如下命令让SDKMAN安装生效

1	source "/Users/mothra/.sdkman/bin/sdkman-init.sh"

使用sdk help命令确定是否已经安装成功

3.4. C++

mac上自带clang，g++/gcc命令实际上用的都是clang。只要你会使用g++命令，就可以正常编译c++的程序了。

当然，肯定是没有windows上的VS 2022之类的ide方便了。

4. 其他

后续有其他需要安装的环境，会在本文补充

https://blog.musnow.top/posts/2565866661 ↩︎

【Agent.07】什么是Agent？从Chat到ReAct的AI进化之路

2025-10-25T02:18:32.000Z

欢迎阅读慕雪撰写的AI Agent专栏，本专栏目录如下

本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。

在前面几篇文章中，我们已经学习了如何与大模型交互、如何写好Prompt、如何进行Function Calling等基础知识。现在，我们终于来到了这个专栏的核心主题——Agent。

本文有部分内容由AI辅助编写，仅供参考

1. 写在前面

说到AI Agent这个最近大火的关键词，很多人可能会觉得这是一个非常高端难懂的概念。但其实，AI Agent的本质就是一个能够自主思考和行动的AI助手。

如果说Chat LLM是一个只能说话的顾问，那么Agent就是一个既能说话又能干事的智能助手。这个转变，就是通过我们前面学习的Function Calling和Agent框架来实现的。

本文将从概念层面带大家理解Agent到底是什么，它和传统的Chat LLM有什么区别，以及它是如何工作的。

2. Agent和Chat LLM的区别

要理解Agent，首先要知道它和我们平时使用的Chat LLM（比如DeepSeek的网页聊天框）有什么本质区别。

2.1. Agent和Chat的区别？

传统的Chat LLM就像是只能说话的顾问，你问它答，一问一答的。它只能生成文本回答，没办法真正帮你做事。而Agent则完全不同，它能主动思考问题，规划执行步骤，还能调用各种工具和API来完成任务。

当然啦，现在很多AI的网页端也在进化，开始加入网络搜索、代码知识库这些工具功能，算是朝着Agent的方向转变了（比如豆包）。但我们这里说的，还是Agent和普通Chat LLM最核心的概念区别。

2.2. 为什么需要Agent？

想象一下这个场景：你需要AI帮你预订一张机票。这也是之前在Function Calling中作为示例的场景。

Chat LLM的处理方式：

由于Chat LLM没有能力访问外部工具，所以他只能给我们提出购买机票的建议

用户：帮我预订一张明天从北京到上海的机票
Chat LLM：对不起，我无法直接预订机票。但我可以告诉你如何操作：
1. 打开携程/去哪儿/飞猪等订票网站
2. 输入出发地：北京，目的地：上海
3. 选择出发日期：明天
4. 选择航班并完成支付...

Agent的处理方式：

Agent可以接触我们预先定义好的工具，帮我们实现预订机票的这个流程。

用户：帮我预订一张明天从北京到上海的机票
Agent：[思考]用户需要预订机票，我需要：
1. 搜索可用航班
2. 选择合适的航班
3. 执行预订操作
[行动]调用search_flights工具 → [分析结果] → 调用book_flight工具 → [完成任务]
Agent：已为您成功预订明天从北京到上海的CA1234航班，08:30起飞，票价1280元。预订号：BK123456789。

这就是本质区别：Chat LLM只能"说"，而Agent能"做"。这一点，在先前的Function Calling章节已经展示给大家了。

在AI时代，我们需要的不仅仅是一个能聊天的助手，更需要一个能帮我们解决实际问题的智能助手，进一步提升各类事情的效率。

Agent的出现解决了很多现实问题：

任务自动化：一些涉及到决策的复杂的多步骤任务，现在可以让Agent自动完成，大大减少了人工干预。
工具集成：Agent能够调用各种API和工具，这样AI的能力边界就被大大扩展了，能够和几乎任何已有的系统进行集成和协作，完全打破了原始的只能通过OpenAPI人工编写脚本进行定死的任务处理的范式。
智能决策：Agent可以根据实际情况自主判断和选择最佳解决方案。而且通过工具与环境交互，Agent还能不断优化自己解决问题的策略。像人一样选择最优解。

在软件开发、数据分析、客户服务这些场景中，Agent的价值就更加明显了。比如本专栏最终要实现的测试用例生成Agent，就能自动完成代码分析、测试用例编写、覆盖率检查这一整套复杂的任务流程。

不过需要注意的是：Agent并不是万能的，只有涉及到需要利用大模型的思考能力进行决策的场景，才有必要使用Agent来实现。如果是一些诸如静态扫描代码流水线、自动化脚本测试这种已经“固定死”的场景，没有必要盲目蛮干的上Agent，没有任何意义，甚至会降低效果！

简单来说，一个任务中，需要根据数据进行下一步操作决策的节点越多，就越适合引入Agent。反之，如果没有什么需要动态决策的场景，一个传统的写死的脚本依旧是更好的选择。

3. Agent的ReAct工作原理

3.1. 什么是ReAct？

ReAct（Reasoning and Acting，推理-行动）是Agent最核心的工作机制。这个概念是姚顺雨（Shunyu Yao）等研究人员在2022年提出的，现在已经成为了Agent框架的标准设计模式^[1]。

ReAct的核心思想其实很简单，就是让Agent像人类一样思考问题，然后采取行动。具体来说包含三个步骤：

首先是推理，Agent会分析当前的情况，制定一个行动计划；
然后是行动，根据计划执行具体的工具调用或操作；
最后是观察，看看行动的结果如何，然后根据结果调整策略，执行下一步行动；

这个过程会不断循环进行，直到AI认为任务完成为止。

3.2. ReAct工作流程图

下面是一个典型的Agent ReAct工作流程：

flowchart TD    A([接收用户任务]) --> B[理解任务需求]    B --> C[分析任务复杂性]    C --> D{需要工具调用?}    D -->|否| E[直接生成回答]    E --> Z([完成任务])    D -->|是| F[规划执行步骤]    F --> G[选择合适工具]    G --> H[调用工具/函数]    H --> I[获取执行结果]    I --> J[分析结果质量]    J --> K{任务完成?}    K -->|否| L[更新策略/信息]    L --> M{需要更多工具?}    M -->|是| F    M -->|否| N[继续推理分析]    N --> F    K -->|是| O[生成最终回答]    O --> Z    style A fill:#90EE90    style Z fill:#FFB6C1    style H fill:#FFE4B5    style I fill:#FFE4B5

3.3. ReAct的具体步骤

让我们用一个具体的例子来说明ReAct是如何工作的。假设用户要求：“帮我分析这个Python文件的性能瓶颈并生成优化建议”。

Step 1: Reasoning（推理）

Agent思考：用户需要我分析Python文件的性能瓶颈。我需要：
1. 读取Python文件内容
2. 分析代码结构和复杂度
3. 识别潜在的性能问题
4. 生成优化建议

需要的工具：
- file_reader：读取文件
- code_analyzer：分析代码
- performance_profiler：性能分析

Step 2: Acting（行动）

# 调用file_reader工具
file_content = file_reader("performance_test.py")
# 调用code_analyzer工具
analysis_result = code_analyzer(file_content)
# 调用performance_profiler工具
performance_report = performance_profiler(file_content)

Step 3: Observation（观察）

Agent观察结果：
- 文件读取成功，共156行代码
- 代码分析发现3个嵌套循环
- 性能分析显示时间复杂度为O(n³)
- 内存使用量较大

Step 4: 再次Reasoning（二次推理）

Agent思考：根据分析结果，我发现了以下性能问题：
1. 三重嵌套循环导致时间复杂度过高
2. 大量重复计算
3. 内存使用未优化

现在需要生成具体的优化建议和代码示例。

Step 5: 最终Action（最终行动）

1	Agent生成最终的优化报告和改进代码。

ReAct这种机制有很多优势。首先是透明性，Agent每一步的推理过程都是可见的，这样我们就能很方便地调试和优化它的行为。然后是灵活性，Agent可以根据中间得到的结果随时调整策略，而不是死板地按照预设流程执行。还有可控性，我们可以在关键节点设置检查点，确保Agent不会"跑偏"。最后是扩展性，可以很轻松地集成新的工具和能力。

正是这种"思考-行动-观察"的循环机制，让Agent具备了真正的智能行为，能够处理那些复杂的、需要多步骤才能完成的任务。

4. Agent SDK与OpenAI接口的关系

4.1. 从底层到高层的关系

在我们前面学习的内容中，我们接触了三个层次的东西：直接用requests调用OpenAI API，使用OpenAI Python SDK，以及现在要学习的Agent框架。

这三者之间是什么关系呢？我们可以用一个生活中的例子来理解。

直接调用OpenAI API就像手动炒菜，你需要自己控制火候、掌握时间、放调料等等所有细节，虽然很灵活但操作起来特别复杂。
使用OpenAI SDK就像用电饭煲，它把底层的网络请求和响应处理都封装好了，你只需要把米放进去按下按钮就行，可以更专注于业务逻辑。
而使用Agent SDK就更像去餐厅点餐了，你只需要告诉服务员你想要吃什么菜，后厨也就是Agent框架会自动处理所有的烹饪流程，你等着上菜就行。

简单来说，这三个东西的封装层次越来越高，也就是一个依赖链条：

flowchart TD    A[HTTP] --> B[OpenAI接口]    B --> C[OpenAI SDK]    C --> D[Agent SDK]    D --> E[Agent工具,如cursor]

现在已经有非常多的开源Agent SDK以及封装好的Agent工具，为我们节省了很多工作。本专栏不会告诉大家如何搓一个Agent SDK出来，而是直接转向Agent SDK的应用。

4.2. Agent SDK的架构层次

下面是一个Agent SDK的架构层次图，非实际的架构图，只是一个示例Demo：

flowchart TD    A[用户输入] --> B[Agent SDK]    B --> C[ReAct控制器]    C --> D[Prompt管理器]    C --> E[工具管理器]    C --> F[状态管理器]    D --> G[系统Prompt构建]    E --> H[Function Calling处理]    F --> I[对话历史维护]    G --> J[OpenAI SDK]    H --> J    I --> J    J --> K[OpenAI API]    K --> L[大模型]    L --> M[模型响应]    M --> N[SDK解析]    N --> O[工具执行]    O --> P[结果处理]    P --> Q[最终输出]    style A fill:#90EE90    style Q fill:#FFB6C1    style B fill:#E1F5FE    style C fill:#F3E5F5

4.3. Agent SDK帮我们做了什么？

Agent SDK本质上是在OpenAI SDK的基础上，封装了以下功能：

首先，是自动化的ReAct循环管理，下面是一个伪代码，展示了二者的区别：

# 原始方式：我们需要手动管理
def manual_agent(user_input):
    messages = [{"role": "system", "content": system_prompt}]
    messages.append({"role": "user", "content": user_input})

    # 手动调用API
    response = openai.chat.completions.create(...)

    # 手动检查是否需要工具调用
    if response.choices[0].message.tool_calls:
        # 手动执行工具
        # 手动构建第二次请求...
        pass

###################################################

# Agent SDK方式：自动管理
from some_agent_sdk import Agent

agent = Agent(
    tools=[tool1, tool2, tool3],
    model="gpt-4"
)

result = agent.run("帮我预订机票")  # SDK自动处理所有ReAct循环

总而言之言而总之，Agent SDK帮我们把上下文管理、工具管理、工具调用、工具返回结果处理等等逻辑都封装好了，不再需要我们自己去解析OpenAI接口的Function Calling返回格式进行处理，也不需要关注Agent在多轮对话中对工具调用状态的思考等等事项。

我们只需要把prompt、模型、工具传入给Agent SDK，剩下的全由Agent SDK代劳！

4.4. 常见的Agent SDK

名称	开发语言	核心特点	仓库
OpenAI Agents SDK	Python	官方轻量型Agent SDK，支持多Agent协作、工具调用、会话记忆，原生集成OpenAI模型	官方文档
LangChain	Python/JS	生态最成熟，支持OpenAI等多LLM集成，提供完整Agent工作流（工具、记忆、编排）	GitHub
Microsoft AutoGen	Python	专注多Agent对话协作，深度兼容OpenAI模型，适合复杂任务分工与自动化执行	GitHub
CrewAI	Python	轻量级团队式Agent框架，默认支持OpenAI模型，角色定义清晰、任务分配灵活	GitHub
LangGraph	Python	状态机式Agent框架，无缝集成OpenAI模型，擅长复杂流程控制与步骤化任务执行	GitHub

5. The end

好啦，通过这篇文章的学习，咱们算是把Agent的核心概念和工作原理搞清楚了。

Agent的核心工作机制就是ReAct，也就是推理-行动-观察的循环。Agent会先分析情况制定计划，然后执行工具调用，观察结果并调整策略，这个循环让Agent具备了真正的智能行为。

后续，将以业界最常用的LangChain Agent SDK为例，为大家展示一个最最简单的Agent的代码编写。

Yao, S., Zhao, J., Yu, D., Du, N., Shafran, I., Narasimhan, K., & Cao, Y. (2023). ReAct: Synergizing Reasoning and Acting in Language Models. International Conference on Learning Representations. https://arxiv.org/abs/2210.03629 ↩︎

【Agent.06】使用openai sdk实现多轮对话

2025-10-25T01:07:45.000Z

欢迎阅读慕雪撰写的AI Agent专栏，本专栏目录如下

本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。

本文介绍了如何使用OpenAI Python SDK实现多轮对话和Function Calling功能，包括SDK安装、多轮对话维护和函数调用的完整示例。

1. 引言

在上一篇文章中，我们使用requests库直接调用OpenAI API，实现了基础的AI交互功能。虽然这种方式能够帮助我们理解API的工作原理，但在实际开发中，直接使用HTTP请求会显得有些"原始"。

OpenAI官方提供了Python SDK，能够让我们更方便的实现这些功能。其本质上也是封装了requests库和aiohttp库提供的网络请求能力，将其从我们网络请求原始获取到的json字段，变成了response对象的成员变量。

本文将简单示例如何使用OpenAI Python SDK的使用方式，以及我们如何进行多轮对话的messages维护示例，都很简单，看看就会了。

2. OpenAI SDK入门

2.1. 安装SDK

首先需要安装OpenAI的Python SDK：

1	pip3 install openai

安装完成后，我们就可以使用OpenAI提供的客户端类来调用API了。

2.2. 基础配置

使用SDK之前，需要先配置API密钥。推荐使用环境变量的方式：

import os
from openai import OpenAI

# 设置API密钥
os.environ["OPENAI_API_KEY"] = "your_api_key_here"

# 创建客户端
client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),
    base_url="https://api.siliconflow.cn/v1"  # 使用硅基流动的API
)

注意：把API密钥设置在环境变量中比硬编码在代码里更安全，这也是生产环境的最佳实践。

问：什么是环境变量？

环境变量是操作系统中用于存储系统或应用程序运行所需关键路径及配置信息的系统级变量。它的核心功能是为系统和用户提供统一的路径引用方式，简化程序调用过程。
简单来说，环境变量就你设置到系统某个地方的变量，可以被整个系统的任何程序获取。使用环境变量获取一些信息，可以避免把API_TOKEN这种重要的数据硬编码到程序里面去，导致泄露。
同时使用环境变量也方便我们后续修改配置，如果API_TOKEN是在程序里面写死的，那可能修改一个变量需要找到所有修改点，很麻烦！

3. 多轮对话实现

3.1. 对话状态管理

多轮对话的核心在于维护对话历史。我们需要在每次请求时，将之前的对话内容一起发送给AI模型。

import os
from openai import OpenAI

class ChatBot:
    def __init__(self, api_key):
        self.client = OpenAI(
            api_key=api_key,
            base_url="https://api.siliconflow.cn/v1"
        )
        self.messages = [
            {"role": "system", "content": "你是一个有帮助的AI助手。"}
        ]

    def chat(self, user_input):
        """发送用户消息并获取AI回复"""
        # 添加用户消息到历史记录
        self.messages.append({"role": "user", "content": user_input})

        try:
            # 调用API获取回复
            response = self.client.chat.completions.create(
                model="Qwen/Qwen3-8B",
                messages=self.messages,
                max_tokens=512,
                temperature=0.7
            )

            # 获取AI回复
            ai_reply = response.choices[0].message.content

            # 将AI回复也加入历史记录
            self.messages.append({"role": "assistant", "content": ai_reply})

            return ai_reply

        except Exception as e:
            return f"出错了: {str(e)}"

    def get_history(self):
        """获取对话历史"""
        return self.messages

# 使用示例
if __name__ == "__main__":
    API_KEY = "your_api_key_here"
    bot = ChatBot(API_KEY)

    print("AI助手已启动，输入'退出'结束对话")

    while True:
        user_input = input("你: ")
        if user_input.lower() == '退出':
            break

        ai_reply = bot.chat(user_input)
        print(f"AI: {ai_reply}")

3.2. 对话效果演示

运行上面的代码，我们可以实现如下对话：

❯ uv run 03.multi.round.chat/multi_round_chat.py
AI助手已启动，输入'退出'结束对话，输入'清空'清空对话历史
==================================================
你: 你好,我叫小明
AI: 你好，小明！很高兴认识你～有什么我可以帮你的吗？(•̀ᴗ•́)و
------------------------------
你: 我叫什么名字?
AI: 你的名字是小明呀！刚才你自己告诉我的，是不是想测试我有没有记住呢？(✧ω✧) 需要我帮你做什么事情吗？
------------------------------
你:

可以看到，AI能够记住我们之前提到的名字"小明"，这就是通过维护messages列表实现的。

4. 总结

OpenAI SDK用起来确实比直接requests调用舒服多了，代码更简洁，也不用自己处理各种HTTP细节。多轮对话的实现原理也很简单，就是把对话历史保存起来，每次请求都带上，作为对话的记忆。

这里也展现了LLM“无状态”的特性，我们把相同的messages数组传递给任何模型，只要不超过目标模型的上下文Token数量，模型就能“记住”我们对话的内容，根据对话历史，为我们生成回答。

不过，在实际的Agent开发中，多轮对话并不常使用，绝大部分Agent框架只需要提供入口prompt，后续的所有流程都是Agent自行解决。

但这不代表多轮对话就不用掌握了，还是得了解了解如何维护多轮对话的状态的。

【Agent.05】OpenAI接口Function Calling工具调用详解

2025-10-19T00:28:30.000Z

欢迎阅读慕雪撰写的AI Agent专栏，本专栏目录如下

本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。

本文将详细介绍OpenAI格式中的Function Calling工具调用的格式和逻辑。

1. 写在前面

Function Calling（函数调用）是大模型时代最革命性的功能之一，它让AI从"只会聊天"变成了"能干活"。在这之前，AI就像一个只能说话的顾问，只能说话，不能干活。现在通过Function Calling，AI变成了一个能够操作工具、执行任务的助手，能实现的能力就更多了！

这个功能最早由OpenAI在2023年6月推出，直接引爆了整个AI Agent开发的浪潮。现在市面上几乎所有的大模型都支持Function Calling功能，包括GPT系列、Claude、Gemini、Qwen、Kimi、DeepSeek等等。只要是你叫的上名字的大模型，都支持Function Calling。

Function Calling是Agent开发的基石。所有Agent框架，本质上都是在利用Function Calling的能力，让AI大模型ReAct，自主进行多轮工具调用，来完成特定任务的。

所以，了解Function Calling，是我们正式开始学习Agent开发之前，必不可少的一环。

在之前，本站已经在MCP的博客中，简单介绍了Function Calling的格式，和MCP工具进行了对比。但在那篇文章中，我们是用了OpenAI的SDK实现的功能，并没有使用直接请求的方式。要详细学习，还是得自己会直接HTTP请求OpenAI接口！

本文将通过requests库直接请求OpenAI接口，带大家认识一下最基础的Function Calling格式长啥样，以及要如何使用Function Calling的结果。现在这些工作，都已经被Agent SDK帮我们实现了。但我们还是得从头开始，自己试试，才能在Agent开发中，更好的理解Agent到底是怎么调用工具的，以及哪里出了问题。

2. 什么是Function Calling？

Function Calling是一种让大模型能够调用外部工具（函数）的机制。简单来说，就是AI可以根据用户的意图，自动选择合适的函数并调用，从而完成实际任务。

2.1. 传统对话 vs Function Calling

下面是一个伪Function Calling调用的示意和Chat模式的对比：

传统对话模式：

1 2	用户：帮我查一下今天的天气 AI：对不起，我无法获取实时天气信息，因为我是一个语言模型...

Function Calling模式：

用户：帮我查一下今天的天气
AI：[调用get_weather函数，参数：location="北京", date="today"]
函数返回：北京今天晴天，温度25°C
AI：北京今天天气晴朗，温度25°C，适合外出活动。

看到了吗？通过Function Calling，AI从"只会说不会做"变成了"既能说又能做"。

有人可能会说：这个功能不是可以让AI在回答中以特定格式，给出函数参数，我们通过解析回答来实现吗？

从理论上来说，当然是可以实现的。但是有一个东西叫“大模型幻觉”，还有另外一个事实是，即便是最新的大模型，依旧可能会在Prompt遵循上有自己的“创造性转化和创新性发展”，导致你本来想让它以A格式返回，模型偏不，给你输出了一个B模式，那你代码里面实现的回答解析逻辑就蛋糕了，没法用喽！

即便现在最新的大模型，依旧有这个问题出现。如果你调用过美团LongCat的API或者claude的API，你可能会发现有的时候，这两个AI会在回答中，以XML格式（如和块）返回工具调用的参数，而不是在Function Calling参数中返回。导致我们预先设计的逻辑直接失效，非常蛋疼。

上面介绍了这些，只是想让大家知道，单纯依赖Chat回答来实现工具调用是不可行的！我们必须要有一个机制，能让大模型直接返回统一格式的工具调用结果，方便实现通用的解析方法和能力使用。

2.2. Function Calling的核心价值

AI生成的核心价值，仅供参考：

扩展AI能力边界：让AI能够获取实时信息、操作数据库、调用API等
提高响应准确性：通过调用可靠的数据源，减少AI"胡说八道"的情况
实现复杂工作流：可以组合多个函数调用，完成复杂任务
降低开发门槛：开发者只需要定义好函数接口，不需要复杂的训练过程

3. Function Calling的工作原理

好了，上面叭叭了那么多没用的，现在开始正式来认识一下Function Calling的流程吧。

Function Calling的核心流程可以概括为：定义函数 -> 用户输入 -> AI选择函数,生成参数 -> 调用函数 -> AI处理结果 -> 返回包含函数信息的回答。

这里需要明确的一点是，调用函数这一环节，是需要我们自己通过解析AI返回的函数工具参数，然后实现的调用，并不能由AI主动触发某个函数！如果你看到了某个AI工具（比如cursor）会主动触发工具调用，那是因为开发者在cursor的代码中实现了这套逻辑。

3.1. 完整工作流程图

下面是单轮工具调用的流程：

flowchart TD    A([用户输入]) --> B[AI分析用户意图]    B --> C{需要调用函数?}    C -->|否| D[直接回答用户]    C -->|是| E[选择合适的函数]    E --> F[生成函数调用参数]    F --> G[返回函数调用信息]    G --> H[执行函数调用]    H --> I[获取函数执行结果]    I --> J[将结果传回AI]    J --> K[AI生成最终回答]    K --> L([输出给用户])    style A fill:#90EE90    style L fill:#FFB6C1    style G fill:#FFE4B5    style I fill:#FFE4B5

3.2. Function Calling的请求和返回格式

了解了流程后，我们再来看看流程中是怎么实现的。

3.2.1. 函数定义（Function Schema）

名词解释：在 XML/JSON 中，schema 用于定义数据格式的约束（如 XML Schema Definition, XSD），规定哪些字段允许出现、数据类型是什么、是否必填等，确保数据交换时的一致性。

首先，我们需要告诉AI有哪些函数可以调用。这通过定义函数的schema来实现：

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定地点的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "要查询天气的地点"
            },
            "date": {
              "type": "string",
              "description": "查询日期，可以是'today'、'tomorrow'或具体日期"
            }
          },
          "required": ["location"]
        }
      }
    }
  ]
}

单个function中的关键字段：

name: 函数名称，必须是有效的标识符，且不可以出现重复。
description: 函数功能描述，AI通过这个理解函数用途，知道什么时候要调用它。
parameters: 参数定义，包括参数名称、类型、描述等，AI通过类型和描述理解参数字段含义，知道要给他传入什么值。
required: 必需参数列表

这个tools的schema是放到OpenAI请求的body中的，和messages参数一起发送

{
  "messages": [],
  "tool_choice": "auto",
  "tools": []
}

这里多了一个参数tool_choice，可选值为auto/none/required：

auto：自动识别是否需要进行工具调用（可以调用，可以不调用）；
none：AI会认为没有工具，不进行工具调用；
required：AI必须进行工具调用；

3.2.2. AI的函数选择

当用户输入后，AI会分析用户意图，决定是否需要调用函数以及调用哪个函数，并在返回值的Body中包含如下字段：

{
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"location\": \"北京\", \"date\": \"today\"}"
      }
    }
  ]
}

其中arguments部分就是AI给这个工具生成的调用参数了。我们需要在代码中，对arguments参数里面的json字符串进行二次解析，获取参数的字段值。

3.2.3. 函数执行和结果处理

我们在接收到AI的函数调用请求后，需要调用并执行对应的函数，并将结果，以如下格式，在messages数组中追加，返回给AI：

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"temperature\": 25, \"condition\": \"晴天\", \"humidity\": \"60%\"}"
}

其中，AI是通过tool_call_id字段将调用结果和调用来源对应上，能够理解这是get_weather工具的调用结果。content字段就是工具调用的返回值了，这个返回值没有任何格式限定，可以随意给出，只要AI能够理解就OK。一般的工具调用结果都会用json格式返回给AI，比较方便AI理解。

接下来，就是AI总结这个工具结果，返回回答给用户了。

3.3. 实际代码示例（单轮）

以下是使用 Python + requests 直接请求 OpenAI API 的示例。其中，我们用了一个假返回值的函数get_weather来模拟了一个天气请求的结果，返回给AI。

这是可行的，因为对于AI来说，我们的工具是怎么实现的是一个黑盒状态，AI不关心我们返回的工具调用结果是哪里来的，也不关注我们工具调用结果的格式。

import requests
import json

def get_weather(location, date):
    """模拟获取天气信息的函数"""
    # 这里应该调用真实的天气API
    return {
        "location": location,
        "date": date,
        "temperature": 25,
        "condition": "晴天",
        "humidity": "60%"
    }

def chat_with_function_calling(user_message):
    # 配置API信息
    api_key = "your-openai-api-key"  # 替换为你的OpenAI API密钥
    base_url = "https://api.siliconflow.cn/v1"
    model = "Qwen/Qwen3-8B"

    # 设置请求头
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }

    # 定义可用的函数
    tools = [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "获取指定地点的天气信息",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "要查询天气的地点"
                        },
                        "date": {
                            "type": "string",
                            "description": "查询日期，可以是'today'、'tomorrow'或具体日期"
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ]

    # 第一次调用AI的请求体
    request_data = {
        "model": model,
        "messages": [{"role": "user", "content": user_message}],
        "tools": tools,
        "tool_choice": "auto"
    }

    # 发送第一次请求
    response = requests.post(
        f"{base_url}/chat/completions",
        headers=headers,
        json=request_data
    )

    if response.status_code != 200:
        print(f"API请求失败: {response.status_code} - {response.text}")
        return "抱歉，服务暂时不可用，请稍后重试。"

    response_data = response.json()
    message = response_data["choices"][0]["message"]

    # 检查是否需要调用函数
    if "tool_calls" in message and message["tool_calls"]:
        # 执行函数调用
        tool_call = message["tool_calls"][0]
        function_name = tool_call["function"]["name"]
        function_args = json.loads(tool_call["function"]["arguments"])

        if function_name == "get_weather":
            result = get_weather(function_args["location"], function_args.get("date", "today"))

            # 构建第二次请求的消息数组
            messages = [
                {"role": "user", "content": user_message},
                message,
                {
                    "role": "tool",
                    "tool_call_id": tool_call["id"],
                    "name": function_name,
                    "content": json.dumps(result)
                }
            ]

            # 第二次请求的数据
            second_request_data = {
                "model": model,
                "messages": messages
            }

            # 发送第二次请求
            second_response = requests.post(
                f"{base_url}/chat/completions",
                headers=headers,
                json=second_request_data
            )

            if second_response.status_code == 200:
                second_response_data = second_response.json()
                return second_response_data["choices"][0]["message"]["content"]
            else:
                print(f"第二次API请求失败: {second_response.status_code} - {second_response.text}")
                return "抱歉，处理函数结果时出现错误。"

    return message["content"]

# 使用示例
if __name__ == "__main__":
    print(chat_with_function_calling("帮我查一下北京今天的天气"))

在本地pip install了requests库之后，配置你的硅基流动API KEY，运行如上代码，可以正常得到结果！可以看到AI的回答，正是我们Function Calling里面工具返回的结果，调用成功了！

你可以在上述代码中添加打印，详细看看每一步我们发送的请求体格式、OpenAI接口返回的结果格式，进一步了解两边的交互过程。本文就不演示啦！

4. Function Calling的高级应用

上面，我们已经了解了单轮Function Calling应该如何实现，现在可以来看看如何实现多轮工具调用

4.1. 多函数调用

AI可以一次性调用多个函数，或者根据前一个函数的结果决定是否需要调用更多函数。所以我们可以定义多个函数（工具）：

# 定义多个函数
tools = [
    {
        "type": "function",
        "function": {
            "name": "search_flights",
            "description": "搜索航班信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "origin": {"type": "string", "description": "出发城市"},
                    "destination": {"type": "string", "description": "目的地城市"},
                    "date": {"type": "string", "description": "出发日期"}
                },
                "required": ["origin", "destination", "date"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "book_flight",
            "description": "预订航班",
            "parameters": {
                "type": "object",
                "properties": {
                    "flight_id": {"type": "string", "description": "航班ID"},
                    "passenger_name": {"type": "string", "description": "乘客姓名"}
                },
                "required": ["flight_id", "passenger_name"]
            }
        }
    }
]

4.2. 多轮函数调用示例

下面我们实现一个完整的多轮函数调用示例，使用4.1节中定义的航班搜索和预订工具：

import requests
import json

def search_flights(origin, destination, date):
    """模拟搜索航班信息"""
    # 这里应该调用真实的航班API
    return [
        {
            "flight_id": "CA1234",
            "origin": origin,
            "destination": destination,
            "date": date,
            "departure_time": "08:30",
            "arrival_time": "11:45",
            "price": 1280,
            "available_seats": 15
        },
        {
            "flight_id": "MU5678",
            "origin": origin,
            "destination": destination,
            "date": date,
            "departure_time": "14:20",
            "arrival_time": "17:35",
            "price": 980,
            "available_seats": 8
        }
    ]

def book_flight(flight_id, passenger_name):
    """模拟预订航班"""
    # 这里应该调用真实的预订API
    import random
    success_rate = random.random()
    if success_rate > 0.2:  # 80%成功率
        return {
            "success": True,
            "booking_id": f"BK{flight_id}{int(__import__('time').time())}",
            "flight_id": flight_id,
            "passenger_name": passenger_name,
            "status": "confirmed"
        }
    else:
        return {
            "success": False,
            "error": "座位已售罄，请选择其他航班"
        }

def multi_tool_function_calling(user_message):
    """多轮函数调用示例"""
    # 配置API信息
    api_key = "your-siliconflow-api-key"
    base_url = "https://api.siliconflow.cn/v1"
    model = "Qwen/Qwen3-8B"

    # 设置请求头
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }

    # 定义多个工具
    tools = [
        {
            "type": "function",
            "function": {
                "name": "search_flights",
                "description": "搜索航班信息",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "origin": {"type": "string", "description": "出发城市"},
                        "destination": {"type": "string", "description": "目的地城市"},
                        "date": {"type": "string", "description": "出发日期"}
                    },
                    "required": ["origin", "destination", "date"]
                }
            }
        },
        {
            "type": "function",
            "function": {
                "name": "book_flight",
                "description": "预订航班",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "flight_id": {"type": "string", "description": "航班ID"},
                        "passenger_name": {"type": "string", "description": "乘客姓名"}
                    },
                    "required": ["flight_id", "passenger_name"]
                }
            }
        }
    ]

    # 工具函数映射
    tool_functions = {
        "search_flights": search_flights,
        "book_flight": book_flight
    }

    # 第一轮对话
    messages = [{"role": "user", "content": user_message}]

    request_data = {
        "model": model,
        "messages": messages,
        "tools": tools,
        "tool_choice": "auto"
    }

    response = requests.post(
        f"{base_url}/chat/completions",
        headers=headers,
        json=request_data
    )

    if response.status_code != 200:
        print(f"API请求失败: {response.status_code} - {response.text}")
        return "抱歉，服务暂时不可用，请稍后重试。"

    response_data = response.json()
    message = response_data["choices"][0]["message"]
    messages.append(message)

    # 处理第一轮工具调用
    if "tool_calls" in message and message["tool_calls"]:
        tool_results = []

        # 执行所有工具调用
        for tool_call in message["tool_calls"]:
            function_name = tool_call["function"]["name"]
            function_args = json.loads(tool_call["function"]["arguments"])

            if function_name in tool_functions:
                try:
                    result = tool_functions[function_name](**function_args)
                    tool_results.append({
                        "role": "tool",
                        "tool_call_id": tool_call["id"],
                        "name": function_name,
                        "content": json.dumps(result)
                    })
                    print(f"✅ 调用 {function_name}: {function_args}")
                    print(f"📋 返回结果: {json.dumps(result, ensure_ascii=False, indent=2)}")
                except Exception as e:
                    tool_results.append({
                        "role": "tool",
                        "tool_call_id": tool_call["id"],
                        "name": function_name,
                        "content": json.dumps({"error": str(e)})
                    })
                    print(f"❌ 调用 {function_name} 失败: {e}")

        # 将工具调用结果添加到消息中
        messages.extend(tool_results)

        # 第二轮对话：处理工具调用结果
        second_request_data = {
            "model": model,
            "messages": messages,
            "tools": tools,
            "tool_choice": "auto"  # 可能需要进一步调用工具
        }

        second_response = requests.post(
            f"{base_url}/chat/completions",
            headers=headers,
            json=second_request_data
        )

        if second_response.status_code == 200:
            second_response_data = second_response.json()
            second_message = second_response_data["choices"][0]["message"]
            messages.append(second_message)

            # 检查是否有第二轮工具调用
            if "tool_calls" in second_message and second_message["tool_calls"]:
                print("\n🔄 进行第二轮工具调用...")

                second_tool_results = []
                for tool_call in second_message["tool_calls"]:
                    function_name = tool_call["function"]["name"]
                    function_args = json.loads(tool_call["function"]["arguments"])

                    if function_name in tool_functions:
                        try:
                            result = tool_functions[function_name](**function_args)
                            second_tool_results.append({
                                "role": "tool",
                                "tool_call_id": tool_call["id"],
                                "name": function_name,
                                "content": json.dumps(result)
                            })
                            print(f"✅ 第二轮调用 {function_name}: {function_args}")
                            print(f"📋 返回结果: {json.dumps(result, ensure_ascii=False, indent=2)}")
                        except Exception as e:
                            second_tool_results.append({
                                "role": "tool",
                                "tool_call_id": tool_call["id"],
                                "name": function_name,
                                "content": json.dumps({"error": str(e)})
                            })
                            print(f"❌ 第二轮调用 {function_name} 失败: {e}")

                # 将第二轮工具调用结果添加到消息中
                messages.extend(second_tool_results)

                # 第三轮对话：生成最终回答
                third_request_data = {
                    "model": model,
                    "messages": messages
                }

                third_response = requests.post(
                    f"{base_url}/chat/completions",
                    headers=headers,
                    json=third_request_data
                )

                if third_response.status_code == 200:
                    third_response_data = third_response.json()
                    return third_response_data["choices"][0]["message"]["content"]
                else:
                    print(f"第三次API请求失败: {third_response.status_code} - {third_response.text}")
                    return "抱歉，生成最终回答时出现错误。"
            else:
                # 没有第二轮工具调用，直接返回结果
                return second_message["content"]
        else:
            print(f"第二次API请求失败: {second_response.status_code} - {second_response.text}")
            return "抱歉，处理工具结果时出现错误。"

    return message["content"]

# 使用示例
if __name__ == "__main__":
    # 测试多轮工具调用
    test_cases = [
        "帮我搜索明天从北京到上海的航班",
        "我想预订一张从北京到上海明天航班的机票，乘客姓名是张三。直接预订第一个机票就行",
        "帮我查询并预订一张从广州到成都后天航班的机票，乘客是李四。直接预订第一个机票就行"
    ]

    for i, test_message in enumerate(test_cases, 1):
        print(f"\n{'='*60}")
        print(f"🚀 测试用例 {i}: {test_message}")
        print(f"{'='*60}")

        result = multi_tool_function_calling(test_message)
        print(f"\n🎯 最终回答:")
        print(result)
        print("\n" + "="*60)

运行这个示例，你可以看到AI如何智能地组合多个工具调用来完成复杂任务。比如用户说"帮我预订机票"，AI会先搜索航班，然后再根据搜索结果进行预订。

但是需要注意的是，我们必须加一个“直接预订第一个机票就行”的限定词，否则AI会咨询我们应该预订哪一张，就要等待用户确认了。这个逻辑在Demo中并没有实现。

4.3. 示例代码测试结果

以下是运行如上代码的终端输出结果，因为让AI帮忙加了些日志，所以看上去更详细。

首先是第一个测试用例，只是让AI进行了查询，没有让他进行预订。可以看到AI确实也没有去调用预订飞机的函数

============================================================
🚀 测试用例 1: 帮我搜索明天从北京到上海的航班
============================================================
✅ 调用 search_flights: {'origin': '北京', 'destination': '上海', 'date': '2023-10-06'}
📋 返回结果: [
  {
    "flight_id": "CA1234",
    "origin": "北京",
    "destination": "上海",
    "date": "2023-10-06",
    "departure_time": "08:30",
    "arrival_time": "11:45",
    "price": 1280,
    "available_seats": 15
  },
  {
    "flight_id": "MU5678",
    "origin": "北京",
    "destination": "上海",
    "date": "2023-10-06",
    "departure_time": "14:20",
    "arrival_time": "17:35",
    "price": 980,
    "available_seats": 8
  }
]

🎯 最终回答:
这里有两个航班选项：

1. 中国国航 CA1234，08:30 起飞，11:45 到达，票价 1280 元，剩余座位 15 个
2. 中国东航 MU5678，14:20 起飞，17:35 到达，票价 980 元，剩余座位 8 个

您需要预订其中一个航班吗？或者需要我帮您进一步筛选航班信息？

然后是第二个测试用例，我们要求AI进行预订了，可以看到AI先进行了查询，然后开始进行预订。因为我们在代码中写了可能预订失败的随机逻辑，可以看到AI在预订是失败的时候，也进行了提示，符合工具返回结果的预期值。

============================================================
🚀 测试用例 2: 我想预订一张从北京到上海明天航班的机票，乘客姓名是张三。直接预订第一个机票就行
============================================================
✅ 调用 search_flights: {'origin': '北京', 'destination': '上海', 'date': '2023-10-06'}
📋 返回结果: [
  {
    "flight_id": "CA1234",
    "origin": "北京",
    "destination": "上海",
    "date": "2023-10-06",
    "departure_time": "08:30",
    "arrival_time": "11:45",
    "price": 1280,
    "available_seats": 15
  },
  {
    "flight_id": "MU5678",
    "origin": "北京",
    "destination": "上海",
    "date": "2023-10-06",
    "departure_time": "14:20",
    "arrival_time": "17:35",
    "price": 980,
    "available_seats": 8
  }
]

🔄 进行第二轮工具调用...
✅ 第二轮调用 book_flight: {'flight_id': 'CA1234', 'passenger_name': '张三'}
📋 返回结果: {
  "success": false,
  "error": "座位已售罄，请选择其他航班"
}

🎯 最终回答:


很抱歉，CA1234航班已售罄。您是否想尝试预订其他可用的航班，例如MU5678（14:20起飞，17:35到达，票价980元）？或者还有其他需求需要协助吗？

============================================================

当第三个用例，预订成功的时候，输出的结果又不一样了：

============================================================
🚀 测试用例 3: 帮我查询并预订一张从广州到成都后天航班的机票，乘客是李四。直接预订第一个机票就行
============================================================
✅ 调用 search_flights: {'origin': '广州', 'destination': '成都', 'date': '后天'}
📋 返回结果: [
  {
    "flight_id": "CA1234",
    "origin": "广州",
    "destination": "成都",
    "date": "后天",
    "departure_time": "08:30",
    "arrival_time": "11:45",
    "price": 1280,
    "available_seats": 15
  },
  {
    "flight_id": "MU5678",
    "origin": "广州",
    "destination": "成都",
    "date": "后天",
    "departure_time": "14:20",
    "arrival_time": "17:35",
    "price": 980,
    "available_seats": 8
  }
]

🔄 进行第二轮工具调用...
✅ 第二轮调用 book_flight: {'flight_id': 'CA1234', 'passenger_name': '李四'}
📋 返回结果: {
  "success": true,
  "booking_id": "BKCA12341760838361",
  "flight_id": "CA1234",
  "passenger_name": "李四",
  "status": "confirmed"
}

🎯 最终回答:


您的航班已成功预订！以下是预订详情：

- **航班号**: CA1234  
- **出发地**: 广州  
- **目的地**: 成都  
- **日期**: 后天（2023-10-07）  
- **起飞时间**: 08:30  
- **到达时间**: 11:45  
- **票价**: 1280元  
- **预订号**: BKCA12341760838361  

订单状态：✅ 已确认  
请核对乘客姓名是否正确（李四），如有其他需求可随时告知！

============================================================

5. 工具设计最佳实践

到这里，关于Function Calling的格式和实践我们都已经了解啦，想必你已经知道如何通过OpenAI接口让大模型进行工具调用了。

下面给出一些函数设计方面的提示：

单一原则：一个函数只干一件事。不要设计通过某个参数让一个函数可以做两件事的逻辑。这种情况，需要拆分成两个函数
名称和参数命名规范：清晰规范的参数命名，能让AI直接通过参数和函数名称理解这个函数的作用，避免AI迷失在description的大海里面，到时候给你瞎调用
返回值简化：Function Call函数的返回值会算作上下文Token的一部分，在设计函数返回值的时候，一定要合理的简化函数的返回值，避免提供重复或者冗余的信息，这种会在多轮工具调用的时候占用Token，影响AI回答效果。
长返回值截断：对于某些工具可能会返回的超级长返回值，一定要设计截断逻辑，对返回值进行削减。建议工具返回值不要超过20K Tokens（这个值已经很大了，超过这个值就很容易直接一个工具干爆大模型上下文窗口）

在实际的设计环节，会包含如上最佳实践，让大家能够看到遵循和不遵循如上最佳实践的效果差异。

6. The end

Function Calling是AI Agent开发的核心技术，掌握它就等于掌握了让AI"干活"的能力。

随着AI技术的发展，Function Calling的能力已经越来越强，支持的工具类型也越来越丰富。现在一个claude code工具里面都的Agent，能为我们实现的能力已经非常非常牛逼了，比如我前几天更新的chrome-devtools-mcp的博客，AI已经能直接帮忙我们操作浏览器了，效果还不错！

根据本专栏目录，下一篇文章将介绍MCP协议，它是Function Calling的标准化扩展，让AI Agent开发更加规范和高效。这篇文章本站已有，请移步阅读：什么是MCP?

【MCP】无敌了，chrome-devtools-mcp杀死浏览器AI自动化的比赛！

2025-10-17T15:58:51.000Z

标题党了，不过chrome-devtools-mcp是真神啊，有些要用OpenAPI才能实现的东西，现在全都可以mcp，让AI操作浏览器去获取信息了。当然，前提是你不在乎Token消耗量。

1. 这是啥玩意？

如果你没有听说过MCP，还是先去看看本站之前的教程博客吧：点我

看完回来了，你现在应该知道MCP是啥玩意了。简单一句话概括，MCP服务端可以给AI客户端暴露一系列工具集。同时MCP标准化了这个服务端的接入方式，让我们的各种Agent工具都可以快速用上，不再需要对每个AI工具做单独开发适配。

如果你了解过前端开发，或者某些时候折腾过浏览器，那你一定知道，主流的浏览器都可以用F12打开一个开发者面板，在开发者面板里面，我们能看到网络请求信息、网页的源代码、控制台的打印等等信息……这些信息除了可以为前端开发Debug提供帮助，也对前端网页自动化测试（如selenium）有很大的作用。

AI时代来了之后，先后出现了brower-use、playwright这类工具，实现了部分网页的Agent自动化测试能力。这些工具的操作，本质上就是封装了一层自动化框架的能力，然后再把这部分能力暴露给AI，让AI理解网页内容，并进行自动化操作。

从前很多需要我们去调用平台提供的OpenAPI才能获取到的数据，都免了！这些工具，能让AI直接打开我们本地的Chrome，直接以用户的身份登录平台，装作一个普通用户，对网页进行操作，获取各类信息！也就是说，只要你能在打开网页后看到的信息，AI都能通过工具获取到，不再受平台OpenAPI的限制。

当然，OpenAPI和网页自动化是完完全全没有关系的东西，很多对数据实时性和获取准确性的场景，依旧需要我们借助平台提供的OpenAPI来实现能力的。不能认为有浏览器自动化工具了，这些网页平台就没必要提供OpenAPI了。OpenAPI提供的好，肯定更多人愿意使用OpenAPI的。

现在大的来了，谷歌直接开源了一个工具，这个工具能直接操作Chrome的DevTools，也就是直接操作开发者面板。这相当于从chrome原生，给AI加上了操作浏览器的工具集！不再是第三方提供了，谷歌自己下场，杀死比赛！

仓库：https://github.com/ChromeDevTools/chrome-devtools-mcp/

仓库使用了 Apache-2.0 license 开源协议，这个协议是允许免费商用的，只不过有些限制（具体的限制请自行查阅协议说明或咨询AI）。这样也直接放开了各大公司在自己的软件中集成chrome-devtools-mcp的权限。

2. 安装chrome-devtools-mcp

2.1. 安装

chrome-devtools-mcp是node编写的，需要有node环境，可以通过npx运行，也可以npm安装：

1	npm install -g chrome-devtools-mcp@latest

2.2. 配置MCP

官方文档中给出了如下的MCP配置方式：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

其中npx -y命令，本质上和我们先npm install -g chrome-devtools-mcp@latest再手动执行命令的效果是一样的。只不过我们添加了@latest标签，npx -y可以让我们每次运行的时候，都一定能运行到最新的版本（有更新的时候会自动拉取，没有更新使用本地缓存）。

咳咳咳，扯远了！这不重要。我们现在要做的是，把上面的内容写入某个目录的.mcp.json文件里面，然后在这个目录下运行claude code！

# 写入文件
echo {"mcpServers": {"chrome-devtools": {"command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"]}}} > .mcp.json
# 运行claude code
claude

如果配置正确，claude code会提示你当前已经链接上了chrome的mcp，齐活啦！

3. 使用一下

本文就不提什么自动化测试那么深入生产场景的玩意了。我们直接说日常可以怎么用这玩意。

举个非常简单的例子，有些博客平台、文档平台，并没有提供AI总结或者AI搜索的能力，我们就可以让Agent使用chrome的mcp工具来自己实现这个能力！

最小的尝试，就是让AI总结一篇博客。

注意，这个能力本身是可以通过fetch或者curl工具来简单实现的。但是对于某些要登录的平台，fetch工具或curl工具就有点小儿科了，因为涉及到了鉴权。chrome的mcp工具用的就是我们自己的chrome浏览器，本身就已经登录了，不再会有任何鉴权问题。就算是有人机验证或cloudflare墙的网站，我们也可以先人工过了验证，再让Agent来操作。

Prompt：

1	阅读 https://blog.musnow.top/posts/7079918377/ 总结内容

可以看到，GLM-4.6成功调用了devtools，打开了我的博客，总结了这篇文章的内容

同时chrome弹出来的页面，也会提示当前正在进行自动化，还是原生实现牛逼吧。

再来个稍微难一点的，让他在我的博客里面搜一下C语言相关文章：

1	请在 https://blog.musnow.top/ 搜索C语言相关文章

AI飞速操作，很快就找到了我博客的搜索页面，搜出了正确的内容！

回答也是非常准确！把收集到的结果都输出了！

4. The end

从上面两个非常小的用例，就能看出来这玩意潜力有多无限了。

不过，得说句公道话，慕雪并没有测试过brower-use和playwright，我相信这两个工具应该也能完成上述的两个工作。但如果谷歌自己都官方下场杀死比赛了，想必后续绝大部分Agent自动化网页测试，都会使用Chrome的这个mcp工具了。

一个字：牛！

AI时代，变化太快了，大家得跟上潮流哦。

【随笔】本地部署AI的现状和AI本地部署的价值

2025-10-08T13:38:56.000Z

随便写写，本地部署AI的现状和AI本地部署的价值。

1. 本地部署AI的最新动态

在一年以前，慕雪测试过Qwen1.5-32B模型，当时在5700x+7800xt的主机上，只跑出了6tok/sec的速度，完全处于不可用阶段。但如今，相同性能的Qwen3 30B的MoE模型，已经能非常流畅的运行，Qwen3 30B Q4量化版本甚至能在32GB内存的windows笔记本上纯CPU运行^[1]，速度依旧不差。

现在，本地部署AI的效果和成本都比先前好了太多。根据慕雪的实测^[2]，一台9800x3d+9070显卡+48GB的windows台式（全新价格约1w元），部署Qwen3-30B-A3B的Q8量化模型时，能跑出18tok/sec的速度，占用了25GB的内存。

慕雪个人认为，这个速度已经完全足够单人使用了。如果换成Q4量化的Qwen3-30B-A3B模型，Token生成速度会变成38tok/sec，拆分一下，甚至足以并发俩人一起访问。

Qwen官方也是在大力宣传之前的QwQ和这次的30B、80B两个MoE模型，主打一个“模型小小，能力大大”，能够在配置一般的机器上也跑起来，完成本地部署。

2. 这意味着什么呢？

那么问题来了：“上面叭叭了一大堆实测数据，这和月薪3K的我有什么关系？”

对于隐私要求不高的普通个人用户而言，本地部署模型就是纯纯鸡肋。没太多用户愿意花那么大价钱买一台电脑，只是为了不让自己发送给AI的资料被人看光光。

备注：这里说的是专门买一台电脑来本地部署AI，在自己的游戏电脑上部署着玩玩不在讨论范围之内。慕雪的意思是真的一直用自己本地部署的AI。

更有不少网友在网上质疑，本地部署的模型参数不够，性能太差，完全不足以满足需要。花大价钱却只能部署一个32B、72B的“人工智障”，没有任何意义。

但，这不代表小参数模型就没有用武之地，各大厂家更不会因为“看上去没啥用”就停止继续迭代越来越好的小模型。

设想下面这样的场景：

大模型的性能提升，让家用电脑能够部署的模型参数量越来越大、速度越来越快。小型的初创企业，能够花1到2万的预算（甚至更低），采购一台高配windows电脑或Mac，无需学习服务器部署AI等等专业知识，也不需要了解算法或编程，只要有一位对电脑使用稍微熟悉的IT人员，就能直接利用LM Studio或ollama这些工具，下载+部署模型，为整个公司提供本地化AI的能力。

从这一天开始，文职人员不再需要苦逼地自己对比各类报表，可以直接丢给AI让他帮忙对比（至少小规模的文件肯定够用的）
从这一天开始，运营人员可以让AI帮忙润色公司的活动文档，不再需要把文档发送给外部AI之前把所有敏感信息都替换掉。
从这一天开始，HR在筛候选人简历的时候，可以放松大胆的把PDF直接发给本地AI，让他总结简历的关键词，对比不同候选者的优势，而不用担心把别人简历传云端大模型对候选者造成的隐私泄露。
还有很多很多……

这些小微企业不需要借助AI来编码，他们只是需要一个能辅助他们日常工作的AI，同时也不会泄露公司信息，就足够了。从这个角度出发，30B、32B的小尺寸模型已经完全能够满足需要！

在以前，需要一台机架服务器、轰鸣的暴力风扇、专门的机房才能完成的本地AI能力，现在只需要一台游戏台式机、一台MAC、甚至一台windows轻薄本，就能完成类似的工作。这便是小模型迭代的意义！

大模型的发展，就好比电脑的发展一样。以windows笔记本电脑市场为例。如果你长期关注过笔记本市场，那你肯定知道，现在的笔记本越来越便宜了。早在5年前，想用3000元买一台不坑爹的笔记本都是一件不可想象的事，基本上只能买intel的i3笔记本+低色域屏幕+8G内存，没有啥好的选择。但现在，3000已经可以买到16+512的8核CPU的笔记本了，对于办公和编程学习而言都够用了。

小结如下：

笔记本电脑的发展，让笔电的价格越来越低，越来越多人能够买得起一台配置尚可的笔记本，加入电脑使用者的行列。
大模型的发展，让大模型部署成本越来越低，越来越多的中小微企业能够部署上自己的本地大模型，让AI赋能公司的运作。提高很多事项上的效率！

科技发展的意义，就是让越来越多人，能够接触到最新的科技，能够使用上最新的能力。让科技普惠到更多人。

3. 我想本地部署大模型，买啥设备好？

如果你只是想部署着玩玩，直接按高配游戏电脑去买就行了。能部署多少B的模型直接看显卡显存就差不多能预估出来（拿显存乘0.8预估参数量）。

但如果你想认真的学学或者折腾一下大模型部署、微调，MAC是更好的选择。目前比较推荐的起步配置是M4Pro 48GB的Mac mini。部署Qwen3-30B-A3B q4的速度高达60t/s，非常牛逼。

极客湾在直播中也提到了，MAC Studio针对的就是个人消费者和小微企业，对于AI部署来说，它的功耗更低，体积更小，上手更简单，这便是它的优势^[3]。

不过呢，价格肯定是不美丽的。

如果你只是玩玩，还是买普通的游戏电脑吧，多少能打打游戏呢。

4. The end

科技的发展，永远是时代的潮流。AI时代，是近十年来最大的变革，不管是互联网大厂，还是中小微企业，都会想尽办法，拥抱这个潮流，不让自己的公司落伍。

我们个人也是一样，尽可能多的使用AI、了解AI行业动态、学习AI相关知识，让AI为我们的生活、学习、工作助力，成为AI时代的“弄潮儿”。

怎么写成了语文作文结尾了……

视频：Qwen3-30B-A3B在DDR5 32G纯CPU内存跑23 tokens每秒 ↩︎
完整实测数据和截图详见此博客文末的表格：https://blog.musnow.top/posts/3021867508/ ↩︎
https://www.bilibili.com/video/BV1ELQhYREvK ↩︎

【Node】实现一个claude-code模型切换器

2025-10-05T23:18:52.000Z

慕雪前排提醒：本文依旧是AI生成的，有少量人工修改。

在上一篇文章中，我介绍了如何配置Claude Code使用美团LongCat等第三方大模型。但是每次切换模型都需要手动修改配置文件，实在是太麻烦了。

于是，我写了一个小工具来解决这个问题：claude-code-model-switch（简称ccms）。

1. 为什么要做这个工具

用过Claude Code的朋友都知道，它支持接入各种第三方大模型，比如美团LongCat、DeepSeek、智谱GLM等等。但是每次切换模型都需要：

打开~/.claude/settings.json配置文件
修改一堆环境变量
保存文件
重新启动Claude Code

这个过程重复多了真的很烦人，而且容易出错。比如忘了改某个变量，或者把配置搞乱了。

所以我就想，能不能像nvm管理node版本那样，用一个命令行工具来管理Claude Code的模型配置呢？

说干就干，直接claude --dangerously-skip-permissions启动！开始写一个。

2. 工具功能

ccms工具提供了以下几个核心功能：

2.1. 快速切换模型

# 切换到deepseek-chat模型
ccms deepseek-chat

# 或者使用switch子命令
ccms switch deepseek-chat

2.2. 查看可用模型

1 2	# 列出所有配置好的模型 ccms list

2.3. 恢复官方模型

1 2	# 清除所有模型配置，恢复使用官方Claude模型 ccms unset

2.4. 查看配置文件路径

1 2	# 查看模型配置文件和Claude设置文件的路径 ccms config-path

3. 安装和使用

3.1. 安装

1	npm install -g claude-code-model-switch

3.2. 配置模型

安装完成后，需要先配置你想要使用的模型。编辑配置文件~/.claude-code-model-switch/settings.json：

{
  "models": {
    "deepseek-chat": {
      "ANTHROPIC_AUTH_TOKEN": "sk-your-token-here",
      "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
      "ANTHROPIC_MODEL": "deepseek-chat",
      "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat",
      "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-chat",
      "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-chat",
      "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "8192",
      "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
    },
    "longcat-flash": {
      "ANTHROPIC_AUTH_TOKEN": "your-longcat-token",
      "ANTHROPIC_BASE_URL": "https://api.longcat.chat/anthropic",
      "ANTHROPIC_MODEL": "LongCat-Flash-Chat",
      "ANTHROPIC_SMALL_FAST_MODEL": "LongCat-Flash-Chat",
      "ANTHROPIC_DEFAULT_SONNET_MODEL": "LongCat-Flash-Chat",
      "ANTHROPIC_DEFAULT_OPUS_MODEL": "LongCat-Flash-Chat",
      "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "8192",
      "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
    },
    "glm-4.6": {
      "ANTHROPIC_AUTH_TOKEN": "your-glm-token",
      "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
      "ANTHROPIC_MODEL": "GLM-4.6",
      "ANTHROPIC_SMALL_FAST_MODEL": "GLM-4.6",
      "ANTHROPIC_DEFAULT_SONNET_MODEL": "GLM-4.6",
      "ANTHROPIC_DEFAULT_OPUS_MODEL": "GLM-4.6",
      "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
      "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
    }
  }
}

3.3. 使用示例

配置好模型后，就可以愉快地切换了：

# 切换到DeepSeek模型
ccms deepseek-chat

# 切换到美团LongCat模型
ccms longcat-flash

# 切换到智谱GLM模型
ccms glm-4.6

# 恢复使用官方Claude模型
ccms unset

4. 技术实现

这个工具的实现其实挺简单的，主要就是：

4.1. 文件操作

读取和解析~/.claude/settings.json配置文件
读取和解析~/.claude-code-model-switch/settings.json模型配置
安全地修改Claude配置文件中的环境变量

4.2. 命令行界面

使用commander库来构建命令行界面，支持：

参数解析
子命令
帮助信息
版本信息

4.3. 安全设计

工具设计时特别注意了安全性：

只修改模型相关变量：不会触及配置文件中的其他设置
默认值处理：自动处理缺失的配置项
错误处理：友好的错误提示和帮助信息

5. 发布到npm

项目已经发布到npm商店，可以直接安装使用：

1	npm install -g claude-code-model-switch

6. 总结

用了这个工具之后，切换模型真的方便多了。如果你也经常在多个大模型之间切换，不妨试试这个工具。

工具还在不断完善中，欢迎大家使用和反馈问题。如果你有新的需求或者发现了bug，可以在GitHub上提issue。

这里顺带解答一下一些朋友可能有的疑惑：这个项目的能力是不是可以用claude-code-router替代？

并不！二者算是不同方向的能力！

claude-code-router本质上是聚合了很多个模型服务商，再对cc统一暴露一个本地url进行服务提供。
当你需要修改claude-code-router使用的模型的时候，你需要修改claude-code-router配置文件，没办法用ccr命令搞定。
本项目的模型切换是直接基于cc自带的环境变量设置实现的，没有ccr那么复杂的逻辑。能切换到的模型服务商也必须是原生提供了anthropic api的服务商，没有提供anthropic的服务商，只能用ccr转发接入。

所以，你可以在本项目的配置文件中把ccr也配置上，这样你也能切换到ccr去！

【Hexo】Butterfly主题站点运行时间实现n年m天格式显示

2025-10-02T08:30:00.000Z

慕雪前排提醒：本文所有内容包括修改点都是AI分析、修改并总结的，纯粹是AI写的，没有半点人工（除了两张截图是我贴上去的）。使用的是GLM-4.6和Claude Code。

前言

在博客网站的侧边栏中，显示站点运行时间是一个很常见的功能。通常我们会看到"1265 天"这样的显示方式，但对于长时间运行的站点来说，这种显示方式不够直观。最近我为Hexo Butterfly主题增加了一个新功能，支持将站点运行时间显示为"3 年 154 天"的格式，这样用户可以更直观地了解站点的运行历史。

本文将详细介绍这个功能的实现过程，包括配置项的添加、JavaScript代码的修改以及相关文件的调整。

功能概述

这个修改主要实现了以下功能：

配置选项：在主题配置中添加runtime_format选项，支持两种格式：

days：默认格式，显示总天数（如：1265 天）
year_day：年天格式，显示年数和剩余天数（如：3 年 154 天）

智能显示：当运行时间不足一年时，仍显示天数格式，避免出现"0 年"的尴尬情况

向下兼容：保持与原有功能的完全兼容，默认使用原有的天数显示方式

实现步骤

1. 配置文件修改

首先需要在主题配置文件_config.butterfly.yml中添加新的配置选项：

aside:
  card_webinfo:
    # 站点运行时间起始日期
    runtime_date: 04/16/2022 00:00:00
    # 运行时间格式：days（默认）或 year_day
    # days: 显示天数（如：1265 天）
    # year_day: 显示年天格式（如：3 年 154 天）
    runtime_format: year_day

同时在merge_config.js中添加默认配置：

// themes/butterfly/scripts/events/merge_config.js
aside: {
  card_webinfo: {
    post_count: true,
    last_push_date: true,
    sort_order: null,
    runtime_date: null,
    runtime_format: 'days'  // 新增默认配置
  }
}

2. 前端配置传递

在config.pug模板中将配置传递给前端JavaScript：

// themes/butterfly/layout/includes/head/config.pug
script.
  window.GLOBAL_CONFIG = {
    // ... 其他配置
    runtime: '!{theme.aside.card_webinfo.runtime_date ? _p("aside.card_webinfo.runtime.unit") : ""}',
    runtime_format: '!{theme.aside.card_webinfo.runtime_format || "days"}',
    // ... 其他配置
  }

3. 核心时间计算逻辑

主要的时间计算逻辑在utils.js中的diffDate函数中实现：

// themes/butterfly/source/js/utils.js
diffDate(date, more = false) {
  const datePost = new Date(date)
  const dateNow = new Date()
  const diffTime = dateNow - datePost
  const diffSecond = Math.round(diffTime / 1000)
  const diffDay = Math.floor(diffSecond / 86400)
  const diffMonth = diffDay / 30
  const { dateSuffix } = GLOBAL_CONFIG

  if (!more) {
    const totalDays = Math.floor(diffDay)

    // 如果启用了年天格式转换
    if (GLOBAL_CONFIG.runtime_format === 'year_day' && totalDays >= 365) {
      const years = Math.floor(totalDays / 365)
      const days = totalDays % 365

      if (years > 0 && days > 0) {
        return `${years} 年 ${days} 天`
      } else if (years > 0) {
        return `${years} 年`
      } else {
        return `${days} 天`
      }
    }

    return totalDays
  }

  // ... 其他时间差处理逻辑
}

4. 显示逻辑优化

在main.js中优化显示逻辑，避免重复显示单位：

// themes/butterfly/source/js/main.js
showRuntime() {
  const $runtimeCount = document.getElementById('runtimeshow')
  if ($runtimeCount) {
    const publishDate = $runtimeCount.getAttribute('data-publishDate')
    const runtimeText = btf.diffDate(publishDate)

    // 如果使用年天格式且已经包含年或天字，则不再添加单位
    if (GLOBAL_CONFIG.runtime_format === 'year_day' &&
        (runtimeText.includes('年') || runtimeText.includes('天'))) {
      $runtimeCount.textContent = runtimeText
    } else {
      $runtimeCount.textContent = `${runtimeText} ${GLOBAL_CONFIG.runtime}`
    }
  }
}

关键实现细节

1. 时间计算逻辑

核心的时间计算逻辑基于以下规则：

1年 = 365天（不考虑闰年的复杂性）
使用整数除法和取模运算分别计算年数和剩余天数
只有当总天数大于等于365天时，才使用年天格式

2. 显示格式处理

处理显示格式时需要注意：

年天格式已包含单位，无需额外添加
传统天数格式仍需添加"天"单位
避免显示"0 年"的情况，提升用户体验

3. 配置兼容性

为了保持向下兼容：

新配置项有默认值
旧配置不受影响
可以随时切换显示格式

效果展示

修改后的效果如下：

传统格式：站点运行时间 : 1265 天

年天格式：站点运行时间 : 3 年 154 天

对于运行时间较短的站点（不足一年），两种格式都会显示为天数，避免出现"0 年"的显示。

总结

这个功能的实现相对简单，但能显著提升用户体验。通过合理的配置设计和代码实现，我们既保持了向后兼容性，又提供了更灵活的时间显示方式。

主要收获：

配置驱动：通过配置项控制功能，提高灵活性
渐进增强：在不破坏原有功能的基础上添加新特性
用户体验：考虑各种边界情况，提供友好的显示方式
代码组织：合理分离配置、计算和显示逻辑

这种实现方式可以作为其他主题功能扩展的参考模板。如果你也想为自己的Hexo主题添加类似功能，可以参考本文的实现思路。

【Hexo】为自己的博客站点加上离线的AI摘要

2025-10-02T01:08:21.000Z

参考大佬的教程，为自己的博客站点加上了离线的AI摘要。

1. 写在前面

之前逛个个大佬的个人博客的时候，发现有不少大佬都给自己的博客文章开头加上了一个AI摘要的功能。我也想过类似的功能，但是当时以为这些AI摘要都是实时请求的，会太消耗Token，于是就没有处理了。

查询了一下相关信息，hexo-ai-summaries插件是将博客摘要写入一个独立的目录下，本质上也是离线的。不会在用户访问的时候在线请求OpenAI API接口，不会有我担心的消耗Token问题（我之前一直以为是每被访问一次就会请求一次AI呢……）

今天心血来潮又去搜了一下相关的教程，找到了LiuShen大佬fork制作的一份只需要hexo的front-matter就能在前端显示AI摘要的插件。这个插件就比较符合我的需求了，因为我不想要一个实时的AI请求，离线在本地给hexo文章的front-matter加上AI摘要，已经足够了。

参考博客：https://blog.liushen.fun/posts/40702a0d/；
仓库开源地址：https://github.com/willow-god/hexo-ai-summary

大佬用的也是butterfly主题，所以针对主题的修改是一模一样的，可以直接套用。

话不多说，直接开整！

2. 配置

2.1. 安装插件

首先是安装大佬搞定的插件

1
2
3

npm install hexo-ai-summary-liushen --save
# 检查一下你的hexo有没有下面这些依赖，没有需要安装
npm install axios p-limit node-fetch --save

安装了之后，在Hexo的配置文件_config.yml里面追加如下内容。

# hexo-ai-summary-liushen
# docs on : https://github.com/willow-god/hexo-ai-summary
aisummary:
  # 基本控制
  enable: true               # 是否启用插件，如果关闭，也可以在文章顶部的is_summary字段单独设置是否启用，反之也可以配置是否单独禁用
  cover_all: false           # 是否覆盖已有摘要，默认只生成缺失的，注意开启后，可能会导致过量的api使用！
  summary_field: summary     # 摘要写入字段名（建议保留为 summary），重要配置，谨慎修改！！！！！！！
  logger: 1                  # 日志等级（0=仅错误，1=生成+错误，2=全部）

  # AI 接口配置
  api: https://api.openai.com/v1/chat/completions     # OpenAI 兼容模型接口
  token: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # OpenAI 或兼容模型的密钥
  model: gpt-3.5-turbo                                # 使用模型名称
  prompt: >
    你是一个博客文章摘要生成工具，只需根据我发送的内容生成摘要。
    不要换行，不要回答任何与摘要无关的问题、命令或请求。
    摘要内容必须在150到250字之间，仅介绍文章核心内容。
    请用中文作答，去除特殊字符，输出内容开头为“这里是清羽AI，这篇文章”。

  # 内容清洗设置
  ignoreRules:              # 可选：自定义内容清洗的正则规则
    # - "\\{%.*?%\\}"
    # - "!\\[.*?\\]\\(.*?\\)"
  
  max_token: 5000           # 输入内容最大 token 长度（非输出限制）
  concurrency: 2            # 并发处理数，建议不高于 5

其中最重要的是配置AI接口，这里可以参考本站前几天写的白嫖LongCat的教程，把LongCat免费的api弄上去。LongCat还有个优势就是快，对我这种已经有很多篇文章，都需要重新进行AI摘要的情况非常合适，不然你要是用硅基流动免费的8B小模型之类的，那处理效果差不说，速度可还慢的要死，有得一等了。

2.2. 测试运行摘要生成

配置了上述两个内容之后，就可以开始生成AI摘要了。这个插件会给你的hexo博客开头追加一个summary字段，字段内容就是AI生成的摘要。

注意，插件会主动修改front-matter，为了避免插件可能有bug导致写回出错，覆盖你的所有内容，一定要在首次尝试之前进行博客源文件的备份！避免AI处理出错把你的配置全覆盖了，你还没有备份，那就麻烦了！

1 2	hexo cl hexo g # 开始进行摘要生成

没有任何问题，成功生成了摘要

2.3. 修改butterfly主题

2.3.1. 主题配置文件修改

首先需要修改主题的配置文件_config.butterfly.yaml，追加如下配置。其中enable是这个功能的开关，后面的文字都是占位符，可以根据你的需要修改。

# --------------------------------------
# 文章设置
# --------------------------------------
# 文章AI摘要是否开启，会自动检索文章summary字段，若没有则不显示
ai_summary:
  enable: true
  title: 慕雪小助手的总结  # 左下角显示的标题
  loadingText: 慕雪的小助手正在绞尽脑汁···
  modelName: LongCat-Flash-Chat  # 显示的模型名称

2.3.2. 主题pug修改

随后需要修改主题源码文件，新增针对AI摘要的处理。

首先是修改theme/butterfly/layout/post.pug文件，在第8行之后新增两行内容。注意添加的时候需要严格缩进，避免格式错误

article#article-container.container.post-content
  //- 添加下面这两行
  if page.summary && theme.ai_summary.enable
    include includes/post/post-summary.pug

然后添加组件，创建文件theme/butterfly/layout/includes/post/post-summary.pug，写入以下内容：

.ai-summary
    .ai-explanation(style="display: block;" data-summary=page.summary)=theme.ai_summary.loadingText
    .ai-title 
        .ai-title-left 
            i.fa-brands.fa-slack
            .ai-title-text=theme.ai_summary.title
        .ai-tag#ai-tag= theme.ai_summary.modelName

2.3.3. 主题样式修改

然后添加样式到theme/butterfly/source/css/_layout/ai-summary.styl文件

// ===================
// 🌗 主题变量定义（仅使用项）
// ===================

:root
  // ai_summary
  --liushen-title-font-color: #0883b7
  --liushen-maskbg: rgba(255, 255, 255, 0.85)
  --liushen-ai-bg: conic-gradient(from 1.5708rad at 50% 50%, #d6b300 0%, #42A2FF 54%, #d6b300 100%)

  // card 背景
  --liushen-card-secondbg: #f1f3f8

  // text
  --liushen-text: #4c4948
  --liushen-secondtext: #3c3c43cc

[data-theme='dark']
  // ai_summary
  --liushen-title-font-color: #0883b7
  --liushen-maskbg: rgba(0, 0, 0, 0.85)
  --liushen-ai-bg: conic-gradient(from 1.5708rad at 50% 50%, rgba(214, 178, 0, 0.46) 0%, rgba(66, 161, 255, 0.53) 54%, rgba(214, 178, 0, 0.49) 100%)

  // card 背景
  --liushen-card-secondbg: #3e3f41

  // text
  --liushen-text: #ffffffb3
  --liushen-secondtext: #a1a2b8

// ===================
// 📘 AI 摘要模块样式
// ===================

if hexo-config('ai_summary.enable')
  .ai-summary
    background-color var(--liushen-maskbg)
    background var(--liushen-card-secondbg)
    border-radius 12px
    padding 8px 8px 12px 8px
    line-height 1.3
    flex-direction column
    margin-bottom 24px
    display flex
    gap 5px
    position relative

    &::before
      content ''
      position absolute
      top 0
      left 0
      width 100%
      height 100%
      z-index 1
      filter blur(8px)
      opacity .4
      background-image var(--liushen-ai-bg)
      transform scaleX(1) scaleY(.95) translateY(2px)
    
    &::after
      content: '';
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;
      z-index: 2;
      border-radius: 12px;
      background: var(--liushen-maskbg);

    .ai-explanation
      z-index 10
      padding 8px 12px
      font-size 15px
      line-height 1.4
      color var(--liushen-text)
      text-align justify

      // ✅ 打字机光标动画
      &::after
        content ''
        display inline-block
        width 8px
        height 2px
        margin-left 2px
        background var(--liushen-text)
        vertical-align bottom
        animation blink-underline 1s ease-in-out infinite
        transition all .3s
        position relative
        bottom 3px

      // 平滑滚动动画
      // .char
      //   display inline-block
      //   opacity 0
      //   animation chat-float .5s ease forwards
    
    .ai-title
      z-index 10
      font-size 14px
      display flex
      border-radius 8px
      align-items center
      position relative
      padding 0 12px
      cursor default
      user-select none

      .ai-title-left
        display flex
        align-items center
        color var(--liushen-title-font-color)

        i
          margin-right 3px
          display flex
          color var(--liushen-title-font-color)
          border-radius 20px
          justify-content center
          align-items center

        .ai-title-text
          font-weight 500

      .ai-tag
        color var(--liushen-secondtext)
        font-weight 300
        margin-left auto
        display flex
        align-items center
        justify-content center
        transition .3s

  // 平滑滚动动画
  // @keyframes chat-float
  //   0% 
  //     opacity 0
  //     transform translateY(20px)
  //   100% 
  //       opacity 1
  //       transform translateY(0)
  
  // ✅ 打字机光标闪烁动画
  @keyframes blink-underline
    0%, 100%
      opacity 1
    50%
      opacity 0

2.3.4. 追加打字机JS

下面的js文件可以随意放到一个source目录下，在主题里面引用上就行了。

这里我是放到了source/js/typing_style.js里面，然后修改主题配置文件，在header里面引入了这个js文件。

# Inject
inject:
  head:
    # ai总结能力打字机效果
    -  src="/js/typing_style.js">

js文件内容如下

// 打字机效果
function typeTextMachineStyle(text, targetSelector, options = {}) {
    const {
        delay = 50,
        startDelay = 2000,
        onComplete = null,
        clearBefore = true,
        eraseBefore = true, // 新增：是否以打字机方式清除原文本
        eraseDelay = 30,    // 新增：删除每个字符的间隔
    } = options;

    const el = document.querySelector(targetSelector);
    if (!el || typeof text !== "string") return;

    setTimeout(() => {
        const startTyping = () => {
            let index = 0;
            function renderChar() {
                if (index <= text.length) {
                    el.textContent = text.slice(0, index++);
                    setTimeout(renderChar, delay);
                } else {
                    onComplete && onComplete(el);
                }
            }
            renderChar();
        };

        if (clearBefore) {
            if (eraseBefore && el.textContent.length > 0) {
                let currentText = el.textContent;
                let eraseIndex = currentText.length;

                function eraseChar() {
                    if (eraseIndex > 0) {
                        el.textContent = currentText.slice(0, --eraseIndex);
                        setTimeout(eraseChar, eraseDelay);
                    } else {
                        startTyping(); // 删除完毕后开始打字
                    }
                }

                eraseChar();
            } else {
                el.textContent = "";
                startTyping();
            }
        } else {
            startTyping();
        }
    }, startDelay);
}

function renderAISummary() {
    const summaryEl = document.querySelector('.ai-summary .ai-explanation');
    if (!summaryEl) return;

    const summaryText = summaryEl.getAttribute('data-summary');
    if (summaryText) {
        typeTextMachineStyle(summaryText, ".ai-summary .ai-explanation"); // 如果需要切换，在这里调用另一个函数即可
    }
}

document.addEventListener('pjax:complete', renderAISummary);
document.addEventListener('DOMContentLoaded', renderAISummary);

3. 最终效果

如图所示，效果不错，可行！

小Tips：如果你觉得这个AI总结框和正文间隔太小了，可以修改theme/butterfly/source/css/_layout/ai-summary.styl里面的.ai-summary的margin-bottom 24px，把24px进一步加大即可，本站设置成了36px。

4. 发现插件的几个小问题

4.1. 请求超过RPM

然后我就发现了几个小问题，首先，LongCat实在是返回的太快了！会出现超RPM的情况^[1]。这需要在插件里面新增一个配置项，每次请求之后都sleep等待再发起下一个请求。

[Hexo-AI-Summary-LiuShen] 原始字符串长度： 8728
[Hexo-AI-Summary-LiuShen] 最终输出长度： 1945
[Hexo-AI-Summary-LiuShen] 生成摘要失败：【C语言】传值调用和传址调用
AI 请求失败: AI 请求失败 (429): {"error":{"message":"App:**xxxx在模型:longcat-flash-chatai-api每分钟请求次数超过限制","type":"rate_limit_error","code":"rate_limit_exceeded"}}

这个问题我已经提交了PR：https://github.com/willow-god/hexo-ai-summary/pull/2，等待原作者合并。如果你也遇到了类似的问题，可以直接修改本地node_moudles下的代码node_modules/hexo-ai-summary-liushen/index.js，写死一个休眠时间，翻到文件的最后，在文件最后的return data之前加一个休眠时间（毫秒）就行了。

        // ...
        // 这里新增一个休眠时间，2000ms就是2秒
        await new Promise(resolve => setTimeout(resolve, 2000))
        return data
    })
})

需要注意的是，本地node_moudles的修改只针对本地生效，如果你用了vercel、netlify等部署平台，这个操作是不会生效的。

4.2. AI返回的结果里面可能有换行

除了超RPM的问题，慕雪还遇到了AI返回的结果出现了换行的问题。所以，需要在插件对AI结果的解析中，把所有换行符\n变成空格。这部分我看插件的ai.js的第42行已经有了，用正则进行了替换。

// 后处理与校验
const cleaned = reply
  .replace(/[\r\n]+/g, ' ') // 去换行
  .replace(/\s+/g, ' ')     // 合并多空格
  .trim()

后来又查了查资料，了解到yaml只要用>-开头，后续的内容都会合并成一行显示的，是符合语法规则的，所以没有问题。

可以在prompt里面进一步警示AI“禁止输出任何换行”，让他别输出有换行的内容。

4.3. 使用vercel、netlify等平台如何进行同步？

这里还有另外一个问题。如果你像慕雪一样，用了vercel、netlify等平台进行自动部署，那么hexo三板斧都是在vercel和netlify服务器上进行的，虽然也会请求AI，修改hexo文件，但是生成的摘要和修改后的文件都是在vercel和netlify的服务器上，不会写到你的hexo配置仓库里面。

这就会导致，如果你没有在本地运行hexo g命令手动执行插件，那么你新增的博客就永远不会有summary总结字段了。

所以，使用这个插件，最好还是定期手动去你的hexo仓库里面执行一下hexo g，把新增的博客全都搞上，免得每次Vercel和Netlify部署的时候，都需要给没有摘要的博客重新生成摘要。

5. 当前本站使用的构建方案的困境

慕雪现在使用的hexo部署方案，是从obsidian直接触发的^[2]，基本流程如下：

obsidian内使用了git插件，自动commit+push到obsidian仓库
obsidian仓库配置了Github Action，会自动把obsidian的博客文件夹和Hexo源配置仓库的source/_post目录进行同步，将obsidian修改的博客推送到Hexo源配置仓库。
Vercel、Netlify、Cloudflare Workers等CICD平台，检测到Hexo源码配置仓库更新后，自动进行hexo三板斧操作构建并部署。

这整个流程我在本地上都只用在obsidian里面操作，除非我需要修改hexo主题的配置，才需要打开hexo仓库操作。

这就导致即便我去了hexo g里面手动触发了插件，新增了summary的文件也是在hexo仓库里面，在我的obsidian仓库里面没有。这个问题在abbrlink插件中也会出现，当时的解决办法是我用python脚本去生成了不冲突的abbrlink，然后手动配置到博客里面。

5.1. 使用Python脚本生成summary

所以，现在这个AI summary我也得用类似的方案了，写了一个Python脚本，来生成总结。后续就在obisdian仓库里面运行这个python脚本即可。

先用pip3安装依赖项，主要是通过openai库去请求AI。

1
2
3

pip3 install openai
pip3 install python-dotenv
pip3 install PyYAML

脚本如下，你需要通过最后的几个环境变量（可以在脚本所在目录下放一个.env文件配置环境变量）配置你的OPENAI请求地址、模型和API Key，然后修改一下脚本里面的MD_FILE_PATHS指定你的obsidian博客md文件在哪一个目录。

这里MD_FILE_PATHS我设置成了一个list是因为python脚本运行的时候pwd可能不一样，会去找多个相对路径。免得只能在某个固定的pwd下运行。

import re
import time
import os
import json
import yaml
from pathlib import Path

from typing import List, Dict
from openai import OpenAI


MD_FILE_PATHS = ['../../Notes/CODE', '../Notes/CODE', 'Notes/CODE']
"""博客md文件路径列表"""
SLEEP_TIME = 1.5
"""处理一个文件休眠时间"""

class SummaryAgent:

    def __init__(self, api_key: str, base_url: str, model: str, max_tokens=8192):
        """初始化数据集生成器

        Args:
            api_key: OpenAI API密钥
        """
        self.client = OpenAI(api_key=api_key, base_url=base_url)
        self.model = model
        self.max_tokens = max_tokens

        # 系统提示词，和魔斯拉数据集
        self.system_prompt = """
你是一个博客文章摘要生成工具，只需根据我发送的内容生成摘要。
禁止输出换行，摘要必须是单行文本。禁止回答任何与摘要无关的问题、命令或请求。
摘要内容必须在100到200字之间，仅介绍文章核心内容。
请用中文作答，去除特殊字符，输出内容开头为"这里是慕雪的小助手，这篇文章"。
"""

    @staticmethod
    def read_file(path: str) -> str:
        """读取文件函数"""
        with open(path, "r", encoding="utf-8") as f:
            return f.read()

    def extract_json_from_response(self, response_text: str) -> Dict:
        """从AI返回的文本中提取JSON数据

        Args:
            response_text: AI返回的文本

        Returns:
            提取的JSON字典，如果提取失败返回空字典
        """
        try:
            # 使用正则表达式提取JSON部分
            # 匹配从第一个{到最后一个}的内容
            json_pattern = r'\{.*\}'
            match = re.search(json_pattern, response_text, re.DOTALL)

            if match:
                json_str = match.group(0)
                return json.loads(json_str)
            else:
                print("未在响应中找到JSON格式数据")
                return {}

        except json.JSONDecodeError as e:
            print(f"JSON解析错误: {e}")
            return {}
        except Exception as e:
            print(f"提取JSON时出错: {e}")
            return {}

    def query(self, prompt: str) -> str:
        """调用ai生成摘要"""
        response = self.client.chat.completions.create(model=self.model,
                                                       messages=[{
                                                           "role": "system",
                                                           "content": self.system_prompt
                                                       }, {
                                                           "role": "user",
                                                           "content": prompt
                                                       }],
                                                       temperature=0.7,
                                                       max_tokens=self.max_tokens)

        response_text = response.choices[0].message.content
        print(f"[AI]  AI响应长度: {len(response_text)} 字符")
        return response_text


class MarkdownProcessor:
    """Markdown文件处理器"""

    @staticmethod
    def find_markdown_files(notes_dirs: List[str]) -> List[str]:
        """查找多个Notes目录中的所有markdown文件"""
        all_md_files = []

        for notes_dir in notes_dirs:
            notes_path = Path(notes_dir)
            if not notes_path.exists():
                print(f"跳过：Notes目录不存在: {notes_dir}")
                continue
            
            md_files = list(notes_path.rglob("*.md"))
            print(f"在 {notes_dir} 中找到 {len(md_files)} 个markdown文件")
            all_md_files.extend([str(f) for f in md_files])
            break # 只处理一个目录

        print(f"总共找到 {len(all_md_files)} 个markdown文件")
        return all_md_files

    @staticmethod
    def parse_front_matter(content: str) -> tuple[Dict, str, str]:
        """解析front-matter并返回front-matter字典和剩余内容

        Returns:
            tuple: (front_matter_dict, front_matter_str, content_without_front_matter)
        """
        front_matter_pattern = r'^---\s*\n(.*?)\n---\s*\n'
        match = re.search(front_matter_pattern, content, re.DOTALL)

        if match:
            front_matter_str = match.group(1)
            content_without_front_matter = content[match.end():]

            # 使用yaml库解析YAML front-matter
            try:
                front_matter = yaml.safe_load(front_matter_str) or {}
            except yaml.YAMLError as e:
                print(f"YAML解析错误: {e}")
                front_matter = {}

            return front_matter, front_matter_str, content_without_front_matter
        else:
            # 如果没有front-matter，返回空的front-matter和完整内容
            return {}, "", content

    @staticmethod
    def add_summary_to_front_matter(content: str, summary: str) -> str:
        """在front-matter中添加summary字段

        Args:
            content: 原始文件内容
            summary: 要添加的摘要

        Returns:
            修改后的文件内容
        """
        front_matter, _, remaining_content = MarkdownProcessor.parse_front_matter(content)

        # 确保summary是单行
        summary = summary.replace('\n', ' ').strip()

        # 如果没有front-matter，创建一个新的
        if not front_matter:
            return f"---\nsummary: {summary}\n---\n{content}"

        # 如果已经有summary字段，替换它
        if 'summary' in front_matter:
            front_matter['summary'] = summary
            # 使用yaml库重新构建front-matter字符串
            try:
                front_matter_yaml = yaml.dump(front_matter, allow_unicode=True, default_flow_style=False)
                new_front_matter_str = f"---\n{front_matter_yaml}---\n"
            except yaml.YAMLError as e:
                print(f"YAML序列化错误: {e}")
                # 如果yaml序列化失败，使用简单格式
                new_front_matter_lines = ['---']
                for key, value in front_matter.items():
                    new_front_matter_lines.append(f"{key}: {value}")
                new_front_matter_lines.append('---\n')
                new_front_matter_str = '\n'.join(new_front_matter_lines)
        else:
            # 如果没有summary字段，直接在front-matter末尾添加
            # 查找最后一个---的位置
            last_end = content.find('---\n', content.find('---') + 3)
            if last_end == -1:
                # 如果没有找到正确的结束标记，就在开头插入
                return f"---\nsummary: {summary}\n---\n{content}"
            else:
                # 在---之前插入summary字段
                before = content[:last_end]
                after = content[last_end:]
                return f"{before}summary: {summary}\n{after}"

        return new_front_matter_str + remaining_content

    @staticmethod
    def process_file(file_path: str, summary_agent: SummaryAgent) -> bool:
        """处理单个markdown文件，生成摘要并添加到front-matter"""
        try:
            content = SummaryAgent.read_file(file_path)

            # 检查是否有front-matter
            front_matter, _, article_content = MarkdownProcessor.parse_front_matter(content)
            if not front_matter:
                print(f"跳过 {file_path} - 没有front-matter")
                return False

            # 检查是否有abbrlink字段或abbrlink为空
            if 'abbrlink' not in front_matter or not front_matter['abbrlink'] or str(front_matter['abbrlink']).strip() == '':
                print(f"跳过 {file_path} - abbrlink字段为空或不存在")
                return False

            # 检查是否已经有summary字段
            if 'summary' in front_matter:
                print(f"跳过 {file_path} - 已存在summary字段")
                return False

            # 限制内容长度以避免token限制
            if len(article_content) > 4000:
                article_content = article_content[:4000] + "..."

            print(f"正在为 {file_path} 生成摘要...")
            summary = summary_agent.query(article_content)
            time.sleep(SLEEP_TIME)

            # 更新文件内容
            new_content = MarkdownProcessor.add_summary_to_front_matter(content, summary)

            with open(file_path, 'w', encoding='utf-8') as f:
                f.write(new_content)

            print(f"✓ 成功为 {file_path} 添加摘要")
            return True

        except Exception as e:
            print(f"✗ 处理文件 {file_path} 时出错: {e}")
            return False


from dotenv import load_dotenv

def main():
    # 加载.env文件
    load_dotenv(override=True)

    api_key = os.getenv("OPENAI_API_KEY")
    base_url = os.getenv("OPENAI_BASE_URL")
    model = os.getenv("OPENAI_MODEL")
    if not api_key or not base_url or not model:
        print("错误：未提供 API 密钥或基础 URL。请检查环境变量。")
        return

    mothra = SummaryAgent(api_key=api_key, base_url=base_url, model=model)
    processor = MarkdownProcessor()

    # 处理整个Notes目录
    md_files = processor.find_markdown_files(MD_FILE_PATHS)
    processed_count = 0

    for file_path in md_files:
        if processor.process_file(file_path, mothra):
            processed_count += 1

    print(f"\n处理完成！共处理了 {processed_count} 个文件")


if __name__ == "__main__":
    main()

5.2. 更便捷：使用obsidian插件生成当前文章summary

在obsidian插件里面搜了一下，有一个ai summary插件，测试了一下，发现它不支持设置base_url和模型，也不支持生成当前文章的摘要。当前插件只支持生成当前文章引用了的文章的摘要，说实话只支持这个功能让这个插件的能力变得太单一了，而且和插件的标题“AI Notes Summary”没啥关系啊！

直接fork一份，clone到本地，爆改一番。

慕雪修改后的插件：https://github.com/musnows/obsidian-ai-summary

修改后的插件，可以通过obsidian的命令行对当前文章进行总结了：

只需要设置相同的system prompt，就可以实现和hexo插件一样的效果了。这样可以在编写了文章后，手动执行一下这个命令，把AI生成的结果自己手动写summary字段里面去。

插件执行效果如下图所示，测试使用的DeepSeek：

由于这个插件是fork的，慕雪没有上obsidian的插件市场，所以需要大家手动安装一下。

直接把插件仓库克隆到本地，执行一下npm install和npm run build，然后把插件文件夹直接整体克隆到你的.obsidian/plugins目录里面去就ok了。重启obsidian，就能在第三方插件里面看到这个本地插件了。

另外，在配置这个插件的时候测试了LongCat，发现LongCat的API请求不允许跨域访问。在obsidian插件中的请求都会有一个origin 'app://obsidian.md'，如果服务端不支持跨域，就没办法正常请求，所以不能用LongCat。报错如下：

index.html:1 Access to fetch at 'https://api.longcat.chat/openai/v1/chat/completions' from origin 'app://obsidian.md' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

本地实测DeepSeek官方提供的API是可以请求的，所以这算是LongCat的OpenAI有能力缺失？在LongCat服务端没有允许跨域访问。

6. The end

不管怎么说，本站也算是成功接入了AI总结的显示能力啦！虽然有点麻烦，但总好过没有。很多问题都是可以解决的。

之前慕雪用python脚本测试过LongCat的OpenAI接口的rpm，约为30，也就是一分钟只能请求30次。 ↩︎
obsidian触发hexo详情可见：https://blog.musnow.top/posts/8608489065?from_abbrlink=5899307553 ↩︎

【Agent.04】AI时代的hello world：调用OpenAI接口，与大模型交互

2025-09-30T07:25:08.000Z

欢迎阅读慕雪撰写的AI Agent专栏，本专栏目录如下

本文介绍了如何使用python发送请求，调用OpenAI的API，与大模型交互，获取到大模型关于hello的响应。

从本文开始，引入python代码编程了，本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。在开始之前，请先在你的电脑上准备好uv环境，仓库中的所有代码都是使用uv进行环境管理的：点我学习uv。

1. 引言

如果说学习编程的第一个程序是hello world，那么学习AI Agent开发的第一个程序就是调用AI API。就像学车要先认识方向盘一样，调用API也是AI开发的必备技能。

本文将介绍如何使用Python的requests库调用硅基流动的OpenAI兼容API。这其实就是一个HTTP请求的事，我们发送请求给OpenAI格式API接口的服务端，服务端将请求处理成大模型能够接受的入参，再把大模型返回的结果，以OpenAI API的格式返回给我们。

本文使用Python的requests库，以硅基流动的API做示例，请求Qwen/Qwen3-8B模型。OpenAI的请求格式可以参考硅基流动的OpenAI API文档。

阅读本文之前，请确保你对HTTP协议、Python的基本语法和requests库的使用有一定了解。本站的Agent专题不包含Python教学部分。

2. 准备工作

2.1. 获取API密钥

首先需要注册硅基流动账号，地址：https://cloud.siliconflow.cn/

如果你愿意支持慕雪，可以使用慕雪的邀请链接注册硅基流动，万分感谢！

登录后，在控制台找到"API Keys"页面，创建新的API密钥。这个密钥就是你在硅基流动这个平台上的身份证，千万保管好，别泄露了。任何平台的API Key都必须保管好！

2.2. 安装依赖库

首先需要保证你的电脑上有Python的基本环境，安装Python参考本站博客：点我。建议至少安装Python 3.10.x版本，不要安装太老的版本。

我们需要使用Python的requests库发送HTTP请求，所以需要安装requests库：

1	pip3 install requests

requests这玩意非常常用，所以直接装在你python全局环境就OJBK了，刚开始学习的时候，没必要去折腾啥虚拟环境。

3. 开始调用！

3.1. 基础调用示例

下面是一个最最最基础的OpenAI请求，包含了一个system prompt和我们咨询的问题。

使用这个代码之前，你需要先替换代码最后的API_KEY为你自己的硅基流动API Key。

import requests
import json

def call_ai_api(api_key, question):
    """
    调用硅基流动的OpenAI兼容API

    Args:
        api_key: API密钥
        question: 用户问题

    Returns:
        API响应结果
    """
    url = "https://api.siliconflow.cn/v1/chat/completions"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    data = {
        "model": "Qwen/Qwen3-8B",
        "messages": [
            {"role": "system", "content": "你是一个有帮助的AI助手，回答要简明扼要。"},
            {"role": "user", "content": question}
        ],
        "stream": False,
        "max_tokens": 512,
        "temperature": 0.7,
        "top_p": 0.7
    }

    response = requests.post(url, headers=headers, json=data)

    if response.status_code == 200:
        return response.json()
    else:
        return {"error": f"请求失败，状态码: {response.status_code}", "message": response.text}

# 使用示例
if __name__ == "__main__":
    API_KEY = "your_api_key_here"  # 替换为实际API密钥
    result = call_ai_api(API_KEY, "Hello World在编程中的意义是什么？")

    if "error" in result:
        print(f"请求出错: {result['error']}")
    else:
        print(f"AI回复: {result['choices'][0]['message']['content']}")

运行结果如下，AI成功回答了我们的问题

❯ uv run basic/01.openai_hello_world.py 
AI回复: 

"Hello World"是编程学习的入门示例，主要用于：  
1. **验证环境**：确认编程语言和开发工具配置正确。  
2. **教学用途**：帮助初学者快速理解基本语法结构（如输出语句）。  
3. **历史传统**：源自1970年代C语言的早期教程，现已成为编程界的通用"Hello World"惯例。  
4. **调试起点**：作为程序运行的简单测试，确保代码执行无误。  

它象征着编程学习的起点，强调“能运行即可”的核心目标。

3.2. 关键参数说明

接下来，对OpenAI API接口中的关键参数进行说明。

3.2.1. Header

首先是header里面的字段，Authorization是一个比较通用的鉴权字段，这里传入了我们的API KEY用来确认我们的用户身份，服务器才能提供响应。后续调用收费的模型，也会自动定位到你的硅基流动账户，进行扣费。

简单来说，Authorization就是一个身份标识，好比进门的钥匙。毕竟你不能不带钥匙就去开门，如果谁来都开门了，这个OpenAI的API接口岂不是能随便请求，那肯定会被干爆的！

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

3.2.2. Body

随后，再来看看OpenAI的body字段里面有哪些内容

data = {
    "model": "Qwen/Qwen3-8B",
    "messages": [
        {"role": "system", "content": "你是一个有帮助的AI助手，回答要简明扼要。"},
        {"role": "user", "content": question}
    ],
    "stream": False,
    "max_tokens": 512,
    "temperature": 0.7
}

这个body里面包含的字段如下：

model：选择使用的AI模型，硅基流动提供多种模型可选
messages：对话历史，包含角色和内容
stream：是否使用流式响应，False表示等待完整响应，True代表使用流失响应；
max_tokens：限制响应的最大token数量，防止AI输出到一半就不干活了，或者输出太多"跑火车"；
temperature：控制回答的随机性，0到1之间的小数，值越高回答越有创意，或者说越高就越偏离你的原定目标。如果想让AI别那么发散，就把这个值稍微调小一点。一般建议默认使用0.7，或者遵循模型官方文档提供的建议。

3.2.3. Messages列表

其中，最重要的参数，是messages列表，这个列表控制了我们的历史记录。我们每次对大模型的请求，都是无状态的，整个对话的输入输出，都是客户端在控制。

举个例子：

你请求了大模型A，咨询了问题1234。
你使用相同的历史记录去请求大模型B，大模型B依旧会有这些历史记录的“记忆”，继续回答你的问题5，同时也会知道前4个问题是啥。

所以，在编写一个多次对话的大模型请求的时候，我们作为客户端的代码需要主动维护这个历史消息的messages列表，保证已有对话的记忆不丢失。

messages列表中的每一个成员都是一个dict，包含两个字段：

role：字符串类型。当前这条消息的身份，可选值为system、user、assistant、tool，分别对应系统消息（system prompt）、用户发送的问题、大模型的回答、以及工具调用的返回值（工具调用结果）。
content：字符串或数组类型，当前这条消息的内容。建议不要使用数组类型，直接用字符串填写内容。

对应Json格式如下：

{
  "role": "system | user | assistant | tool",
  "content": "字符串内容"
}

当出现多轮对话的时候，我们请求体里面的messages列表也要对应更新，这便是我们客户端维护的历史消息。

[
  {"role": "system", "content": "你是一名旅行顾问"},
  {"role": "user", "content": "巴黎有哪些免费景点？"},
  {"role": "assistant", "content": "巴黎免费景点有：塞纳河步行、卢森堡公园、蒙马特高地……"},
  {"role": "user", "content": "那吃的呢？什么是最好吃的？"},
  {"role": "assistant", "content": "法式牛排非常吃！"},
]

role中比较特殊的是tool这个类型，代表的是工具调用的返回结果。这部分在后续function calling实操部分再展开讲讲，现在你只要知道role有这个类型就行了。

3.3. 进阶：流式响应

如果需要实时查看AI的输出过程（类似ChatGPT网页端上的样子），可以使用流式响应：

import requests
import json

def stream_response(api_key, question):
    url = "https://api.siliconflow.cn/v1/chat/completions"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    data = {
        "model": "Qwen/Qwen3-8B",
        "messages": [
            {"role": "user", "content": question}
        ],
        "stream": True,
        "max_tokens": 512
    }

    response = requests.post(url, headers=headers, json=data, stream=True)
    # 这里返回200，并不是请求全都发回来了，而是连上服务器了！
    if response.status_code == 200:
        # 开始遍历返回的结果，判断是不是有数据
        for line in response.iter_lines():
            if line:
                line_str = line.decode('utf-8')
                if line_str.startswith('data:'):
                    if line_str == 'data: [DONE]':
                        break
                    json_str = line_str[5:]
                    chunk = json.loads(json_str)
                    # 真的有数据诶，打印一下！
                    if chunk['choices'][0]['delta'].get('content'):
                        print(chunk['choices'][0]['delta']['content'], end='', flush=True)
    else:
        print(f"请求失败，状态码: {response.status_code}")

# 使用示例
if __name__ == "__main__":
    API_KEY = "your_api_key_here"
    stream_response(API_KEY, "请写一首关于冬天的诗")

流式传输的执行效果如下

不过，一般也只有开发前后端AI项目的时候需要用到流式相应。如果是开发一个自动化的Agent，没必要使用流式响应，对性能和效果都没有啥提升，反而会把代码变得复杂。

当然，实际编写Agent的时候，我们都会用主流的Agent SDK，不会自己造轮子。这些底层的OpenAI接口调用是怎么处理的，就不是我们需要考虑的内容了。但，学习OpenAI接口的基本结构还是非常重要的，对后续Debug和加深学习都是必要的。

4. 总结

调用OpenAI API是AI开发的入门技能，就像学习编程的hello world。掌握了这个基础，后续可以：

尝试不同模型，比较效果差异
将AI集成到实际项目中
探索更多AI应用场景

最后提醒：AI只是工具，关键是怎么用。与其追求最新最强的模型，不如先掌握好基本用法。

另外，本文介绍的OpenAI API请求只是最基础的一个“hello world”，Agent开发中并不会使用requests直接调用API这么原始的方式调用OpenAI的接口，而是会使用OpenAI官方提供的python sdk和包装好的Agent框架，这样能避免造轮子的尴尬。这些都是后续专栏中会逐步介绍的内容了。