欢迎来到我的博客！这里是我分享知识、经验和见解的地方。希望通过这个平台与志同道合的朋友们交流，互相学习，共同成长。让我们一起探索技术与财务的世界，分享彼此的故事和见解！

我的公众号​

为了能够获取第一手资讯，我也会在我的公众号上发布相关的内容，欢迎关注

我们看一下最终的样子，安装指南来了！

读完本篇文章，你可以学会：在自己的电脑上安装一个自己的龙虾，并用飞书来直接跟他聊天，完全不需要任何编程基础，纯小白也能轻松上手！

准备工作​

首先，你需要一台可以连接互联网的电脑

Windows、MacOS、Linux 都可以

有不少已经上网搜索过龙虾的小伙伴会问：Windows、MacOS、Linux 哪个系统更适合安装龙虾？ 我是否应该买一台Mac Mini？

在阿赞的角度来看：MacOS 肯定是独一档的好

因为有着更好的稳定性，更强的性能，更低的功耗，让Mac Mini成为最适合龙虾的机器

但是其他系统也完全可以使用，如果不是重度依赖龙虾工作，你完全没有必要额外去买一台Mac Mini，在现有的电脑上安装使用足矣。

其次，你需要一个大模型的API接口

你可以买任何你觉得好用的大模型API接口，OpenAI、Anthropic、国内的模型厂商都可以

如果你没有预算，完全可以使用免费的模型接口，或者你有比较不错的显卡，那么你完全可以选择在本地部署一个开源模型，来当做龙虾的后端引擎。

开始安装​

我相信绝大多数小伙伴都有windows电脑，所以我们以Windows系统为例，来介绍一下安装的步骤。

MacOS 和 Linux 的安装步骤基本上是一样的，唯一的区别就是第一步安装 Docker 的方式不太一样，后续的步骤完全一样。

第一步，安装docker​

你可以在下面这个地址找到docker的安装教程，这里我不再赘述

https://www.runoob.com/docker/windows-docker-install.html

安装并启动完成之后，可以看到docker的界面了

打开一个命令行窗口，输入 docker version 来验证一下是否安装成功

看到如上界面后，就表示docker安装成功了，我们就可以进入下一步了。

第二步，下载龙虾docker镜像​

这里我们使用了一个已经集成好了国内各种聊天软件的龙虾

Github仓库地址如下，感兴趣的小伙伴可以阅读一下，不感兴趣的直接按照我们下面的步骤来操作 https://github.com/justlovemaki/OpenClaw-Docker-CN-IM

打开一个命令行窗口，输入下面的命令来下载这个龙虾的docker镜像

docker pull justlovemaki/openclaw-docker-cn-im:latest

如果你没有科学上网的条件，那么大概率上面这个镜像下不下来，没关系我这里也准备了一个国内网络友好的镜像地址

docker pull registry.cn-hangzhou.aliyuncs.com/dongfangzan/openclaw-docker-cn-im:20260309

你也可以在后台私信我回复：龙虾，我已经把这个镜像准备好了

文件下载下来之后，在下载目录，执行下面的命令即可完成导入

docker load -i openclaw.tar

下载完成后，你可以输入下面的命令看到这个镜像

docker images

第三步，启动龙虾​

在你觉得合适的地方，创建一个目录来存放龙虾的数据，比如 E:\openclaw-data

这里可以看到，当前目录是空的，我们现在需要创建一个文本文档，命名为 .env

所有的配置文件，你可以关注我的公众号，并在后台回复：龙虾，我已经把所有涉及到的文件都准备好了

把下面的内容，保存进.env文件中，然后我们开始替换掉里面的内容

创建配置文件​

# OpenClaw Docker 环境变量配置示例
# 复制此文件为 .env 并修改相应的值

# Docker 镜像配置
OPENCLAW_IMAGE=justlikemaki/openclaw-docker-cn-im:latest

# 模型配置
# 是否自动同步模型配置到 openclaw.json (true/false)
# 如果你手动修改了 openclaw.json 中的模型设置，请将其设为 false
SYNC_MODEL_CONFIG=true

# 提供商 1 (默认)
# 主模型 ID (支持多个，用逗号隔开，第一个将作为默认模型)
MODEL_ID=model id
# 图片模型 ID (可选，留空则使用 MODEL_ID，支持 provider/model 格式)
IMAGE_MODEL_ID=
BASE_URL=http://xxxxx/v1
API_KEY=123456
# API 协议类型: openai-completions 或 anthropic-messages
API_PROTOCOL=openai-completions
# 模型上下文窗口大小
CONTEXT_WINDOW=200000
# 模型最大输出 tokens
MAX_TOKENS=8192

# 提供商 2 (可选)
# MODEL2_NAME=model2
# MODEL2_MODEL_ID=model id1,model id2
# MODEL2_BASE_URL=http://xxxxx/v1
# MODEL2_API_KEY=123456
# MODEL2_PROTOCOL=openai-completions
# MODEL2_CONTEXT_WINDOW=200000
# MODEL2_MAX_TOKENS=8192

# Telegram 配置（可选，留空则不启用）
TELEGRAM_BOT_TOKEN=

# 飞书配置（可选，留空则不启用）
FEISHU_APP_ID=
FEISHU_APP_SECRET=
# 是否启用飞书官方插件 (true/false)
FEISHU_OFFICIAL_PLUGIN_ENABLED=false

# 钉钉配置（可选，留空则不启用）
DINGTALK_CLIENT_ID=
DINGTALK_CLIENT_SECRET=
DINGTALK_ROBOT_CODE=
DINGTALK_CORP_ID=
DINGTALK_AGENT_ID=

# QQ 机器人配置（可选，留空则不启用）
QQBOT_APP_ID=
QQBOT_CLIENT_SECRET=
# NapCat (OneBot v11) 配置（可选，留空则不启用）
# NapCat 反向 WS 监听端口（NapCat 主动连接到此端口）
NAPCAT_REVERSE_WS_PORT=
# NapCat HTTP API 地址（可选，用于主动发送消息）
NAPCAT_HTTP_URL=
# 连接鉴权 Token（与 NapCat 侧保持一致）
NAPCAT_ACCESS_TOKEN=
# 管理员用户 ID，多个用逗号分隔
NAPCAT_ADMINS=

# 企业微信配置（可选，留空则不启用）
# 方式1：单账号（兼容旧格式），会自动同步为 channels.wecom.default
WECOM_TOKEN=
WECOM_ENCODING_AES_KEY=
# 方式2：多账号（Multi-Bot）JSON，支持 bot1/bot2... 独立配置（会与现有配置深度合并）
# 注意：.env 中 JSON 需要写成单行
# 示例：{"bot1":{"token":"t1","encodingAesKey":"k1","agent":{"corpId":"wwxxx","corpSecret":"s1","agentId":1000001}},"bot2":{"token":"t2","encodingAesKey":"k2","agent":{"corpId":"wwxxx","corpSecret":"s2","agentId":1000002}}}
WECOM_BOTS_JSON=

# 工作空间配置（不要更改）
WORKSPACE=/home/node/.openclaw/workspace

# 挂载目录配置（按实际更改）
# OpenClaw 数据目录（包含配置文件、工作空间等所有数据）
OPENCLAW_DATA_DIR=~/.openclaw

# 可选：容器启动用户 UID:GID
# 默认 0:0（root）用于 init.sh 自动修复挂载目录权限，再降权为 node 启动服务
# 如需与宿主机用户对齐，可设置为 1000:1000 或 Linux 上的 $(id -u):$(id -g)
OPENCLAW_RUN_USER=0:0

# Gateway 配置
## 网关 token，用于认证（按实际更改）
OPENCLAW_GATEWAY_TOKEN=123456
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_MODE=local
# 允许的 Origin 域，多个用逗号隔开
OPENCLAW_GATEWAY_ALLOWED_ORIGINS=http://localhost
# 允许不安全认证（如 http），可选 true/false
OPENCLAW_GATEWAY_ALLOW_INSECURE_AUTH=true
# 危险：禁用设备认证（如在 Docker 环境中无法获取设备信息），可选 true/false
OPENCLAW_GATEWAY_DANGEROUSLY_DISABLE_DEVICE_AUTH=false
# 插件全局控制
OPENCLAW_PLUGINS_ENABLED=true
# 飞书官方插件独立开关（对应 plugins.entries.feishu-openclaw-plugin.enabled）
# 与旧版 feishu 渠道互斥：
# true  = 启用 feishu-openclaw-plugin，并自动禁用旧版 feishu
# false = 禁用 feishu-openclaw-plugin，并自动启用旧版 feishu
# 留空表示不覆盖现有配置；若检测到官方插件已有状态，也会自动与旧版 feishu 做互斥处理
FEISHU_OFFICIAL_PLUGIN_ENABLED=

首先需要注意的是，如果在第二步 中下载的镜像是registry.cn-hangzhou.aliyuncs.com/dongfangzan/openclaw-docker-cn-im:20260309

那么你需要把上面.env文件中的 OPENCLAW_IMAGE 的值，替换成 registry.cn-hangzhou.aliyuncs.com/dongfangzan/openclaw-docker-cn-im:20260309

接下来我们需要替换掉模型相关的配置

注意下面这一块内容，你需要把MODEL_ID、BASE_URL、API_KEY 和 API_PROTOCOL 替换成你自己的大模型接口的相关信息

# 提供商 1 (默认)
# 主模型 ID (支持多个，用逗号隔开，第一个将作为默认模型)
MODEL_ID=model id
# 图片模型 ID (可选，留空则使用 MODEL_ID，支持 provider/model 格式)
IMAGE_MODEL_ID=
BASE_URL=http://xxxxx/v1
API_KEY=123456
# API 协议类型: openai-completions 或 anthropic-messages
API_PROTOCOL=openai-completions
# 模型上下文窗口大小
CONTEXT_WINDOW=200000
# 模型最大输出 tokens
MAX_TOKENS=8192

在这个步骤中，我们就需要用到大模型的接口了，如果你还没有的话，可以去购买一个，或者使用本地部署的。

我们需要找到你的API Key 和 API Base URL

这个在为你提供大模型接口的厂商那里都可以找到，通常在控制台的API管理或者密钥管理那里

比如你在阿里云购买了一个Coding Plan的大模型接口，那么就可以按如下进行填写

# 提供商 1 (默认)
# 主模型 ID (支持多个，用逗号隔开，第一个将作为默认模型)
MODEL_ID=qwen3.5-plus
# 图片模型 ID (可选，留空则使用 MODEL_ID，支持 provider/model 格式)
IMAGE_MODEL_ID=
BASE_URL=https://coding.dashscope.aliyuncs.com/v1
API_KEY=sk-xxxxxx
# API 协议类型: openai-completions 或 anthropic-messages
API_PROTOCOL=openai-completions
# 模型上下文窗口大小
CONTEXT_WINDOW=200000
# 模型最大输出 tokens
MAX_TOKENS=8192

然后注意在第78行，现在是OPENCLAW_DATA_DIR=~/.openclaw

需要替换为你在第三步一开始创建的目录 OPENCLAW_DATA_DIR=E:\\openclaw-data\\.openclaw

windows 路径需要使用双斜杠 \\ 来转义，如果是MacOS 或 Linux 则直接使用单斜杠 / 即可

替换完成后，保存这个.env文件

可以看到当前目录下目前只有这个.env文件

创建启动文件​

接着，再打开一个新的文本文件，命名为 docker-compose.yml

把下面的所有内容，复制粘贴到 docker-compose.yml 文件中进行保存

version: '3.8'

x-openclaw-common-env: &openclaw-common-env
  TZ: Asia/Shanghai
  HOME: /home/node
  TERM: xterm-256color
  # 模型配置
  SYNC_MODEL_CONFIG: ${SYNC_MODEL_CONFIG}
  MODEL_ID: ${MODEL_ID}
  IMAGE_MODEL_ID: ${IMAGE_MODEL_ID}
  BASE_URL: ${BASE_URL}
  API_KEY: ${API_KEY}
  API_PROTOCOL: ${API_PROTOCOL}
  CONTEXT_WINDOW: ${CONTEXT_WINDOW}
  MAX_TOKENS: ${MAX_TOKENS}
  # 提供商 2 (可选)
  MODEL2_NAME: ${MODEL2_NAME}
  MODEL2_MODEL_ID: ${MODEL2_MODEL_ID}
  MODEL2_BASE_URL: ${MODEL2_BASE_URL}
  MODEL2_API_KEY: ${MODEL2_API_KEY}
  MODEL2_PROTOCOL: ${MODEL2_PROTOCOL}
  MODEL2_CONTEXT_WINDOW: ${MODEL2_CONTEXT_WINDOW}
  MODEL2_MAX_TOKENS: ${MODEL2_MAX_TOKENS}
  # 通道配置
  TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
  FEISHU_APP_ID: ${FEISHU_APP_ID}
  FEISHU_APP_SECRET: ${FEISHU_APP_SECRET}
  DINGTALK_CLIENT_ID: ${DINGTALK_CLIENT_ID}
  DINGTALK_CLIENT_SECRET: ${DINGTALK_CLIENT_SECRET}
  DINGTALK_ROBOT_CODE: ${DINGTALK_ROBOT_CODE}
  DINGTALK_CORP_ID: ${DINGTALK_CORP_ID}
  DINGTALK_AGENT_ID: ${DINGTALK_AGENT_ID}
  QQBOT_APP_ID: ${QQBOT_APP_ID}
  QQBOT_CLIENT_SECRET: ${QQBOT_CLIENT_SECRET}
  NAPCAT_REVERSE_WS_PORT: ${NAPCAT_REVERSE_WS_PORT}
  NAPCAT_HTTP_URL: ${NAPCAT_HTTP_URL}
  NAPCAT_ACCESS_TOKEN: ${NAPCAT_ACCESS_TOKEN}
  NAPCAT_ADMINS: ${NAPCAT_ADMINS}
  # 企业微信配置
  WECOM_TOKEN: ${WECOM_TOKEN}
  WECOM_ENCODING_AES_KEY: ${WECOM_ENCODING_AES_KEY}
  # 企业微信多账号配置（JSON 字符串，示例见 .env.example）
  WECOM_BOTS_JSON: ${WECOM_BOTS_JSON}
  # 工作空间配置
  WORKSPACE: ${WORKSPACE}
  # Gateway 配置
  OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
  OPENCLAW_GATEWAY_BIND: ${OPENCLAW_GATEWAY_BIND}
  OPENCLAW_GATEWAY_PORT: ${OPENCLAW_GATEWAY_PORT}
  OPENCLAW_BRIDGE_PORT: ${OPENCLAW_BRIDGE_PORT}
  OPENCLAW_GATEWAY_MODE: ${OPENCLAW_GATEWAY_MODE}
  OPENCLAW_GATEWAY_ALLOWED_ORIGINS: ${OPENCLAW_GATEWAY_ALLOWED_ORIGINS}
  OPENCLAW_GATEWAY_ALLOW_INSECURE_AUTH: ${OPENCLAW_GATEWAY_ALLOW_INSECURE_AUTH}
  OPENCLAW_GATEWAY_DANGEROUSLY_DISABLE_DEVICE_AUTH: ${OPENCLAW_GATEWAY_DANGEROUSLY_DISABLE_DEVICE_AUTH}
  OPENCLAW_GATEWAY_AUTH_MODE: ${OPENCLAW_GATEWAY_AUTH_MODE}
  # 插件控制
  OPENCLAW_PLUGINS_ENABLED: ${OPENCLAW_PLUGINS_ENABLED}
  FEISHU_OFFICIAL_PLUGIN_ENABLED: ${FEISHU_OFFICIAL_PLUGIN_ENABLED}

services:
  openclaw-gateway:
    container_name: openclaw-gateway
    image: ${OPENCLAW_IMAGE}
    cap_add:
      - CHOWN
      - SETUID
      - SETGID
      - DAC_OVERRIDE
    # 可选：指定容器运行 UID:GID（例如 1000:1000）
    # 默认保持 root 启动，以便 init.sh 自动修复挂载卷权限后再降权运行网关
    user: ${OPENCLAW_RUN_USER:-0:0}
    environment: *openclaw-common-env
    volumes:
      - ${OPENCLAW_DATA_DIR}:/home/node/.openclaw
      # 使用命名卷共享 extensions，确保工具容器安装后的插件主容器可见
      - openclaw-extensions:/home/node/.openclaw/extensions
    ports:
      - "${OPENCLAW_GATEWAY_PORT}:18789"
      - "${OPENCLAW_BRIDGE_PORT}:18790"
    init: true
    restart: unless-stopped

  openclaw-installer:
    container_name: openclaw-installer
    image: ${OPENCLAW_IMAGE}
    profiles:
      - tools
    user: ${OPENCLAW_RUN_USER:-0:0}
    environment: *openclaw-common-env
    volumes:
      - ${OPENCLAW_DATA_DIR}:/home/node/.openclaw
      - openclaw-extensions:/home/node/.openclaw/extensions
    entrypoint: ["tail", "-f", "/dev/null"]
    init: true
    restart: 'no'
    ports: []
    stdin_open: true
    tty: true
    cap_add:
      - CHOWN
      - SETUID
      - SETGID
      - DAC_OVERRIDE

volumes:
  openclaw-extensions:

这时，该目录下，就有两个文件了

接下来，我们需要在这个目录下打开一个命令行工具

执行下面的命令

docker-compose up -d

看到最下方有一个绿色的Created，就表示龙虾已经成功启动了

然后我们输入下面的命令

docker logs openclaw-gateway

当看到有listening on ws://0.0.0.0:18789的日志输出时，就表示龙虾已经成功启动了

接下来我们输入下面的命令，来进入到龙虾的安装容器中

docker exec -it openclaw-gateway bash

随后输入下面的命令，就进入了与我们的龙虾进行交互时对话的窗口了

openclaw tui

如果我们配置的大模型接口没有问题，且网络通畅，那么我们此时与龙虾对话窗口就会有模型的回复了

至此，我们的龙虾就已经跑起来了

但截止到目前为止，我们还是在命令行窗口中与龙虾进行对话的，这样的体验还是比较糟糕的

我们希望可以在聊天工具中直接跟龙虾进行对话，来享受更好的使用体验

第四步，对接飞书​

首先说明一点，为什么选择飞书？​

截止到发文时，其他国内的聊天软件，都需要用户有一个外网IP或者外网域名

再或者需要用户进行复杂的内网穿透，既麻烦又不安全，在外网上暴露龙虾，可能会导致你的数据泄露或者被攻击。

所以目前国内使用体验最好的，可能就是飞书了，因为他不需要你有外网IP或者外网域名，也不需要你进行内网穿透

直接在飞书添加一个机器人，就可以直接跟你的龙虾进行对话了

注册飞书​

首先，你需要去飞书的官网https://www.feishu.cn/

注册一个账号并下载安装，注册飞书的方法非常简单，直接使用手机号或者邮箱注册就可以了，按照提示操作即可

创建飞书机器人​

访问地址，进入飞书开放平台，https://open.feishu.cn/

点击右上角开发者后台

点击创建企业自建应用

根据你的喜好，来给你的龙虾命名

创建完成后，点击左侧凭证与基础信息，来获取你的App ID和App Secret

记住这个App ID和App Secret，然后我们回到刚才的控制台黑框中

通过命令来进入到龙虾的安装容器中

docker exec -it openclaw-gateway bash

如果你刚刚没有退出龙虾的对话窗口，那么直接按键盘上的Ctrl+D来回到容器中

这时，输入下面的命令

feishu-plugin-onboard install

然后按照下面的命令输入 y->回车

接下来，回到你的.env文件中，把你刚才获取的App ID和App Secret，分别替换掉 FEISHU_APP_ID 和 FEISHU_APP_SECRET 的值

并将.env文件最最后一行的飞书官方插件开关 FEISHU_OFFICIAL_PLUGIN_ENABLED 的值，替换为 true

保存文件后，回到命令行窗口，输入下面的命令，来重启龙虾

# 关闭龙虾
docker-compose down

# 启动龙虾
docker-compose up -d

# 查看日志
docker-compose logs openclaw-gateway

最终看到下面的文字，表明龙虾与飞书对接成功了

配置飞书权限​

接下来，我们需要回到飞书的开发者后台，来给我们的机器人添加权限

选择权限管理，点击批量导入/导出权限

这里我整理好了一个常用的权限列表，你可以直接复制下面的内容，粘贴到飞书的权限批量导入框中，来快速添加权限

{
  "scopes": {
    "tenant": [
      "bitable:app",
      "bitable:app:readonly",
      "calendar:calendar",
      "calendar:calendar.acl:create",
      "calendar:calendar.acl:delete",
      "calendar:calendar.acl:read",
      "calendar:calendar.event:create",
      "calendar:calendar.event:delete",
      "calendar:calendar.event:read",
      "calendar:calendar.event:reply",
      "calendar:calendar.event:update",
      "calendar:calendar.free_busy:read",
      "calendar:calendar:create",
      "calendar:calendar:delete",
      "calendar:calendar:read",
      "calendar:calendar:readonly",
      "calendar:calendar:subscribe",
      "calendar:calendar:update",
      "calendar:exchange.bindings:create",
      "calendar:exchange.bindings:delete",
      "calendar:exchange.bindings:read",
      "calendar:settings.caldav:create",
      "calendar:settings.workhour:read",
      "calendar:time_off:create",
      "calendar:time_off:delete",
      "calendar:timeoff",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "docx:document",
      "docx:document.block:convert",
      "docx:document:create",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:readonly",
      "drive:drive:version",
      "drive:drive:version:readonly",
      "drive:export:readonly",
      "drive:file",
      "drive:file.like:readonly",
      "drive:file.meta.sec_label.read_only",
      "drive:file:download",
      "drive:file:readonly",
      "drive:file:upload",
      "drive:file:view_record:readonly",
      "im:app_feed_card:write",
      "im:biz_entity_tag_relation:read",
      "im:biz_entity_tag_relation:write",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.announcement:read",
      "im:chat.announcement:write_only",
      "im:chat.chat_pins:read",
      "im:chat.chat_pins:write_only",
      "im:chat.collab_plugins:read",
      "im:chat.collab_plugins:write_only",
      "im:chat.managers:write_only",
      "im:chat.members:bot_access",
      "im:chat.members:read",
      "im:chat.members:write_only",
      "im:chat.menu_tree:read",
      "im:chat.menu_tree:write_only",
      "im:chat.moderation:read",
      "im:chat.tabs:read",
      "im:chat.tabs:write_only",
      "im:chat.top_notice:write_only",
      "im:chat.widgets:read",
      "im:chat.widgets:write_only",
      "im:chat:create",
      "im:chat:delete",
      "im:chat:moderation:write_only",
      "im:chat:operate_as_owner",
      "im:chat:read",
      "im:chat:readonly",
      "im:chat:update",
      "im:datasync.feed_card.time_sensitive:write",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message.urgent",
      "im:message.urgent.status:write",
      "im:message.urgent:phone",
      "im:message.urgent:sms",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_depts",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "im:tag:read",
      "im:tag:write",
      "im:url_preview.update",
      "im:user_agent:read",
      "wiki:member:create",
      "wiki:member:retrieve",
      "wiki:member:update",
      "wiki:node:copy",
      "wiki:node:create",
      "wiki:node:move",
      "wiki:node:read",
      "wiki:node:retrieve",
      "wiki:node:update",
      "wiki:setting:read",
      "wiki:setting:write_only",
      "wiki:space:read",
      "wiki:space:retrieve",
      "wiki:space:write_only",
      "wiki:wiki",
      "wiki:wiki:readonly"
    ],
    "user": [
      "contact:contact.base:readonly"
    ]
  }
}

配置飞书接收消息​

接下来，点击左侧事件与回调->订阅方式

选择使用长连接接收事件，点击保存，如果你保存成功了，说明上述的配置就都生效了

如果你看到下面的界面，表明前面龙虾与飞书的连接没有配置成功，回到前面的步骤，检查一下是否正确配置了App ID和App Secret，以及是否重启了龙虾

接下来，右侧的添加事件按钮

添加接收消息事件

在这里面，我们就配置了当飞书接收到消息的时候，发送一个事件到我们的龙虾，来触发龙虾的回复

到此，我们就完成了飞书时间的配置

接下来，点击上方的创建版本，来发布这个机器人

填写版本号和版本描述，点击保存->确认发布即可

到这里我们就完成了所有飞书的配置工作

第五步，在飞书与小龙虾对话​

经过上述发布后，飞书工作台里面，就可以看到这个机器人了

点击这个机器人，进入对话界面，发送一条消息试试

你就可以看到，龙虾已经成功回复了你的消息了，我们的小龙虾就正式上线啦！

完结撒花，快来试试你的龙虾吧！如果你在安装的过程中遇到了任何问题，欢迎在评论区留言，我会第一时间回复大家的！

Anthropic 系列模型主要以云端服务形式提供，受限于网络和昂贵的价格，很多开发者希望能在本地部署类似能力的大模型

国内最近开源的 Kimi-K2.5 / GLM-4.7 / MiniMax-M2.1 等模型，具备强大的编程能力，可以说在一定程度上替代 Anthropic 系列模型

可以在享受不限速的本地推理体验的同时摆脱网络和费用的束缚，并保证数据的隐私安全

但是目前本地部署的开源方案中，大多数模型部署后都只支持 OpenAI 兼容格式的接口

无法直接兼容 Anthropic 的调用格式，这就给想要无缝切换到本地模型的开发者带来了不便

本篇文章，我们将分享如何利用本地部署大模型，助你轻松实现不限量的 Vibe Coding 体验！

接口之争​

在介绍如何接入之前，我们可以先了解一下目前主流的 AI 接口格式，具体都有哪些区别

对这部分内容已经了解的朋友可以直接跳过到后面如何使用转换器的章节。

目前主流的 AI 接口主要有三种

1. OpenAI /chat/completions 接口​

这个接口相信大家都比较熟悉，在 2022 年末，ChatGPT 发布时，OpenAI 推出了这个接口，迅速成为行业标准

几乎所有的模型厂商都兼容这个接口，这也是我们最常用的接口。

这个接口顾名思义，本质是为了对话文本生成快速做出来的接口，且非常简单易用

它的核心假设是：

• 一次请求 = 一次文本回复
• 你自己管理上下文
• 工具调用是后来硬塞进去的（function calling）

这在 2023 年是非常合理的设计，因为当时大多数模型都只是对话工具

2. OpenAI /responses 接口​

到了 2025 年，随着大模型能力的发展，Agent 智能体、多模态、工具调用已经越来越重要

原来的/chat/completions历史包袱太重，已经无法很好地支持这些新兴的复杂交互场景

OpenAI 在 2025 年 3 月份发布了一个新的接口 /responses，这个接口本质上是为了更好地支持复杂交互设计的

在这个全新的接口中，增加了原生的 Agent 能力:

1. 内置 tool use：file_search、code_interpreter、image_generation、web_search、MCP 等
2. 一次 responses 调用里可以发生多次模型-工具-模型循环

增加了 原生的状态(stateful) 支持，保持会话状态，让每次推理不再失忆

与此同时，多模态也不再是给 chat 接口加个字段，而是：

1. text / image / audio / file 都是一等公民
2. 输出也是多 item（text + tool_call + structured output）

这对真正做产品级应用很重要，OpenAI 也在积极的推动这个接口的生态建设

比如现在的 OpenAI 推出的编程工具 Codex 就是基于这个接口设计的

3. Anthropic /messages 接口​

Anthropic 的 /messages 接口，在原理上其实与 OpenAI 的 /chat/completions 接口更为接近

他们在文本对话的基础上，增加了多模态、工具调用的能力，并没有额外基于 Agent 去设计一套全新的接口

但有趣的是，Anthropic 是一家工程能力非常强的公司，他们在过去一年中，专注于 Agent 的落地

在 AI 编程这个领域，打造了一个非常强大的编程 Agent 工具 Claude Code

使得基于这一套 /messages 接口，利用工具调用、MCP、Agent Skills 等能力，能够实现非常高效的交互能力

随着 Claude Code 越来越流行，越来越多的开发者希望能够直接调用兼容 Anthropic 的 /messages 接口，来利用 Claude Code 的强大能力

很多国内厂家也开始支持 Anthropic 的接口规范

虽然 OpenAI 的 /responses 接口在设计上看起来更超前，更优秀

但 Anthropic 的 /messages 接口，凭借其强大的生态和落地能力，似乎已经成了 Agent 开发的事实标准

本地部署大模型接入 Claude Code 全攻略​

现在，回到我们的主题，如何将本地部署的大模型，接入到 Claude Code 体系中？

当前我们本地部署大模型，通常会采用以下三种推理引擎来运行大模型

1. Ollama
2. vLLM
3. SGLang

绝大多数非自研模型的 AI 接口提供商，大体上也是基于以上的推理引擎进行修改而来的

1. Ollama​

Ollama 作为目前桌面端使用最多的推理引擎，一开始就已经支持了 OpenAI 的 /chat/completions 接口

2026 年初，Ollama 也发布了对 Anthropic /messages 接口的支持

所以，如果你使用 Ollama 来部署模型，那么直接调用本地的 Ollama 服务即可

你需要升级到 Ollama 最新版本，才能支持 Anthropic 接口，至少>=v0.15.0

2. vLLM​

vLLM 作为目前最流行的云端推理引擎，支持了最多类型的 API

上述我们提到的三种主流接口，vLLM 都已经支持

如果你使用 vLLM 来部署模型，在启动模型成功时，看到 vLLM 支持的 API

3. SGLang​

SGLang 作为目前另外一款跟 vLLM 齐名的推理引擎，目前只支持 OpenAI 的 /chat/completions 接口

在当前的版本中，还没有对 Anthropic 的 /messages 接口提供支持

但在今年的 Roadmap 中，SGLang 团队已经明确表示会支持 Anthropic 接口

只是具体的发布时间还未确定，所以如果你使用 SGLang 来部署模型，目前还无法直接支持 Anthropic 接口调用

简单总结​

我们总结一下，如果你使用 Ollama 或 vLLM 来部署模型

那么恭喜你，你可以直接调用本地的 Anthropic 接口来实现接入 Claude Code

如果你使用SGLang来部署模型，那就比较惨了，目前就只有干瞪眼了

那么有的同学可能会问了

我不知道我们公司是用啥部署的，只有一个/chat/completions接口

或者你像我一样，希望可以享受 SGLang 的高性能，那该怎么办呢？

Claude Code Router​

github 地址： https://github.com/musistudio/claude-code-router

顾名思义，这是一款可以将各种类型的 AI 接口，转换成 Anthropic /messages 接口的转换器

同时可以对你所有的模型进行路由

目前 github 上已经积累了 25k+ stars，受到了社区的广泛关注

你可以进入他的 github 仓库，查看详细的使用说明，只需要几步配置就可以完成部署

local-openai2anthropic​

Claude Code Router 是一款非常好用的软件，在很多场景下面都能派上用场

但是在当前的开源的推理引擎中，即使是兼容OpenAI接口的 Ollama 、 vLLM 和 SGLang 也并不完美

每家实现的兼容OpenAI接口的方式各不相同，这就导致了即使是对 AI 非常熟悉的工程师，也无法完美适配每一家不同的接口

所以针对我们本地部署大模型接入 Claude Code 的场景，我自己写了一个非常轻量级的转换器 local-openai2anthropic

https://github.com/dongfangzan/local-openai2anthropic

这个转换器的设计目标非常简单，只考虑本地部署大模型接入 Claude Code 等编程工具的场景

主要功能：

• 本地部署的 OpenAI 兼容接口（如 SGLang / Ollama / vLLM） 转换成 Anthropic 兼容接口
• 完美适配了不同开源模型的思考、非思考模式的切换
• 通过外接搜索工具，解决本地模型无法进行 WebSearch 的问题
• 支持图像输入(Kimi-K2.5/Qwen3-VL/GLM-4.6V)，实现多模态能力
• 完美支持 token 用量估算，避免上下文超限导致的窗口溢出

使用方法​

你可以直接通过 pip 安装这个包

pip install local-openai2anthropic

然后通过命令行启动这个转换器

oa2a start

启动后，通过引导输入你的本地 OpenAI 兼容接口地址和 API Key 即可

随后，只需要将你Claude Code 的 ANTHROPIC_BASE_URL 地址，指向这个转换器的地址即可

vi ~/.claude_code/settings.json

联网搜索支持​

如果你需要通过搜索引擎来支持 WebSearch 功能

可以通过配置 tavily_api_key 来实现

vi ~/.oa2a/config.toml

免费版的 Tavily Search，每个月有 1000 次调用额度，基本上可以满足日常使用需求

你可以到他的官网去免费注册一个账号，来获取 API Key

官网地址：https://tavily.com

结束​

感谢你看到这里，随着 AI 编程时代的全面到来，本地化部署已经成为追求极致性能与数据隐私开发者的必经之路

目前国产开源模型（如 Kimi-K2.5、GLM-4.7、MiniMax-M2.1）在能力上已经非常能打，无论你用哪种方式来实现 Vibe Coding，我们的目标都是一致的：

打破格式壁垒，释放本地算力的无限潜力。 🚀

希望这篇教程能帮助你搭建起专属的本地 AI 编程环境，享受不限速、不泄密、不掉线的 Vibe Coding 体验！

如果你在部署过程中遇到任何坑，或者有更好的玩法的，欢迎在评论区交流，或者直接去 GitHub 提 Issue！👋

特别是在 Agent 智能体、编程开发 和 视觉理解 领域，其表现堪称惊艳。

本篇文章，我们就最近这几天在本地部署 Kimi K2.5 模型的踩坑实践做一个全方位分享，助你一次跑通！💪

📦 一、 模型下载​

你可以在 魔搭社区 或者 Hugging Face 找到这个模型。

👉 国内推荐：魔搭社区，下载速度会更快一些 🔗 链接：https://modelscope.cn/models/moonshotai/Kimi-K2.5

📊 模型参数概览​

在模型卡片中我们可以看到：

• 总参数量：1T (MoE 架构)
• 激活参数：32B
• 量化版本：原生 INT4
• 实际大小：约 595.21GB (虽然听起来恐怖，但因为是 INT4，实际体量在可控范围内)

⚙️ 二、 硬件环境准备​

从模型大小就能看出，这位“巨兽”对硬件的要求不低。😨

💻 最低配置门槛​

8 * 96GB H20 是能摸到这个模型的底线，且需要裁剪上下文长度。

✨ 推荐配置方案​

为了拥有丝滑的使用体验，我们推荐以下几种配置：

💡 小贴士：比如 H100 这种算力够但显存吃紧的卡，完全可以通过多机部署来解决。

🛠️ 三、 部署步骤​

0️⃣ 前置准备​

首先在你的服务器上安装好 Nvidia 驱动 和 CUDA 环境（此处省略一万字...）。

📥 下载模型到本地​

# 1. 安装 modelscope
pip install modelscope

# 2. 下载模型到指定目录
modelscope download moonshotai/Kimi-K2.5 --local-dir ./dir

⏳ 经过漫长的等待... 下载完成后，整个 Kimi K2.5 模型大约 555GB。

📖 官方部署文档参考： https://modelscope.cn/models/moonshotai/Kimi-K2.5/file/view/master/docs%2Fdeploy_guidance.md?status=1

1️⃣ 方案 A：使用 vLLM 部署​

vLLM 是一个高性能的大模型推理引擎，支持大规模模型的高效推理。

📍 方法一：本机直接部署​

安装 vLLM（注意版本号！）：

uv pip install -U vllm==0.15.0 
# ⚠️ 注意：一定要安装 0.15.0 及以上版本，才能支持 Kimi K2.5

启动脚本 (单机 8 * 141GB H200/H20)：

vllm serve $MODEL_PATH -tp 8 \
--trust-remote-code \
--tool-call-parser kimi_k2 \
--reasoning-parser kimi_k2 \
--enable-auto-tool-choice \
--port 8000 \
--host 0.0.0.0

📍 方法二：Docker 部署 (推荐 🌟)​

不想污染本地环境？用 Docker！

# 拉取镜像
docker pull vllm/vllm-openai:v0.15.0

启动脚本：

docker run --runtime nvidia --gpus all \
    -v $MODEL_PATH:$MODEL_PATH \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.15.0 \
    --model $MODEL_PATH \
    --trust-remote-code \
    --tool-call-parser kimi_k2 \
    --reasoning-parser kimi_k2 \
    --enable-auto-tool-choice \
    --port 8000 \
    --host 0.0.0.0

🌐 多机部署补充​

如果是双机部署（如 2 * 8 * 96GB H20），需确保节点间网络互通（IB 网络配置正确）。 👉 配置 IB 网络可参考我之前的 DeepSeek 部署文章： https://mp.weixin.qq.com/s/iyYap5ciQd3JtpgBNnld8Q

主节点脚本：

vllm serve $MODEL_PATH \
    --tool-call-parser kimi_k2 \
    --reasoning-parser kimi_k2 \
    --enable-auto-tool-choice \
    --enable-expert-parallel \
    --enable-chunked-prefill \
    --host 0.0.0.0 --port 8000 \
    --distributed-executor-backend mp \
    --pipeline-parallel-size 2 \
    --tensor-parallel-size 8 \
    --nnodes 2 --node-rank 0 \
    --served-model-name kimi-k2.5 \
    --master-addr $HEAD_NODE_IP \
    --trust-remote-code 

从节点脚本：

vllm serve $MODEL_PATH \
    --tool-call-parser kimi_k2 \
    --reasoning-parser kimi_k2 \
    --enable-auto-tool-choice \
    --enable-expert-parallel \
    --enable-chunked-prefill \
    --host 0.0.0.0 --port 8000 \
    --distributed-executor-backend mp \
    --pipeline-parallel-size 2 \
    --tensor-parallel-size 8 \
    --nnodes 2 --node-rank 1 \
    --served-model-name kimi-k2.5 \
    --master-addr $HEAD_NODE_IP --headless\
    --trust-remote-code 

(从节点脚本类似，仅需修改 --node-rank 1 并添加 --headless 参数)

2️⃣ 方案 B：使用 SGLang 部署 (🔥 作者当前在用)​

截止目前，SGLang 尚未发布最新的正式版，需使用开发版本。

📍 方法一：本机源码部署​

# 安装依赖 (源码安装)
pip install "sglang @ git+https://github.com/sgl-project/sglang.git#subdirectory=python"
pip install nvidia-cudnn-cu12==9.16.0.29

启动脚本：

sglang serve --model-path $MODEL_PATH \
--tp 8 \
--trust-remote-code \
--tool-call-parser kimi_k2 \
--reasoning-parser kimi_k2 \
--host 0.0.0.0 \
--port 8000

多机部署，同样的需要首先配置IB网络

# 主节点
sglang serve --model-path $MODEL_PATH --served-model-name kimi-k2.5 \
    --tp 16 \
    --trust-remote-code \
    --tool-call-parser kimi_k2 \
    --reasoning-parser kimi_k2 \
    --dist-init-addr $HEAD_NODE_IP:$HEAD_NODE_PORT \ # 例如我的是10.0.41.2:8000
    --nnodes 2 \
    --node-rank 0 \
    --host 0.0.0.0 \
    --port 8000

# 从节点
sglang serve --model-path $MODEL_PATH --served-model-name kimi-k2.5 \
    --tp 16 \
    --trust-remote-code \
    --tool-call-parser kimi_k2 \
    --reasoning-parser kimi_k2 \
    --dist-init-addr $HEAD_NODE_IP:$HEAD_NODE_PORT \ # 例如我的是10.0.41.2:8000
    --nnodes 2 \
    --node-rank 1 \
    --host 0.0.0.0 \
    --port 8000

📍 方法二：Docker 部署 (推荐 🌟)​

# 1. 拉取最新开发版镜像
docker pull sglang/sglang:dev

# 2. 启动容器
docker run -d --gpus all \
  --shm-size=128g \
  --ipc=host \
  --network=host \
  --name kimi-k2.5 \
  lmsysorg/sglang:dev \
  bash -c "while true; do sleep 3600; done"

# 3. 进入容器
docker exec -it kimi-k2.5 bash

# 4. 在容器内执行方法一中的启动脚本即可

✅ 部署成功验证​

当日志中出现如下内容，恭喜你，模型启动成功！🎊

实测性能：

• 环境：2 * 8 * 80GB H100
• Decode 速度：平均 70-80 tokens/s
• 评价：比 GLM-4.7 和 MiniMax-M2.1 稍慢，但考虑到模型量级巨大，这个速度完全可接受！

🔮 四、 下一步：落地​

相信大家本地部署 Kimi K2.5，绝不仅仅是为了简单聊聊天。🗣️

在 2026 年的今天，编程 和 Agent 才是 AI 的核心生产力。

Kimi K2.5 在这两方面的能力非常强大，加上原生支持多模态，让它在视觉编程方面拥有了天然优势。

想象一下：

📸 你只需要截个图，发给 AI，它就能帮你生成一个一模一样的界面...

这种感觉有多爽？只有亲自体验过才知道！😎

然而，理想很丰满，现实却有些“骨感”。🤔

虽然直接购买官方 API 门槛最低，但在企业级实战中，我们往往面临着两座大山：网络延迟的不确定性 和 核心数据的安全红线。把核心代码交给公网模型？很多团队心里总会犯嘀咕。

既然公有云有顾虑，那**“把能力搬回家”**就成了必然选择。

但问题来了：如何把 Kimi K2.5 这种“巨无霸”平稳落地，并像 API 一样丝滑地接入到我们的开发流中？

这正是我们下一阶段要攻克的重点——从“能跑通”到“好用”，实现真正的本地化生产力闭环。

📝 写在最后​

感谢你看到这里！祝你部署顺利！🎉

下篇文章预告 🚀​

我们将讨论如何将你本地部署的大模型完美接入 Claude Code，让你闲置的 GPU 转冒烟，发挥它的最大价值！🔥

关注我，不迷路！ 👇

只用了几分钟时间，我们就快速搭建了一个可以自动修复Python代码的QuickStart

在本篇文章中我们继续来深入了解Claude Agent SDK的核心组件——query()函数和ClaudeSDKClient类

Claude Agent SDK的核心组件主要包括两个部分：query()函数和ClaudeSDKClient类

如何去选择使用query()函数还是ClaudeSDKClient类​

快速对比​

注意：自定义工具，只能在ClaudeSDKClient里面使用，这是很多新手容易忽略的点

何时使用 query()（每次都是新会话）​

最适合：

• 一次性问题，不需要对话历史
• 不需要之前交换上下文的独立任务
• 简单的自动化脚本
• 当你每次都想要一个全新的开始

何时使用 ClaudeSDKClient（持续对话）​

最适合：

• 继续对话 - 当你需要 Claude 记住上下文时
• 后续问题 - 基于之前的回答构建
• 交互式应用程序 - 聊天界面、REPL
• 响应驱动逻辑 - 当下一个操作取决于 Claude 的响应时
• 会话控制 - 显式管理对话生命周期

简单总结​

以上是官方对query()和ClaudeSDKClient的对比介绍

说简单点，query()函数更适合一次性任务，而ClaudeSDKClient类更适合持续对话和复杂交互

如果你希望做一个AI对话机器人，那么ClaudeSDKClient类无疑是更好的选择

如果你只是想执行一个简单的任务，比如发送一个微信公众号消息，那么使用query()函数就足够了

query() 函数​

我们看一下query()的核心定义

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeAgentOptions | None = None
) -> AsyncIterator[Message]

query()函数接受两个核心参数：

• prompt：可以是一个字符串，也可以是一个异步可迭代对象，对话的提示词
• options：可选的配置对象，默认为ClaudeAgentOptions()

query()函数返回一个异步迭代器AsyncIterator[Message]，可以用来逐步获取Claude Agent的响应

代码示例

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="你是一个经验丰富的Python开发人员",
        permission_mode='acceptEdits',
        cwd="./2-1-query"
    )

    async for message in query(
        prompt="创建一个Python的Web服务器示例代码",
        options=options
    ):
        print(message)


asyncio.run(main())

大概用时几十秒，可以看到AI输出的结果如下

并看到，我们指定目录下生成了相应的代码文件

AI 甚至贴心的给我们写了一份README文件，让我们能轻松的读懂代码

工具调用和Mcp​

AI Agent的核心，还是可以利用各类工具，为我们完成复杂的任务

在上面的例子中，AI Agent就调用了Edit工具，帮我们创建了Python代码文件

我们首先来看tool注解（装饰器）的定义

def tool(
    name: str,
    description: str,
    input_schema: type | dict[str, Any]
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

可以看到，tool注解接受三个参数

对于input_schema参数，有两种方式可以

1. 简单模式

{"text": str, "count": int, "enabled": bool}
// 表示工具需要三个参数，text是字符串，count是整数，enabled是布尔值

2. 复杂模式JSON Schema格式

{
    "type": "object",
    "properties": {
        "text": {"type": "string"},
        "count": {"type": "integer", "minimum": 0}
    },
    "required": ["text"]
}

以上json_schema表示json例子如下

{
    "text": "Hello, World!", // 必填
    "count": 42 // 非必填，最小是0
}

我们现在来自定义一个简单的工具，来让AI打招呼

from claude_agent_sdk import tool
from typing import Any

@tool("greet", "Greet a user", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {
        "content": [{
            "type": "text",
            "text": f"你好, {args['name']}!"
        }]
    }

我们再回顾一下tool的返回值

-> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

可以看到，在Claude Agent SDK中，如果想要使用一个工具，你需要把它注册到MCP服务器（MCP Server）里面才可以使用

my_mcp_server = create_sdk_mcp_server(
    name="my_mcp_server",
    version="2.0.0",
    tools=[greet]  # Pass decorated functions
)


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"my_mcp_server": my_mcp_server},
        allowed_tools=["mcp__my_mcp_server__greet"]
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("你好，我叫东方赞，请使用greet工具")
        async for message in client.receive_response():
            print(message)

asyncio.run(main())

我们详细解释一下这里的代码

1. query()函数无法使用自定义工具，如果要调用工具，你需要使用ClaudeSDKClient，在这里官方文档没有特别强调这一点，会让很多新接触的研发人员感到困惑

2. allowed_tools=["mcp__my_mcp_server__greet"]约定了工具的命名格式，mcp__{server_name}__{tool_name}

在代码执行过程中，可以看到AI成功调用了我们自定义的greet工具的过程

如果我们注释掉allowed_tools参数，AI会向用户发起询问，是否允许使用该工具

我们还可以使用一个外部的mcp server来实现网页抓取的功能

我们可以到模搭社区去找一个免费的mcp server，比如Chrome浏览器工具

首先在本地安装这个mcp server

npx chrome-devtools-mcp@latest

如果你没有安装Node.js，可以先去Node.js官网下载安装

然后我们启动启动执行这个mcp server

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, ClaudeSDKClient
from claude_agent_sdk._errors import CLIConnectionError


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "chrome-devtools": {
                "command": "npx",
                "args": ["chrome-devtools-mcp@latest"]
            }
        },
        allowed_tools=["mcp__chrome-devtools__*"],
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("帮我打开一个新的标签页，进入谷歌官网，并搜索东方赞博客"
                           "找到你觉得最可能是的，进去之后看看他最近写了哪些东西？")
        async for message in client.receive_response():
            print(message)
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(message.result)

asyncio.run(main())

你可以非常清晰的看到整个操作过程

1. AI Agent使用Chrome DevTools打开了一个新的标签页
2. 进入谷歌官网
3. 搜索“东方赞博客”
4. 找到最可能的结果，进入博客页面
5. 查看最近的文章内容
6. 完成总结

我把整个视频录制了一份，感兴趣的朋友可以看下整个过程

总结​

本文我们深入介绍了Claude Agent SDK的核心组件——query()函数和ClaudeSDKClient类

我们详细对比了两者的区别和使用场景，并通过工具调用和MCP，来展示了如何利用Agent SDK来完成复杂的任务

下篇文章，我们会继续深入其他更多的特性，比如流式输入、中断、钩子函数等高级功能

感谢你看到这里，如果你对Claude Agent SDK有任何问题，欢迎在评论区留言讨论！

大家开始逐步开发落地AI应用，而Claude Agent SDK的出现，无疑为开发者提供了一个极其便利的工具

本系列文章，我们就来介绍Claude Agent SDK的使用方法和一些实战经验

使用 Claude Code 作为库构建生产级 AI 代理

构建能够自主读取文件、运行命令、搜索网络、编辑代码等的 AI 代理。Agent SDK 为您提供了与 Claude Code 相同的工具、代理循环和上下文管理，可在 Python 和 TypeScript 中编程。

Agent SDK 包含用于读取文件、运行命令和编辑代码的内置工具，因此您的代理可以立即开始工作，无需您实现工具执行。深入了解快速入门或探索使用 SDK 构建的真实代理

官方文档地址

以上是官方对Claude Agent SDK的介绍

快速开始

下面我们就来快速体验一下Claude Agent SDK的使用方法

环境准备​

• Node.js 18+ 或 Python 3.10+
• 一个Anthropic账户
• 或支持兼容Anthropic API的模型（你可以使用最新版本的Ollama进行本地测试）

以下都是用Python版本进行演示

安装​

Claude Code 安装​

Agent SDK是使用Claude Code作为其运行时的，所以你需要先安装Claude Code

# macOS/Linux/WSL
curl -fsSL https://claude.ai/install.sh | bash

或者使用npm进行安装

npm install -g @anthropic-ai/claude-code

安装Agent SDK包​

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

配置本地环境变量​

ANTHROPIC_API_KEY=sk-ant-your-key-here
兼容Anthropic API的地址
# ANTHROPIC_BASE_URL=http://localhost:3456

Hello World 示例​

编写代码如下

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="你好，请介绍一下自己",
        options=ClaudeAgentOptions(
            allowed_tools=["Read"],  # Tools Claude can use
        )
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)              # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")   # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # Final result

asyncio.run(main())

# Output:
# 我是 Claude，由 Anthropic 开发的 AI 助手。我可以在对话中帮助你完成各种任务，包括：

# **💻 编程与开发**
# - 编写、审查和调试代码
# - 帮助设计软件架构
# - 修复 bug 和优化性能
# - 运行命令和测试

Agent能力示例

为了展示Agent的能力，我们可以让它读取一个本地文件，以官方文档中的例子为例

首先，我们可以准备一个有缺陷的代码如下，并保存到本地叫做utils.py：

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    return user["name"].upper()

在这段代码中，有两个主要错误

1. calculate_average 函数在计算平均值时没有处理空列表的情况，这会导致除以零的错误。
2. get_user_name 函数假设传入的 user 字典中总是包含 name 键，如果缺少该键会引发 KeyError。

我们使用Agent SDK来让Claude自动修复这些错误

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    # Agent执行循环
    async for message in query(
        prompt="请审查代码utils.py，查找可能导致崩溃的错误。修复你发现的任何问题。",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # 可以使用的工具
            permission_mode="acceptEdits"            # 自动批准文件编辑
        )
    ):
        # 打印人类可读的输出
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)              # Claude的推理过程
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")   # 调用的工具
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # 最终结果
asyncio.run(main())

可以看到输出内容如下

我会帮您审查并修复 utils.py 文件中的潜在错误。让我先读取这个文件。
Tool: Glob
Tool: Read
我发现了这个文件中存在几个可能导致崩溃的错误：

## 发现的问题：

1. **`calculate_average` 函数 - 零除错误**：当 `numbers` 为空列表时，`len(numbers)` 返回 0，导致除零错误。

2. **`get_user_name` 函数 - KeyError**：当传入的字典中没有 "name" 键时，会抛出 KeyError。

3. **`get_user_name` 函数 - AttributeError**：如果 `user` 不是一个字典，或者 `user["name"]` 不是字符串，调用 `.upper()` 会失败。

4. **`get_user_name` 函数 - TypeError**：如果传入的不是字典类型，索引操作 `user["name"]` 会失败。

现在让我修复这些问题：
Tool: Edit
Tool: Edit
完成！我已经修复了所有可能导致崩溃的错误。以下是修复的详细说明：

## 修复内容：

### 1. `calculate_average` 函数
**问题**：空列表会导致 `ZeroDivisionError`
**修复**：添加了空列表检查，当列表为空时返回 0

### 2. `get_user_name` 函数
**问题**：多个潜在错误
- `KeyError`：字典中没有 "name" 键
- `AttributeError`：不是字符串类型无法调用 `.upper()`
- `TypeError`：传入的不是字典类型

**修复**：
- 检查 `user` 是否为空或不是字典类型
- 使用 `.get()` 方法安全地获取 "name" 值，避免 `KeyError`
- 使用 `str()` 转换确保类型正确
- 添加空字符串检查，避免对空值调用 `.upper()`

现在这两个函数都具有更强的健壮性，能够处理各种边界情况而不会导致程序崩溃。

随后检查utils.py文件，发现代码已经被自动修复为如下内容

def calculate_average(numbers):
    if not numbers:
        return 0
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    if not user or not isinstance(user, dict):
        return ""
    name = user.get("name", "")
    return str(name).upper() if name else ""

可以看到，只需要几分钟时间，我们就用agent sdk实现了一个自动读取，自动修改代码的AI Agent

当然我们也可以通过更改一些参数，来修改Agent的能力，比如增加网络搜索

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

或者给Claude一个自定义的系统提示词

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="你是一个经验丰富的Python开发者，请帮我审查并修复代码中的错误。"
)

亦或者直接执行bash命令

options=ClaudeAgentOptions(
    # 允许Bash工具
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)

工具​

工具是Claude Agent SDK的核心能力之一

它可以控制你的Agent能够执行哪些操作

权限模式​

权限模式(permission_mode)主要用于控制你需要多少人工干预

更多权限模式的介绍，我们可以参照官方文档，也可以我们以后再来探讨

总结

截止到这个阶段，我们了解到了Claude Agent SDK的基本使用方法

与我们熟悉的OpenAI的/chat/completions接口相比

Claude Agent SDK完整的封装了Agent的能力，让你不用再关心

1. 如何管理上下文
2. 如何调用工具
3. 如何处理多轮对话
4. 如何处理文件读写 等等复杂的逻辑，也让你可以更专注于业务逻辑的实现

相较于LangChain等框架，Claude Agent SDK将整个Think-Act-Observe流程进行了高度封装，且性能更优，使用体验更好

好了今天的快速入门就到这里，感谢你看到这里，下期见

相信很多使用过人的朋友在尝试过一次后，都会被深刻的震撼到

最近也看到很多大佬的谈到，Claude Code 用 1 小时就完成了过去一年以来所构建的东西

那么在高强度的复杂工程里面，Vibe Coding 究竟能带来什么样的体验呢？

在过去的 10 天里，我消耗了10亿Tokens，就来分享一下我的一些实际体验和心得吧。

首先需要声明的是，能消耗这么多token，并不是我钞能力无敌，可以肆意挥霍

而是这段时间我用的都是私有化部署的开原模型，分别是

1. GLM-4.7
2. MiniMax-M2.1
3. Qwen3-235B-A22B
4. DeepSeek-V3.2

同时再叠个甲，上述几个模型，都是用的开源方案进行本地部署的

虽然decode的速度比官方快很多，但是并不具备官方的编程工具，且对Claude Code的适配也并不完善

所以无论你用的是Claude的模型，还是用官方的上述模型，实际效果应该都会比我更好

一开始

熟悉的朋友可能了解，我们在公司内部使用OpenWebUI搭建了一套AI系统，专门服务内部用户。

OpenWebUI是一个超过120k⭐️的超级开源项目，相信很多人都知道他

有超过700位开发者贡献过代码，我自己也是其中之一[旺柴]

我们在上面搭建了以上几个模型的服务，用户可以在OpenWebUI上直接调用DeepSeek等相关模型

同时建了一个RAG系统，用于回答内部用户的问题

这套系统在线上跑了一年之后，用户反馈也非常不错，但也存在不少问题，比如

1. 用户不知道这一大堆模型该怎么选，哪个能识图？哪个能写代码？哪个能写材料？是被问到最多的问题
2. RAG出来的东西不准，需要人工校验
3. AI办事流程开发复杂，连个简单的请假，都要专门写工作流

RAG的问题尤其凸显

在文档数据量从几百个增长到几十万个的时候

花费在人肉排查问题上的时间，有时候比RAG本身带来的提效要高很多

比如下面这个问题，在文档数超过80000个后，rerank模型对某些明明正确的结果给出的灾难性打分

求助了很多朋友都遇到这种类似的问题

RAG的感觉就是Demo很美好，一落地就抓瞎

固定的RAG工作流，有时候让在用户只问一个简单问题，也要忍受查询文档的缓慢过程

这体验非常糟糕，这也是在当下这个时点内部AI系统面临的困境。

对于这种用业余时间维护的为爱发电项目，就几乎变成了一个无法维护的项目

OpenAgentWebUI

那么在当下这个时间点，如果要搭建一个内部AI系统，Agent模式肯定是最合适的

所以基于这个考虑，我就开始尝试基于Claude Code搭建一个OpenAgentWebUI来解决上述问题

1. 只有一个AI​

不让用户选择，就没有模型选择的问题

这个AI能识图、能写材料、能写代码、能画图、能查内部资料、能办事

2. Agentic RAG​

针对不同用户的不同任务，由AI自主判断，选择合适的RAG工作流

这也就是Agentic RAG的概念

3. 保持用户习惯​

为了降低用户的学习成本，与现在所有的AI保持一致，用户在使用OpenAgentWebUI的时候，不需要学习新的指令，只需要按照现在的习惯来使用即可。

开始编码

我给把前面的故事给Claude Code讲了一遍

接下来让AI根据我的描述进行计划并实施编码后，他给了我这样一个界面

看起来完全不可用，简直丑的不忍直视

看到这个的时候连我自己都在笑这是什么玩意

反思​

如果是这样的话，那压根就没有做了，这得做到猴年马月了，这Vibe Coding也不行啊

但是仔细回想，这只是AI一次生成的，如果我把整个工作流按照正常的开发流程来一遍，也许可行呢？

设计先行​

相信各位在公司里做开发，也是首先产品设计方案，其次UI/UX出原型图，最后根据原型图进行开发的吧

那么好，我们就从设计开始，让AI不考虑任何功能实现，我们只考虑UI/UX的设计，用纯html+css的方式来只做样式设计

很快，大概用了半个小时左右的调整和细化，原型很快就做出来了

设计稿在代码仓库的frontend/design目录下

看到这个原型的时候，信心就都回来了

原来我一个从来没搞过设计的后端工程师，也能做出来一个看着还不错的原型设计了啊！

接着编码​

有了设计稿，就开始让 AI 一比一的还原设计稿

接下来就是一边摸鱼，一边干活，边调试边优化

一杯茶，一包烟，敲打AI一整天的方式完成了整个前端的开发

中间遇到一些AI乱写的地方，我会及时提醒他，让AI严格按照设计稿进行还原，比如一开始写成了这个样子

再根据心情一点点的调整，最后得到了这样的前端

在功能上，登录、注册、对话管理、AI对话、浅色/暗色切换、多语言、上传附件、搜索对话、用户编辑等十多个大的功能点基本上开发完成

截止到达到这个阶段，也才过去了一周不到，效率算是远超预期，接着我又开始了后端的开发

所有的代码我都公布在了

https://gitee.com/zsy3313422/open-claude-webui

目前尚未开发完成，最近写的有点累了，总结一下经验换换脑子，感兴趣的朋友也可以看看给点意见

经验总结

从开始琢磨这个事情，到完善一个可用的前端代码，也才过去了几天时间，这种效率是非常恐怖的

以我一个后端工程师的经验，估计写完这套前端代码，至少要花上可能数月的时间

AI编码效率，目前已经达到了一个非常高的水平，但是如何让AI编码能规范的按照你的思路进进行编码，以下是我的一点经验总结

1. 先有设计，再编码​

在AI的帮助下使用figma、sketch等工具先设计出原型图，可以让你更在一开始的阶段更注重用户体验

设计稿写的越精确，AI编码的结果就越符合你的预期

如果你像我一样没用过设计工具，直接用html和css也是一个思路，不必拘泥于形式

2. Plan之后再Coding​

在开启每次PR之前，使用Claude Code的Plan Mode（按两下shift+tab切换）与AI进行讨论完善计划

磨刀不误砍柴工，经过多轮讨论后生成代码质量更高，考虑的内容会更完善

3. 尽早开始维护你的CLAUDE.md​

可能有人不知道什么是CLAUDE.md

这个文件是Claude Code的底层规范，分成三层 1. 系统级，由Claude管理，用户操作不了 2. 用户级，你自己的编码习惯和规则，在各个项目中通用 3. 项目级，仅在具体项目中使用

他就像整个开发团队里的约束文档，规定了整个项目的编码规范、设计规范、功能规范等

如果没有约束，AI写起代码来就会天马行空

一个很典型的例子就是，AI有可能一会用html自己写组件，一会引入一个乱七八糟的组件来实现相同的功能

时间长了你的代码就会变得几乎不可维护

4. 把你自己当做技术主管而不是程序员​

在编码的过程中，你要把自己当做技术主管，而不是简单的当做一个程序员

你大量的时间，应该放在如何制定约束，让AI按照你的约束进行编码

比如我自己常用的

1. 代码查找时优先使用 LSP 工具
2. 访问外部网站时，如果访问失败使用本地代理
3. 前端在写css是严格限制使用 Tailwind CSS 类名
4. **优先使用现有组件框架**，避免从零手写 HTML/CSS 实现
5. 设计数据库时⚠️严禁使用 UUID 作为主键
6. ⚠️严禁使用数据库外键约束

你可以使用自己的编码习惯和团队习惯来进行约束

如果是团队工作，可以由整个团队共同讨论的编码规范结果

最终写入一个由团队共同使用的CLAUDE.md文件来约束AI的行为

相信你会用的越来越顺畅

5. 学会接受不完美​

有很多人都讨厌屎山代码，很多人吐槽AI写的屎山代码

但是事实上说句可能扎心的话，没有程序员会觉得自己写的代码是屎山，但是看别人写的都是屎山

看看自己身边的同事写的代码

再看看公司内部前人遗留下的代码

有多少代码是真正让你看了会觉得写的真棒👍🏻？

有多少代码是让你看了后觉得就是写的一坨屎山？

接受AI写的不完美，就像是你不得不接受几年请青涩的自己，和其他人写的不完美的代码

真正实现价值，比写出完美的代码更重要

结束

好了感谢你看到这里，接下来我会继续完善上面的项目，并继续探索AI Coding

欢迎留下你的宝贵意见，我们下期再见啦！

我讲述了我自己如何从 AI 辅助编程，转向 Vibe Coding 的心路历程

相信很多人都有类似经历，但是也会怀疑

1. Vibe Coding 到底有没有用？如何才能真正利用 Vibe Coding 来提升编程效率？
2. Vibe Coding 很贵，是否值得购买？有没有更便宜的方案？
3. 受限于网络问题，国外模型不可用/公司内网环境无法对接外网，是否有解决方案？

在本篇文章中，我们就来一一解答这些问题

首先，Vibe Coding 是一个基于 AI 的编程工具，它的主要作用是帮助开发者快速生成代码。

从 3 月份 Claude Code 发布以来，已经过去了 9 个月时间

Claude Code 的作者 Boris 在 X 上放出了自己过去 30 天里的真实生产数据：

在过去 30 天里，我合并了 259 个 PR —— 共 497 次提交，新增约 4 万行代码，删除约 3.8 万行代码。而且，每一行代码都是由 Claude Code + Opus 4.5 编写的。

Claude 可以稳定地持续运行数分钟、数小时，甚至数天（借助 Stop hooks）。

当然如果你觉得他是作者自卖自夸，但其实 Claude Code 是一个开源项目

所有人的提交记录都可以在代码仓库里查看

https://github.com/anthropics/claude-code

毕竟数据不能作假，Vibe Coding 已经确确实实成为了很多人的选择

2. 如何才能真正利用 Vibe Coding 来提升编程效率？

分享一下我自己的一个真实编程环境

这是字节跳动的 TRAE + Claude Code 组合

我不仅用它来写代码，还用来写文档，甚至还用他来学习。

代码层面​

代码质量的好坏其实更多取决于你使用的模型好坏

这个与大家在网页上进行对话式的问答写出来的代码差别不大

区别更多的在于，Claude Code 能够直接读取你仓库中的代码，而不再依赖你手动复制粘贴

对于一个代码仓库，你可以直接让模型分析整个仓库的核心逻辑

分析可能存在的问题，例如代码质量、性能问题、安全问题等

并让其直接修复

你甚至可以让模型直接操作 git 仓库，比如提交代码、创建发布、自动合并 PR、构建镜像并发布到仓库

将原来需要折腾一整套 CICD 流程的时间大幅简化

文档层面​

基于整个代码仓库，一次性生成 README 文档，帮助其他开发者快速了解项目的功能、安装方法、使用示例等。

学习新知识​

对于不了解的新知识，Claude Code 可以直接帮助你学习并理解

比如，我希望学习 LangChain 这一开发框架

就可以让 Claude Code 直接讲解 LangChain 的基本概念、架构、使用方法等，并生成相应的示例代码

还有更多高效的功能可以让你事半功倍

3. 如何使用 Claude Code

3.1 安装 NodeJS​

Claude Code 是一个 NodeJS 模块，因此你需要先安装 NodeJS

你可以从 https://nodejs.org/ 下载并安装最新版本的 NodeJS

3.2 安装 Claude Code​

安装完成 NodeJS 后，你可以使用 npm 来安装 Claude Code

npm install -g @anthropic-ai/claude-code

安装完成后，执行下面的命令，你就可以看到 Claude Code 的界面了

claude

3.3 安装 IDE 插件​

为了更方便地使用 Claude Code，你可以安装对应的 IDE 插件

取决于你的爱好，VS Code 或 JetBrains 等 IDE 都有对应的插件

VS Code 插件（推荐）​

你可以在 VS Code 插件市场搜索 "Claude Code" 并安装

然后点击代码窗口右上角的 "Claude Code" 图标，即可打开 Claude Code 界面

JetBrains 插件​

同样的，在 JetBrains 插件市场搜索 "Claude Code" 并安装

相比之下，VS Code 插件的功能更强大，使用体验更好

安装好了之后，其实就可以直接使用 Claude Code 了

但是！Claude Code 原生的不仅受限于网络限制，而且价格并不便宜

想要拿来高强度编码的话，即使是 20 美元的 Pro 订阅方案也经不住造

4. 有没有更便宜的方案？

其实国内很多模型，都提供了 Claude Code 对接方案

如果你已经买了相应的模型订阅，那么就可以直接使用

DeepSeek​

https://api-docs.deepseek.com/zh-cn/guides/anthropic_api

GLM​

https://docs.bigmodel.cn/cn/coding-plan/tool/claude

通义千问系列​

https://bailian.console.aliyun.com/?tab=doc#/doc/?type=model&url=2949529

CC Switch​

这里还推荐一个软件叫做 CC Switch

它可以帮助你在不同的模型供应商之间切换，而不需要重新安装插件

https://github.com/farion1231/cc-switch

不能上外网，只能用内网的方案

如果你的公司有严格的网络策略，不能直接上外网，只能通过内网访问模型 API

当然如果公司内部能够统一搭建 Claude Code 代理来给用自然是最好的

如果没有，你需要找公司的 AI 部门，询问是否能够提供一个内部的模型 API 地址

这个 AI 的地址分为两种情况

1. OpenAI 格式，通常是/v1/chat/completions结尾
2. Claude 格式，通常是/v1/messages结尾

如果你的内网 AI 接口支持第 2 种 Claude 格式，按照上述方法简单配置一下 API 地址，即可直接使用 Claude Code

但在当前的市场上，绝大多数模型都只支持第 1 种 OpenAI 格式

Claude Code 本身却不支持这种格式，所以你需要进行转换。

Claude Code Router​

你可以借助一个叫做 Claude Code Router 的工具来实现这一转换

https://github.com/musistudio/claude-code-router

在已经安装完 Claude Code 后，安装 Claude Code Router

npm install -g @musistudio/claude-code-router

并使用下面的命令启动配置 Claude Code Router

ccr ui

在此，就可以将自己部署/第三方的 OpenAI 模型接入 Claude Code 中使用啦！

最后

从最初的怀疑到现在的高效使用，Vibe Coding 确实已经证明了它的价值。

这不是要让 AI 完全取代程序员，而是让程序员从重复的编码工作中解放出来，将更多精力投入到架构设计、产品思考和创新上。

当你不再纠结于代码的细节，而是专注于"要做什么"而非"怎么写"时，你的生产力将得到质的飞跃。

Vibe Coding 不是终点，而是编程方式的新起点。在这个 AI 时代，学会与 AI 协作，将成为每个程序员的核心竞争力。

与其观望和怀疑，不如亲自体验一下。也许过不了多久，你也会和我一样感叹：原来写代码可以这么轻松。

2025年12月26日，一个普通的冬天 ❄️

我坐在电脑前，像往常一样准备开始写代码。

但这一次，我没有打开 IDE，没有新建文件，没有敲下第一行 import。

我只是打开了一个软件

然后，我开始"说话"：

"帮我写一个通用后台管理系统，就像 RuoYI 一样，支持用户管理、角色管理、菜单管理、操作日志管理……"

几分钟后，一个完整的系统，出现了在我的面前。

那一刻，我意识到：我不再需要"写"代码了。

十年：写代码的方式从未改变​

2014年，我硕士毕业 🎓

这十年，我走过不少地方：国企、互联网公司、事业单位，后来又做了几年数字游民，接单写代码。

环境在变，节奏在变，但我的写代码方式始终没变：

需求来了 → 打开 Google → 搜索 "Java 实现 xxx" 
→ 翻十几页结果 → 复制粘贴 → 改改改 → 跑通

搜索引擎是我最好的朋友，Stack Overflow/CSDN/博客园 是我的第二个家。

ChatGPT 带来的变革​

2023年，ChatGPT 横空出世 🔥

我也开始用 AI 辅助写代码，但那时候 AI 对我来说，只是一个更聪明的搜索引擎：

• 它给我答案
• 但代码还是要我自己改
• Bug 还是要我自己调

但我依然是"写代码的人"，AI 只是帮我写得快了一点。

2025年，国产 AI 模型开始崛起 🇨🇳

DeepSeek、智谱、月之暗面... 一个个名字刷屏。

最直接的感受：

选择更多了，体验更好了，门槛更低了。

真正的 Vibe Coding​

到了 2025 年 3 月，Claude Code 出现了 🤖

号称是 Vibe Coding 的标杆，大家都说好用。

但我试了之后，真的是特别强，特别好用

但也还是那两个老问题：

尤其是命令行编程的模式，跟我用了十年的"手写代码"习惯完全冲突。

打开 IDE、敲代码、改代码、跑代码，这套流程已经刻进肌肉记忆了。

突然让我对着命令行说话，说实话，不愿意尝试。

终于找到「对味儿」的 Vibe Coding 🎯​

在我以为接下来的几年之内，我可能还是会继续用人写 + AI 辅助的方式来写大型项目。

也会尝试用 Vibe Coding 来写一些简单的脚本，或者是一些小项目。

但随着 GLM4.7 和 ZCode 的发布，好像一切都发生了一点点变化。

首先国产模型也比肩最强了​

在大模型排行榜上，GLM4.7 超过了最新的 GPT-5.2，接近 gemini 和 Claude 等顶尖模型

很多大牛博主实测，GLM4.7 写出来的代码已经非常可用，甚至很好用了

其次是成本上的优化​

购买官方的接口，3 倍的用量，1/7 的价格

再次是工具上的革新​

Z Code 是一个编码工具，它将最优秀的 AI 智能体与你现有的工具完美结合，让你能够无缝地进行规划、编码、审查和部署。

他可以直接使用官方的 Claude 模型、智谱系列模型

还可以使用你自定义的模型，并将其直接接入到 Claude Code 中

针对于不喜欢命令行编程的用户，Z Code 提供了一个基于 GUI 的界面，你可以直接在界面上"说话"，直接看到结果

彻底解决了Claude Code 的三大痛点 💥

最后，最重要的是速度上质的飞跃​

对于我来说，GLM 4.7 带给我的最大的影响，其实是速度上的飞跃。

如果你有私有化部署的 GLM4.7-FP8 在 H100 上运行，decode 的速度会达到惊人的 200 tokens/秒。

即使是稍差一点的 H20，decode 的速度也会达到 160 tokens/秒。

这是我用过速度最快的旗舰模型，没有之一。

别小看这点速度的提升，它对编程体验的改变是颠覆性的 💥

为什么速度这么重要？🤔​

想象一下这样的场景：

当代码以"说话"的速度生成时：

• ✅ 思维不会被打断 — 你的思路还在，代码就已经出来了
• ✅ 反馈即时可见 — 改完需求，马上看到结果
• ✅ 沉浸式编程 — 进入心流状态，效率翻倍
• ✅ 多轮迭代更轻松 — 一分钟内可以完成 3-5 次调整

真实感受对比 📊​

以前的体验：

我："帮我写一个用户登录功能"
AI: ████████░░░░░░░░░░░░░░ 30%
     [等待中... 喝口水... 看看手机...]
AI: ████████████████░░░░░░ 60%
     [还在生成... 思路都断了...]
AI: █████████████████████ 100%
     [终于好了，忘了刚才想说什么了]

现在的体验：

我："帮我写一个用户登录功能"
AI: █████████████████████ 100% ✨
     [哇！这么快！继续...]
我："把密码改成 BCrypt 加密"
AI: █████████████████████ 100% ✨
     [改好了！]
我："再加个验证码功能"
AI: █████████████████████ 100% ✨
     [搞定！]

现在，我们回到一个老生常谈的问题

程序员会被 AI 取代吗？​

我觉得会，也不会。

会被替代的，是"代码工人"。哪怕你精通十几种编程语言，如果每天的工作只是机械地写业务代码、CRUD、复制粘贴——那 AI 确实能做得更出色。

不会被替代的，是那些把时间花在解决问题上的人，这也回归了工程师本来的意义。

Vibe Coding 🤖 的存在的价值就在于

🎯 让我们从"写代码的人"变成"解决问题的人"

• 不再纠结语法细节
• 不再重复造轮子
• 专注于业务逻辑和架构设计
• 把更多时间花在真正有价值的事情上

这就是从今天开始，我不再"写"代码的原因。

给还在犹豫的你 💡​

如果你也在犹豫要不要尝试 Vibe Coding，我的建议是：

📌 现在就开始

1. 📥 下载 Z Code（支持 macOS 和 Windows）
2. 🔗 接入 GLM4.7
3. 🗣️ 开始用自然语言写代码
4. 🚀 体验效率提升

别等了，未来已经来了。 🌟

最后的话 📝​

十年前，我学会了写代码。

十年后，我学会了不写代码。

这不是倒退，而是进步。

因为我们终于可以专注于真正重要的事情——用技术解决问题，创造价值。

欢迎关注 🌟​

如果你喜欢这篇文章，欢迎关注我的公众号：

「程序员阿赞」 👨‍💻

我会在这里分享：

• 🔥 最新 AI 技术动态
• 💻 高效编程技巧
• 🚀 工具使用心得
• 📖 技术成长之路

话不多说直接开始，模型下载地址：

https://modelscope.cn/models/XiaomiMiMo/MiMo-V2-Flash

https://huggingface.co/XiaomiMiMo/MiMo-V2-Flash

下载完成后，可以看到整个模型文件大小为292G

在比较知名的开源模型中，与通义千问3-235B-FP8模型大小近似

简单做个对比如下

Mimo-V2-Flash是在FP8上原生训练的而Qwen3并不是，所以这里仅对比同在FP8下的模型大小

Day0 部署准备

这里我的测试机器是一台8 * H100 80G的服务器

根据模型卡片描述，我们可以直接使用sglang的python包进行启动。

为了环境更纯净，通常来说用docker可能更简单点

我们可以找到sglang最近的dev版本

docker pull lmsysorg/sglang:dev

截止到写稿时，sglang还没有发布正式支持Mimo-V2-Flash的新发布版本

小米牌面不行啊[吃瓜]，DeepSeek每次都是秒发

部署开始

1.使用下面的启动命令，将容器挂起

docker run -d --gpus all \
  --shm-size=32g \
  --ipc=host \
  --network=host \
  --name mimo-v2 \
  -v /path/to/huggingface:/root/.cache/huggingface \
  lmsysorg/sglang:dev \
  bash -c "while true; do sleep 3600; done"

2.进入容器

docker exec -it mimo-v2 bash

3.卸载容器内已经按照好的sglang，并按照包含了mimo-v2-flash的sglang

pip uninstall sglang -y

pip install sglang==0.5.6.post2.dev8005+pr.15207.g39d5bd57a \
  --index-url https://sgl-project.github.io/whl/pr/ \
  --extra-index-url https://pypi.org/simple

4.执行下面的命令来启动模型

export SGLANG_ENABLE_SPEC_V2=1
nohup python3 -m sglang.launch_server \
      --model-path /root/.cache/huggingface/hub/XiaomiMiMo/MiMo-V2-Flash \
      --served-model-name mimo-v2-flash \
      --pp-size 1 \
      --dp-size 2 \
      --enable-dp-attention \
      --tp-size 8 \
      --moe-a2a-backend deepep \
      --page-size 1 \
      --trust-remote-code \
      --tool-call-parser mimo \
      --chunked-prefill-size 16384 \
      --reasoning-parser qwen3 \
      --context-length 262144 \
      --attention-backend fa3 \
      --speculative-algorithm EAGLE \
      --speculative-num-steps 3 \
      --speculative-eagle-topk 1 \
      --speculative-num-draft-tokens 4 \
      --host 0.0.0.0 \
      --port 8000 > app.log 2>&1 &

需要注意的是，官网放出的--enable-mtp，在H100上无法正常启动

最后我们如果看到下面的日志，就表明启动成功啦！

找一个AI客户端来看使用成果

可以看到Decode的速度是非常快的

最快可以达到170tokens/s

平均也达到了110tokens/s，比较惊喜，也超过了在默认启动参数下Qwen3-235B

深度思考

Mimo-V2-Flash是一个支持切换思考和非思考的模型

通过模型卡片描述可以看到

curl -i http://localhost:9001/v1/chat/completions \
    -H 'Content-Type:application/json' \
    -d  '{
            "messages" : [{
                "role": "user",
                "content": "Nice to meet you MiMo"
            }],
            "model": "mimo-v2-flash",
            "max_tokens": 4096,
            "temperature": 0.8,
            "top_p": 0.95,
            "stream": true,
            "chat_template_kwargs": {
                "enable_thinking": true
            }
        }'

通过参数来控制思考开关

"chat_template_kwargs": {
    "enable_thinking": true
}

与其他模型不同，在现阶段本地部署的Mimo-V2-Flash

enable_thinking是必须要传的

否则会导致模型回复的内容直接解析到了思考内容中

这可能是由于早期版本使用的通义千问的reasoning-parser导致的问题，待后续修复

工具调用

在不开启深度思考模式时，目前工具调用可以正常使用

开启深度思考后，如果temperature过高，很大程度上会导致工具调用失败

推荐temperature=0.3时

在使用时尽量按照官方文档中推荐的采样参数进行设置

IMPORTANT 推荐的采样参数： top_p=0.95 temperature=0.8 适用于数学、写作、Web 开发 temperature=0.3 适用于自主任务（例如，氛围编码、工具使用）

结尾

好啦，这就是Mimo-V2-Flash在Day0的一些本地部署测试

目前还存在一些小bug，应该会在后续版本中修复，随着持续优化也会有更强的性能

接下来一段时间我这边也会持续使用一段时间这个模型

看一下在写作、编程等实际使用场景的效果如何

感谢你看到这里啦！

我们在2台 8 * H100 80G上成功的完成了部署并使用了几天，并在真实的生产环境上运行了几天，也遇到了一些问题，随之对相应的问题进行了一些调整和优化，本文就来详细说一说。

VLLM上恼人的性能问题​

首先声明，应该不是引擎有问题，应该是我菜还没找对办法，这个引擎是相当强大的！

VLLM在2025年1月27日公布了V1版本，具体的详细内容可以看

https://blog.vllm.ai/2025/01/27/v1-alpha-release.html

主要就是为了解决过去V0版本的性能问题和大量技术债务，但是遗憾的是，在当前这个时间点官方貌似并没有在V1引擎上支持Deepseek

所以在上一篇文章中，我也只能无奈选择退回到V0引擎的版本。

听闻有些技术能力强的大厂哥哥们已经搞定了这个问题，这个确实佩服，点赞👍！

起初在部署起来的时候是非常让人兴奋的，简单看了一下VLLM后台的日志，每秒的生成速度在21-30之间波动，人肉平均一下就是25tokens/s左右（没有详细测，人肉估计），人肉检测首个token返回时间大概在1.8s-1.9s左右，已经达到了跟官网网页上的速度类似的速度。

但是随着开放使用之后，问题就来了，在处理长上下文的时候（4k以上），出现了一种偶发性的降速，并且这个请求直到处理完之前，都会一直保持1 tokens/s以下

在nvidia-smi中可以看到所有GPU的利用率会直接冲到100%，直到这个超卡的请求全部生成完，才会恢复正常。

实体感受就像一个人前一秒在滔滔不绝的疯狂输出，下一秒他突然就卡壳了。

如果单纯只是这一个请求卡住了，那么影响的是这一个人的使用，倒还勉强能接受。

可惜的是接下来进来的每一个请求都会非常慢，有一种一个坏学生把全班的好学生都教坏了的既视感😂。

如果长prompt无法使用，那么就注定在RAG这个企业内部最常用的AI场景出现了死局。

二、调整思路

鉴于上述问题，希望有感兴趣的大佬也可以来指导我一下，感激不尽，我这边也会和开源社区继续研究推理引擎，把这个问题解决掉。

马斯克说，很多即使很优秀的工程师都会在已有的路径上持续去优化一个也许不该存在问题，这就是路径依赖。通往罗马的路不止只有一条，可以解决这个问题的方法也可以让问题本身不存在。

抱着这样的想法再来回头重新审视问题，重新找到Deepseek的官方仓库：https://github.com/deepseek-ai/DeepSeek-V3，可以看到除了第一个以外，Deepseek推荐的第一个是一个叫作SGLang的推理引擎。

查看这个引擎的文档清晰的写到：SGLang从一开始就在与Deepseek团队深度合作，完成了Deepseek V3的适配工作，并且给出的详细的部署步骤。

部署文档可见：https://github.com/sgl-project/sglang/tree/main/benchmark/deepseek_v3

有了这个，我们只需要重新调整一下部署脚本，把相应的Deepseek V3换成Deepseek R1即可（tokennizer是一样的，所以可以通用）

在两个节点上分别执行下面的命令，过一会就看得到

# 在两个节点上分别执行命令
# 节点1
docker run --gpus all \
--shm-size 128g \
--network=host \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--name sglang_multinode1 \
-d \
--ipc=host --restart always \
--privileged -e NCCL_IB_HCA=mlx5_1,mlx5_2,mlx5_3,mlx5_4,mlx5_5,mlx5_6,mlx5_7,mlx5_8 -e NCCL_P2P_LEVEL=NVL -e NCCL_IB_GID_INDEX=0  -e NCCL_IB_CUDA_SUPPORT=1 -e NCCL_IB_DISABLE=0 -e NCCL_SOCKET_IFNAME=ibs11,ibs12,ibs13,ibs14,ibs15,ibs16,ibs17,ibs18 -e NCCL_DEBUG=INFO -e NCCL_NET_GDR_LEVEL=2 \
egistry.cn-hangzhou.aliyuncs.com/dongfangzan/sglang:v0.4.2.post3-cu124 \
python3 -m sglang.launch_server --model-path /root/.cache/huggingface/hub/deepseek-ai/DeepSeek-R1 --served-model-name deepseek-r1 --tp 16 --dist-init-addr ip1:20000 --nnodes 2 --node-rank 0 --trust-remote-code --host 0.0.0.0 --port 8000

# 节点2
docker run --gpus all \
--shm-size 128g \
--network=host \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--name sglang_multinode1 \
-d \
--ipc=host --restart always \
--privileged -e NCCL_IB_HCA=mlx5_1,mlx5_2,mlx5_3,mlx5_4,mlx5_5,mlx5_6,mlx5_7,mlx5_8 -e NCCL_P2P_LEVEL=NVL -e NCCL_IB_GID_INDEX=0  -e NCCL_IB_CUDA_SUPPORT=1 -e NCCL_IB_DISABLE=0 -e NCCL_SOCKET_IFNAME=ibs11,ibs12,ibs13,ibs14,ibs15,ibs16,ibs17,ibs18 -e NCCL_DEBUG=INFO -e NCCL_NET_GDR_LEVEL=2 \
egistry.cn-hangzhou.aliyuncs.com/dongfangzan/sglang:v0.4.2.post3-cu124 \
python3 -m sglang.launch_server --model-path /root/.cache/huggingface/hub/deepseek-ai/DeepSeek-R1 --served-model-name deepseek-r1 --tp 16 --dist-init-addr ip1:20000 --nnodes 2 --node-rank 0 --trust-remote-code --host 0.0.0.0 --port 8000

神奇的事情就自然而然的发生了，引擎一次性启动成功

并且经过测试，token的生成速度达到了31+tokens/s，较原方案大幅提升了20%+

经过一天多的使用，也没有再次出现过降速和卡顿的问题。

三、压测

从直观感受来目测系统响应速度有两个点

1. 当用户提了问题，AI给出的第一个token的延时时间，也就是常说的Time To First Token（TTFT）
2. 字符输出的速度，也就是在论文里常看到的Output Thoughput token/s

单个请求​

TTFT​

首先简单用one-api去测试一下系统的反应，首次未命中缓存时，大概在1.9s左右，后续命中缓存的情况下，降低到只有0.43秒。

针对TTFT的测试，随机生成16/256/1024/2048/4096/8192/16384/32768/65536个随机token来当做输入prompt，模拟在不同长度输入的场景下，用户能接收到的第一个字符的平均等待时间，时间越短，用户见到第一个token速度越快。

这里可以看到一个非常有趣的现象，在长度为8192个token之前的TTFT增长曲线是比较平缓的，到8192之后陡然上升，而且呈现一个很有意思的趋势，就是16384是8192的2倍，5.11接近2.94的2倍；32769是8192的4倍，11.78接近2.94的4倍；貌似是一个线性的增长关系，这个8192就是一个比较有趣的数字。

回头再看系统在启动过程中打印的日志中包含了这样一个数字，chunked_prefill_size=8192，那么大概率这里就跟这个chunked_prefill_size有关。

找Deepseek一问，便可可得知，这个参数是做显存优化用的，较小的chunk_size可以节约显存，但是没关系我们都已经有28H100了，直接拉大来提升速度就会是一个不错的优化选择，具体的优化细节我们有机会再来讨论。

Output Thoughput token/s​

上文已经提到过，单个请求的输出速度基本保持在了31-32token/s之间，肉眼可见的快速。

多请求并发​

TTFT​

这次我们使用1024个随机输入token，对模型的进行10/20/30/40/50/100并发进行测试，来看分别在不同并发量的情况下，token最大的生成速度和TTFT。

可以看到当并发请求上到超过50并发时，系统的等待时间已经超过10秒了，这时候给人的感觉已经是很慢了，再往上拉高并发数量也基本失去了意义

Output Thoughput token/s​

这块基本上就是纯属娱乐一下了

系统的最大吞吐量，当以1024个随机token输入，500并发时出现将近1192.06token/s（当然这个数据只是估算出来的，并没有太多实际的价值）

在我们使用默认参数的情况下，能看到日志中最大可以处理的请求数量为78。

这个参数在默认的时候是没有设置的，Deepseek给出的推荐值如下图所示

四、结语

在完成Deepseek-r1的部署之后，我们发现的VLLM中可能存在的潜在问题目前无法解决，随后替换成了SGLang来暂时让系统达到可用状态。

接下来对整个系统进行了一系列的测试，在测试过程中发现了很多有意思的参数设置，比如chunked_prefill_size和max_running_reuquest在不同场景下可能影响着系统的延迟和吞吐能力，这将会成为我们接下来的进行优化的目标，感谢你看到这里。

本来过年前乐乐呵呵的准备出去旅游的，Deepseek来了一波疯狂炸场，把全世界的目光都吸引了过来，这波泼天的流量也是没谁了。

年后没多久，因为一些特定的原因，官网的Deepseek基本都变成了这个状态

手上刚好有几张算力还算可以的显卡，经过一系列折腾，终于完成了完整版Deepseek-r1 671B满血版生产级的部署，本来就来详细讲一下。

本人水平有限，部署过程中对各种设备、模型、网络等内容的理解有限，还望各位高手指正

一、准备工作​

1.1 模型文件​

生产级满血版的Deepseek-r1，我们应该直奔他的原版仓库

1. huggingface的Deepseek-r1仓库地址

2. 魔塔社区(modelscope)的Deepseek-r1仓库地址

因为网络的问题，我们可以通过魔塔社区去下载可能会比较快，毕竟这个模型还是很大的。

这里可能需要澄清一下，网络上各种文章说Deepseek-r1的文件大小有600G、700G还有1T以上可能都不是非常准确。

实际在linux下载后的完整版是642G

还需要注意的是，可能大家看到的更多的是ollama官网的671b写的是404G，如下图

这个并非不准确，而是ollama提供的是一个4bit的量化版本，并非真正的满血非量化版本。

1.2 服务器/显卡​

在这里我们准备2台8 * NVIDIA H100 80GB HBM3的服务器，并且显卡之间用Nvlink进行连接。

当然如果有H200可能效果会更好，但是毕竟那玩意还是太稀有了。

按照英伟达官网安装好显卡驱动、cuda、以及nvidia-fabricmanager，这里列出我使用的版本。

显卡驱动版本：550.54.15

cuda版本：release 12.4, V12.4.131

nvidia-fabricmanager：550_550.54.15

这里值得注意的是，上述三个软件版本一定要相互匹配，不然是运行不起来的。

1.3 推理引擎​

模型、硬件都准备好了，接下来就是软件了。

在这里选择了vllm，与ollama类似，这也是一个推理引擎，但是具有更高性能的特点，社区也比较活跃，有关他的详细介绍也可以看看其他的文章。

为了简化部署和统一环境，我们只需要下载vLLM的docker镜像即可。

在两台服务器上分别执行命令

docker pull vllm/vllm-openai:v0.7.1

如果网络不太好，在阿里云上也有相应的镜像

docker pull registry.cn-hangzhou.aliyuncs.com/dongfangzan/vllm-openai:v0.7.1

到此我们所有的准备工作就都做完了，接下来就可以进入部署阶段了。

二、开始部署​

根据vllm的部署文档Distributed Inference and Serving — vLLM，我们首先要找到一个脚本用来做分布式推理。

run_cluster.sh

#!/bin/bash

# Check for minimum number of required arguments
if [ $# -lt 4 ]; then
    echo "Usage: $0 docker_image head_node_address --head|--worker path_to_hf_home [additional_args...]"
    exit 1
fi

# Assign the first three arguments and shift them away
DOCKER_IMAGE="$1"
HEAD_NODE_ADDRESS="$2"
NODE_TYPE="$3"  # Should be --head or --worker
PATH_TO_HF_HOME="$4"
shift 4

# Additional arguments are passed directly to the Docker command
ADDITIONAL_ARGS=("$@")

# Validate node type
if [ "${NODE_TYPE}" != "--head" ] && [ "${NODE_TYPE}" != "--worker" ]; then
    echo "Error: Node type must be --head or --worker"
    exit 1
fi

# Define a function to cleanup on EXIT signal
cleanup() {
    docker stop node
    docker rm node
}
trap cleanup EXIT

# Command setup for head or worker node
RAY_START_CMD="ray start --block"
if [ "${NODE_TYPE}" == "--head" ]; then
    RAY_START_CMD+=" --head --port=6379"
else
    RAY_START_CMD+=" --address=${HEAD_NODE_ADDRESS}:6379"
fi

# Run the docker command with the user specified parameters and additional arguments
docker run \
    --entrypoint /bin/bash \
    --network host \
    --name node \
    --shm-size 10.24g \
    --gpus all \
    -v "${PATH_TO_HF_HOME}:/root/.cache/huggingface" \
    "${ADDITIONAL_ARGS[@]}" \
    "${DOCKER_IMAGE}" -c "${RAY_START_CMD}"

然后在两个不同的节点上分别执行命令

# 节点1
bash run_cluster.sh \
                vllm/vllm-openai \
                ip_of_head_node \
                --head \
                /path/to/the/huggingface/home/in/this/node \
                -e VLLM_HOST_IP=ip_of_this_node
# 节点2
bash run_cluster.sh \
                vllm/vllm-openai \
                ip_of_head_node \
                --worker \
                /path/to/the/huggingface/home/in/this/node \
                -e VLLM_HOST_IP=ip_of_this_node

两个节点均完成启动之后，找到其中一个节点，使用docker exec -it node bash进入容器，这时候就可以执行vllm的启动命令了。

vllm serve /root/.cache/huggingface/hub/deepseek-ai/DeepSeek-R1 \ 
--served-model-name deepseek-r1 \
--enable-prefix-caching \
--max-model-len 32768 \
--gpu-memory-utilization 0.95 \
--tensor-parallel-size 8 \
--pipeline-parallel-size 2 \
--enable-chunked-prefill \
--max-num-batched-tokens 32768 \
--trust-remote-code \
--port 8000

如果顺利的话，在漫长的等待之后，就可以看到模型所有的safetensors被一个一个的加载起来。

这时我们再去找一个Chatbox、Open WebUI等图形化工具进行一些简单的配置，就可以对话了。

2.1 但是​

总会有但是，部署的过程肯定不会那么顺利，尤其是在多机多卡的推理场景上。

用上述脚本只能勉强把模型跑起来，跑起来之后，跟官网上那种流畅的速度比起来简直是千差万别，**基本上就是一个字一个字在蹦，**非常的慢。

我们在后台看到token的生成速度，好一点的时候可能有20+tokens/s，稍微问多一点的时候可能会掉到只有不到1tokens/s，非常的惨。

到了这里可能会怀疑为什么这么多H100还是会这么慢？

实际上这里的瓶颈已经不在于显卡的算力，即使不是16张H100而是16张4090的话，算力也不是阻碍。

搞过多机多卡训练的大佬可能就会知道，在这种场景下网络带宽才是真正限制推理速度的最大阻碍。

2.2 超高性能网络-Infiniband​

InfiniBand （以下简称IB网络）是一种专为高性能计算（HPC）和超大规模数据中心设计的网络技术，以亚微秒级超低延迟和超高带宽为核心优势。

这里的带宽，不是指家里的千兆网或者机房中的万兆网（10G/s）就那么简单，而是有接近400G/s的超高速显卡互联网络。

在保证系统上安装且启用了IB网卡的情况下，我们用命令ibdev2netdev -v可以看到IB网口的状态。

当确认了IB网络是通畅的时候，我们需要对上述的启动脚本进行修改，在两个节点上分别执行以下命令

# 节点1
bash run_cluster.sh \
                vllm/vllm-openai \
                ip_of_head_node \
                --head \
                /path/to/the/huggingface/home/in/this/node \
                -e VLLM_HOST_IP=ip_of_this_node
                --privileged -e NCCL_IB_HCA=mlx5 \
                -e NCCL_P2P_LEVEL=NVL \
                -e NCCL_IB_GID_INDEX=3 \ 
                -e NCCL_IB_DISABLE=0 \
                -e NCCL_DEBUG=INFO \
                -e NCCL_SOCKET_IFNAME=ibs1 \
                -e NCCL_NET_GDR_LEVEL=2
# 节点2
bash run_cluster.sh \
                vllm/vllm-openai \
                ip_of_head_node \
                --worker \
                /path/to/the/huggingface/home/in/this/node \
                -e VLLM_HOST_IP=ip_of_this_node \
                --privileged -e NCCL_IB_HCA=mlx5 \
                -e NCCL_P2P_LEVEL=NVL \
                -e NCCL_IB_GID_INDEX=3 \ 
                -e NCCL_IB_DISABLE=0 \
                -e NCCL_DEBUG=INFO \
                -e NCCL_SOCKET_IFNAME=ibs1 \
                -e NCCL_NET_GDR_LEVEL=2

新增的环境变量配置，主要用于启用IB网络通信，而非使用以太网进行通信，详细的每一个参数的具体含义，可以在英伟达NCCL的官方网站上找到说明。

--privileged -e NCCL_IB_HCA=mlx5 \ # 通信设备为IB网卡
-e NCCL_P2P_LEVEL=NVL \ 
-e NCCL_IB_GID_INDEX=3 \ 
-e NCCL_IB_DISABLE=0 \
-e NCCL_DEBUG=INFO \
-e NCCL_SOCKET_IFNAME=ibs1 \
-e NCCL_NET_GDR_LEVEL=2

在完成配置之后，重新启动vllm，就可以看到如下的效果了。

三、下一步​

部署到这里，我们就得到了一个跟官网不卡的时候速度类似的满血版Deepseek-r1，希望这个文档对你有所帮助。

下一步，我会对已经完成部署的模型进行压测，来探索系统的性能极限在哪里，以及如何在生产环境中何如进行进一步的性能优化，期待你的关注。

个人水平有限，有误的地方望指正

附录​

RuntimeError; Nccl error; unhandled svstem error (run with NCCL DEBUG INE for deta​

这个报错大概率是nccl配置有问题，单机多卡场景下，请按照如下思路排查

1. 请检查pytorch版本与nccl版本是否匹配？
2. nvidia-fabricmanager是否开启? systemctl status nvidia-fabricmanager
3. fabricmanager的版本与显卡驱动版本是否匹配？
4. 执行vllm的测试脚本，文档地址，以确定问题出现在哪里

设置了IB网络，输出还是很慢​

在启动脚本前加入NCCL_DEBUG=INFO，并检查是否有如下日志，最关键的就是[send] via NET/IB/0/GDRDMA，这段日志表示网络通信是通过BI网络且开启了RDMA

NCCL中的RDMA（远程直接内存访问）通过绕过操作系统内核实现GPU内存直接跨节点通信，减少数据传输延迟和CPU开销；该技术利用网卡的零拷贝能力加速多机多卡间的集体操作（如AllReduce），显著提升分布式训练的通信效率。

如果你找到的日志是[send] via NET/SOCKET，则表示网络通信是通过以太网传输的，那么这时字符输出很慢是正常的。

如果你找到的日志是[send] via NET/IB/0，则表示网络通信是通过IB网络的，但是没有开启GDRDMA技术，则会有大致5%的性能损耗（网传，未实测）。

排查思路如下：

1. 检查IB网络是否开启，并正确配置。
2. 在github上找一个代码仓库https://github.com/NVIDIA/nccl-tests，根据文档进行nccl的测试，逐一排查问题。
3. 对NCCL_IB_DISABLE、NCCL_IB_HCA等环境变量的配置进行修改并调试，NCCL的官方网站会有给你很大的帮助。
4. 对于你找到的日志是[send] via NET/IB/0，无法正确开启RDMA的场景，请关注这个文档，确认自己的系统中是否正确开启了nvidia-peermem，因为默认它是不开启的，会导致RDMA无法使用。

2017年年初，我用了半年不到的时间从170斤减到了150斤，但是自此之后的5年时间里，我的体重一直在140-150之间反复横跳再也降不下去。

我曾经十分自责的认为是自己没有毅力无法坚持，但为了身体健康，还是要寻找其他方式来帮助我减肥成功，希望这本书能帮到我，如果我可以成功，那希望这本书也能帮到大家。

写于2022-11-15

一个前提​

人体会根据你的遗传基因和体内的激素水平，对你的体重预设一个平衡的值，来保证机体可以生存下去。 想要通过节食和运动来减肥，可能会在减肥初期看到一些效果，但是长期来看，由于体内的遗传基因和激素水平没有发生改变，就会使体重回到原来的预设状态，甚至比以前更胖。

我们常见的误区​

1. 经过调查显示，通过毅力进行的节食减肥会在6个月左右的时候达到体重最轻，然后在12个月后反弹。
2. 同时运动带来的减肥效果是有限的（饮食占95%，运动可能只占5%），也就是我们常说的“管住嘴、迈开腿”并不会帮你减肥成功。
3. 过量进食并不会让你长胖，而是同节食一样，短期长胖，长期回到预设的体重。
4. 果糖和代糖也是非常糟糕的食物，会导致胰岛素水平上升，从而引发肥胖

关键问题​

1. 胰岛素是让人发胖的罪魁祸首，同时越胖的人会出现胰岛素抵抗的问题，也就是分泌同样的胰岛素，分解糖原的水平变低，从而身体会分泌更多的胰岛素，最终形成一个恶性循环。
2. 如何吃和什么时候吃是解决胰岛素抵抗的关键问题
3. 皮质醇也会导致胰岛素分泌过多，也就是说长期的心理压力越大，经常失眠，也会诱发发胖
4. 脂肪肝也会加剧胰岛素抵抗，越是脂肪肝，越容易胖

如何做​

影响体重的主要因素有两个，吃什么和什么时间吃

如何吃​

1. 减少多余糖的摄入，不加额外的糖，不吃精加工的甜品，如果实在想吃甜品，可以把水果当成甜品，不要吃零食，咖啡比想象的更健康，但不要加糖，多喝茶，可以喝骨汤
2. 减少精制谷物的摄入，如面粉和各种精加工的面包、饼干等东西。摄入完全未经加工的碳水化合物。茄子、甘蓝、菠菜、胡萝卜、西蓝花、豌豆、西红柿、芦笋、甜椒、西葫芦、花椰菜、牛油果、生菜、甜菜、黄瓜、卷心菜等都是非常健康的含碳水化合物的食物。
3. 适度摄入蛋白质，不要高蛋白饮食，很难坚持
4. 增加天然脂肪的摄入，橄榄油、黄油、椰子油和猪油，不吃深加工的，坚果和全脂牛奶都是不错的食物，牛油果非常好
5. 增加相关保护因子的摄入，膳食纤维可以减少碳水化合物对胰岛素的刺激，天然的食物中有大量膳食纤维，但在加工过程中会被去除。魔芋和醋也是很好避免胰岛素上升的东西

什么时间吃​

长期节食会导致减肥初期体重减轻后进入平台期，接着是可怕的体重反弹。胰岛素抵抗使胰岛素保持在较高水平，较高的胰岛素水平又使身体的体重设定点偏高，体重设定点过高必然会削弱减肥的努力成果，人们会觉得越来越饿，所以只调整食谱不够。间歇性禁食（24-36小时）对身体有益，通过定期禁食可以降低胰岛素水平，从而显著提升胰岛素敏感性。 间歇性禁食组受试者的胰岛素水平明显较低，胰岛素抵抗状况得以明显改善。由于间歇性禁食组出现了极低胰岛素水平阶段，减缓了胰岛素抵抗的症状，对身体健康更加有利。

禁食是指自愿在特定的时间不吃食物，但允许喝水或茶等不含热量的饮料，可以每天补充一粒多种维生素片，每天2升水，可以喝骨头汤，蔬菜汤都可以。

禁食有三种方式：

1. 24小时禁食从第一天晚餐开始直到第二天的晚餐前结束。实际上这意味着在禁食日你不吃早餐、午餐和零食，只吃一顿晚餐。从本质上来说，你从第一天晚上7点禁食到第二天晚上7点，少吃了两顿饭。也可以从第一天的早餐或午餐开始禁食。
2. 36小时禁食是指从第一天晚餐之后开始，直到第三天早餐前结束。这意味着一整天不吃早餐、午餐、晚餐和任何零食。你从第一天晚上7点禁食到第三天早上7点，少吃了三顿饭。（关于膳食方案和禁食计划，详见附录一）。

每周进行2次左右的间歇性禁食。

禁食计划​

24小时禁食方案​