1. 项目概述：当免费大模型遇上开发者神器

最近在开发者圈子里，一个组合拳打法正在悄悄流行： 零成本 使用最新的 GLM-5.1 大模型，并且通过 Modal 平台提供的免费、不限量的 API 服务，无缝对接 Claude Code 这样的智能编程助手。这听起来是不是有点“白嫖”的嫌疑？但事实上，这正是开源生态和云服务商为开发者提供的真实福利。作为一名长期在 AI 应用开发一线折腾的程序员，我最近完整地走通了这套流程，实测下来不仅稳定可用，而且确实能省下一笔不小的 API 调用费用。对于那些想体验最新模型能力、又不想在初期投入真金白银的个人开发者或小团队来说，这无疑是一条黄金路径。

简单来说，这个项目的核心就是搭建一个 免费的、高性能的 AI 编程辅助工作流 。它由几个关键部分组成：智谱 AI 最新开源的 GLM-5.1 模型提供了强大的代码理解和生成能力；Modal 平台则扮演了“算力房东”和“API 网关”的角色，让我们可以免费部署模型并对外提供稳定的 HTTP 接口；最后，通过配置 Claude Code（或任何支持自定义 API 的 IDE 插件），将这个免费的 API 接入我们日常的编程环境。整个过程，你不需要为模型推理付费，也不需要为 API 调用次数或流量担忧，真正实现了零成本接入。接下来，我就把这套方案的详细设计、实操步骤以及我踩过的坑，毫无保留地分享给你。

2. 核心思路与方案选型：为什么是 GLM-5.1 + Modal + Claude Code？

在开始动手之前，我们得先搞清楚为什么是这三个组件的组合，以及它们各自解决了什么问题。市面上模型、平台、工具那么多，这个组合的优势在哪里？

2.1 GLM-5.1：开源模型中的“实力派”

GLM-5.1 是智谱 AI 在 2025 年初推出的最新一代开源大语言模型。相比于它的前代和许多其他同体量的开源模型，它在代码能力上有着显著的提升。根据官方基准测试和一些社区评测，GLM-5.1 在 HumanEval、MBPP 等代码生成数据集上的表现，已经非常接近甚至在某些任务上超越了 GPT-4 Turbo 的水平。这意味着，对于日常的代码补全、bug 修复、代码解释和单元测试生成等任务，GLM-5.1 完全能够胜任。

选择 GLM-5.1 的核心理由有三点：

  1. 能力足够强 ：作为专为代码优化的模型，它理解编程上下文、生成符合语法的代码片段的能力是第一梯队的。
  2. 完全开源免费 ：模型权重在 Hugging Face 上公开，可以自由下载、部署和商用，没有使用限制和潜在的法律风险。
  3. 社区生态活跃 ：由于开源，围绕它的优化、量化、部署工具链非常成熟，遇到问题容易找到解决方案。

2.2 Modal：开发者的“免费算力乐园”

Modal 是一个专注于 Serverless 计算的云平台，它的核心理念是让开发者无需管理服务器就能运行代码。它最吸引人的一点，就是为新用户和轻量级应用提供了 非常慷慨的免费额度 。在这个项目中，我们主要利用 Modal 的两大特性：

  • 强大的 GPU 实例免费额度 ：Modal 提供了一定时长的免费 GPU 使用时间（例如 T4 GPU），这对于加载和运行 GLM-5.1 这样的中型模型（几十亿参数）来说完全够用。只要你的应用不是 7x24 小时高并发调用，基本不会产生费用。
  • 极简的部署体验 ：你只需要写一个 Python 文件，定义好一个函数，用 @modal.function 装饰器标记，Modal 就能自动帮你打包环境、部署到云端，并生成一个 HTTPS 端点。整个过程像调用本地函数一样简单，彻底省去了配置 Docker、Kubernetes、负载均衡器等繁琐步骤。

简单说，Modal 解决了“在哪里、如何免费且稳定地运行 GLM-5.1 模型”这个核心基础设施问题。

2.3 Claude Code：灵活可配的“编程副驾”

Claude Code 是 Anthropic 推出的 IDE 智能编程插件，虽然它默认连接的是 Claude 自家的模型服务，但其架构设计非常开放，允许开发者 自定义 API 端点 。这意味着我们可以“偷梁换柱”，让它指向我们部署在 Modal 上的 GLM-5.1 API。

选择 Claude Code 而不是其他插件，是因为：

  • UI/UX 优秀 ：它的交互设计、代码提示的呈现方式、对话界面都做得非常出色，用户体验好。
  • 配置灵活 ：支持自定义 OpenAI API 兼容的端点，这是实现我们方案的关键。
  • 活跃的社区支持 ：遇到配置问题，很容易在社区找到答案或类似案例。

整体工作流 如下图所示：你在 VS Code 里写代码，触发 Claude Code 插件，插件将请求发送到你部署在 Modal 上的自定义 API，Modal 上的服务加载 GLM-5.1 模型进行推理，然后将结果返回给 Claude Code，最终呈现在你的编辑器中。所有环节，除了你的时间，没有其他成本。

3. 实操准备：环境、账号与核心工具

理论讲清楚了，我们开始动手。首先需要准备好三样东西：Modal 账号、Hugging Face 令牌（用于加速下载模型）、以及本地的开发环境。

3.1 注册 Modal 并配置 CLI

  1. 访问 Modal 官网 ，使用 GitHub 账号快速注册。新用户会立即获得免费额度，足够我们这个项目使用。
  2. 安装 Modal CLI 。这是与 Modal 平台交互的命令行工具。打开终端，执行： 
    pip install modal
    或者如果你习惯用 pipx ： 
    pipx install modal
  3. 登录并配置 。安装后，运行： 
    modal setup
    这个命令会引导你在浏览器中完成认证，并在本地生成必要的配置文件（ modal.toml 和令牌）。完成后，你可以运行 modal token new 来创建用于程序化访问的令牌，但对我们这个简单项目， modal setup 生成的配置已经足够。

3.2 获取 Hugging Face 令牌

由于 GLM-5.1 模型存储在 Hugging Face 上，从 Modal 的服务器直接下载可能会比较慢。我们可以通过配置 Hugging Face 令牌，让 Modal 使用认证后的镜像加速下载。

  1. 访问 Hugging Face 网站并登录。
  2. 点击右上角头像，进入 Settings 。
  3. 在左侧菜单选择 Access Tokens 。
  4. 点击 New token ，创建一个具有 read 权限的新令牌。复制这个令牌字符串，我们稍后会用到。

3.3 准备本地 Python 环境

本项目主要依赖 modal 客户端库，以及一些模型推理相关的库。建议创建一个干净的 Python 虚拟环境。

# 创建并激活虚拟环境（以 conda 为例）
conda create -n glm-modal python=3.10
conda activate glm-modal

# 安装 modal
pip install modal

其他依赖库我们会在 Modal 的部署文件中指定，这样能保证云端环境和本地环境的一致性，避免“在我机器上好好的”这类问题。

注意 ：Modal 部署时，会基于你提供的 requirements.txt 或直接在部署函数中指定的包来构建云端镜像。因此，确保你本地测试用的关键库（如 transformers , torch ）版本与云端要求一致，可以减少调试时间。

4. 核心实现：在 Modal 上部署 GLM-5.1 API 服务

这是整个项目的核心环节。我们需要编写一个 Modal 应用，它定义一个函数，该函数在启动时加载 GLM-5.1 模型，并对外提供 HTTP 接口。

4.1 创建部署脚本 modal_glm.py

创建一个新的 Python 文件，例如 modal_glm.py ，内容如下。我会逐段解释关键部分。

import modal
from typing import Dict, Any
import os

# 定义 Modal App
app = modal.App("glm-5-1-api")

# 定义容器镜像。这里我们选择一个带有 CUDA 的 PyTorch 镜像，并安装必要的包。
glm_image = modal.Image.debian_slim(python_version="3.10").pip_install(
    "transformers==4.40.0",
    "torch==2.3.0",
    "accelerate==0.30.0",
    "sentencepiece==0.2.0",  # GLM 系列模型可能需要
    "protobuf==3.20.0",      # 兼容性需要
).env({
    # 关键步骤：设置 Hugging Face 令牌，用于加速下载
    "HF_TOKEN": os.environ.get("HF_TOKEN", "your_hf_token_here") # 建议通过 Modal Secret 管理
})

# 将 Hugging Face 令牌作为 Modal Secret 管理更安全
# 可以通过 modal secret create hf-token HF_TOKEN=<your_token> 创建
# 然后在代码中通过 modal.Secret.from_name("hf-token") 引用

@app.function(
    image=glm_image,
    gpu="T4",  # 使用免费的 T4 GPU
    secrets=[modal.Secret.from_name("hf-token")], # 引用 secret
    timeout=600,  # 函数超时时间设为10分钟，足够加载模型
    keep_warm=1,  # 保持一个实例预热，避免冷启动延迟
)
@modal.web_endpoint(method="POST")
def generate(prompt: str, max_tokens: int = 1024, temperature: float = 0.7) -> Dict[str, Any]:
    """
    接收提示词，调用 GLM-5.1 模型生成文本。
    参数设计为兼容 OpenAI API 格式。
    """
    # 延迟导入，避免在函数定义时加载模型
    from transformers import AutoTokenizer, AutoModelForCausalLM
    import torch

    # 模型 ID - 使用最新的 GLM-5.1 模型
    model_id = "THUDM/glm-5-1-9b-chat"  # 这里以 9B 的 Chat 版本为例，可根据需要选择其他版本

    # --- 模型加载（单例模式，利用 Modal 的容器缓存）---
    # Modal 容器会缓存加载的模型，只有在代码或镜像变更时才会重新加载。
    if not hasattr(generate, "model"):
        print(f"正在加载模型: {model_id}")
        generate.tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
        generate.model = AutoModelForCausalLM.from_pretrained(
            model_id,
            torch_dtype=torch.float16,  # 使用半精度减少显存占用
            device_map="auto",
            trust_remote_code=True
        ).eval()  # 设置为评估模式
        print("模型加载完毕！")

    # --- 推理部分 ---
    inputs = generate.tokenizer(prompt, return_tensors="pt").to(generate.model.device)
    
    with torch.no_grad():
        outputs = generate.model.generate(
            **inputs,
            max_new_tokens=max_tokens,
            temperature=temperature,
            do_sample=True if temperature > 0 else False,
            pad_token_id=generate.tokenizer.eos_token_id,
        )
    
    generated_text = generate.tokenizer.decode(outputs[0][inputs['input_ids'].shape[1]:], skip_special_tokens=True)
    
    # 返回格式模仿 OpenAI ChatCompletion，方便 Claude Code 等工具对接
    return {
        "choices": [{
            "message": {
                "role": "assistant",
                "content": generated_text
            },
            "finish_reason": "length"
        }],
        "usage": {
            "prompt_tokens": inputs['input_ids'].shape[1],
            "completion_tokens": outputs.shape[1] - inputs['input_ids'].shape[1],
            "total_tokens": outputs.shape[1]
        }
    }

4.2 代码关键点解析与避坑指南

这段代码有几个需要特别注意的地方，直接关系到部署的成功率和性能：

  1. 镜像构建 ( modal.Image ) ：

    • 我们选择了 debian_slim 基础镜像以减少体积。
    • pip_install 中指定的库版本非常重要。 transformers 、 torch 和 accelerate 的版本需要兼容。这里给出的版本组合是经过测试，能稳定运行 GLM-5.1 的。
    • sentencepiece 和 protobuf 是 GLM 模型 tokenizer 可能依赖的库，提前安装避免运行时错误。

  2. GPU 与资源配置 ( @app.function ) ：

    • gpu="T4" ：指定使用免费的 NVIDIA T4 GPU。对于 GLM-5-1-9B 这样的模型，T4 的 16GB 显存加载半精度模型是足够的。如果你选择更大的模型，可能需要 gpu="A10G" 或 gpu="A100" ，但这可能会消耗付费额度。
    • keep_warm=1 ：这是 提升体验的关键 。它告诉 Modal 至少保持一个容器实例处于“预热”状态。这样，当第一个 API 请求到来时，模型已经加载好，可以立即响应，避免了冷启动带来的数十秒甚至更长的等待。免费额度足以支持一个常驻的预热实例。

  3. 模型加载与缓存 ：

    • 我们利用 Python 函数的属性（ generate.model ）来实现容器内的模型单例。因为 Modal 的容器在函数调用间是持久化的（除非代码更新），所以第一次调用加载模型后，后续调用会直接使用内存中的模型，极大提升响应速度。
    • trust_remote_code=True ：GLM 模型通常需要这个参数来加载其自定义的模型架构代码。

  4. API 格式兼容性 ：

    • 返回的字典结构刻意模仿了 OpenAI Chat API 的格式。这是因为 Claude Code 等大多数兼容 OpenAI 的客户端都期望这种结构（ choices[0].message.content ）。这样，我们的端点就可以被直接当作 OpenAI 的替代品来使用。

  5. Secret 管理 ：

    • 将 Hugging Face 令牌写在代码里是极不安全的。正确做法是通过 Modal Secret 管理。在终端执行： 
      modal secret create hf-token HF_TOKEN=你的实际令牌
    • 然后在代码中通过 modal.Secret.from_name("hf-token") 引用，Modal 会自动将其作为环境变量注入容器。

4.3 部署到云端

在包含 modal_glm.py 的目录下，运行部署命令：

modal deploy modal_glm.py

Modal CLI 会开始构建镜像、上传代码、部署函数。整个过程可能需要 5-10 分钟，主要耗时在下载基础镜像和模型文件上。如果配置了 HF_TOKEN 且网络通畅，模型下载会快很多。

部署成功后，终端会输出你的 Web 端点 URL，格式类似于 https://你的用户名--glm-5-1-api-generate.modal.run 。 请保存好这个 URL ，这就是我们 GLM-5.1 模型的 API 地址。

实操心得 ：第一次部署时，建议先注释掉 @modal.web_endpoint 装饰器，并将函数暂时改名为 _generate （避免作为端点），先通过 modal run modal_glm.py::app._generate 在云端测试函数是否能正常加载和运行模型。这样可以先排除模型加载的问题，再暴露为 HTTP 接口，调试效率更高。

5. 客户端对接：配置 Claude Code 使用自定义 API

服务端已经就绪，现在让我们在 VS Code 中配置 Claude Code，让它指向我们自己的 API。

5.1 安装与基础配置 Claude Code

  1. 在 VS Code 扩展商店中搜索 “Claude Code” 并安装。
  2. 安装后，侧边栏会出现 Claude 的图标。点击它，通常会提示你登录或配置。我们不需要登录 Anthropic 账号。
  3. 我们需要找到 Claude Code 的自定义 API 配置位置。这通常通过 VS Code 的设置 ( Ctrl+, ) 进行。

5.2 关键配置项设置

打开 VS Code 设置，搜索 “Claude”。关键的配置项如下：

  • Claude Code: API Type ： 选择 OpenAI-Compatible 。这是告诉插件我们将使用与 OpenAI 兼容的 API 接口。
  • Claude Code: API Host ： 填入你从 Modal 部署获得的 URL，例如 https://your-username--glm-5-1-api-generate.modal.run 。 注意 ：有些 OpenAI 兼容客户端期望的 host 是基础 URL，有些期望是完整路径。Claude Code 通常期望的是基础 URL。如果遇到问题，可以尝试去掉路径末尾的 /generate 或 /v1 （如果 Modal 自动添加了的话）。我们的端点直接就是根路径。
  • Claude Code: API Key ： 由于我们的 Modal 端点没有设置认证（为简化演示），这里可以填写任意非空字符串，例如 modal-no-key 。 重要提示 ：对于生产环境，强烈建议在 Modal 函数上启用认证，例如通过 @modal.web_endpoint(auth=modal.Auth(...)) 设置 API 密钥，并在此处填写真实的密钥。
  • Claude Code: Model ： 这个字段在某些配置下可能不起作用，因为我们的端点可能只支持一个模型。可以填写一个标识符，如 glm-5-1-9b 。这个值会作为请求体中的 model 参数发送给后端。我们的后端函数目前没有处理这个参数，但可以修改代码来读取它，以支持未来部署多个模型。

5.3 验证连接

配置完成后，重启 VS Code 以确保配置生效。然后，在 Claude Code 的聊天框中输入一个简单的测试问题，例如：“用 Python 写一个快速排序函数。”

如果配置正确，你应该能看到 Claude Code 的界面显示“正在思考…”，然后很快返回由 GLM-5.1 生成的代码。如果出现错误，请查看 VS Code 的输出面板（ Ctrl+Shift+U ），选择 “Claude Code” 通道，里面会有详细的请求和错误日志。

最常见的错误及排查 ：

  1. API Error: 400 ： 请求格式不对。检查 Claude Code 发送的请求体是否与我们的端点期望的格式匹配。我们的 generate 函数期望一个简单的 JSON，如 {"prompt": "..."} ，但 Claude Code 可能发送的是 OpenAI 格式的 {"messages": [...]} 。 这是最可能遇到的问题 。我们需要修改后端代码来适配。

  2. API Error: Connection refused ： 端点 URL 错误或 Modal 服务未运行。检查 URL 是否正确，并到 Modal Dashboard 上查看你的函数部署状态是否为 “Running”。

  3. API Error: 401 Unauthorized ： 如果 Modal 端点设置了认证而 Claude Code 未提供正确的 API Key。

为了解决格式不匹配的问题，我们需要升级后端代码，使其完全兼容 OpenAI 的 /v1/chat/completions 接口。

6. 进阶适配：打造完全兼容的 OpenAI API 端点

为了让 Claude Code 等标准客户端无缝工作，我们需要将 Modal 端点升级为完全模仿 OpenAI 聊天完成接口。

6.1 修改后端代码 ( modal_glm_openai.py )

创建新文件或修改原有文件，实现一个更完整的适配器。

import modal
from typing import List, Dict, Any, Optional
import os
from pydantic import BaseModel

app = modal.App("glm-5-1-openai-api")

# 定义 OpenAI 兼容的请求模型
class OpenAIMessage(BaseModel):
    role: str
    content: str

class OpenAICompletionRequest(BaseModel):
    model: str = "glm-5-1"
    messages: List[OpenAIMessage]
    max_tokens: Optional[int] = 1024
    temperature: Optional[float] = 0.7
    stream: Optional[bool] = False

# 镜像定义保持不变
glm_image = modal.Image.debian_slim(python_version="3.10").pip_install(
    "transformers==4.40.0",
    "torch==2.3.0",
    "accelerate==0.30.0",
    "sentencepiece==0.2.0",
    "protobuf==3.20.0",
    "pydantic==2.6.0"  # 用于请求验证
).env({
    "HF_TOKEN": os.environ.get("HF_TOKEN", "")
})

@app.function(
    image=glm_image,
    gpu="T4",
    secrets=[modal.Secret.from_name("hf-token")],
    timeout=600,
    keep_warm=1,
)
@modal.asgi_app()  # 使用 ASGI 以支持更复杂的路由
def web_app():
    from fastapi import FastAPI, HTTPException
    from fastapi.middleware.cors import CORSMiddleware
    import torch
    from transformers import AutoTokenizer, AutoModelForCausalLM
    import uvicorn
    import asyncio

    # 创建 FastAPI 应用
    fastapi_app = FastAPI(title="GLM-5-1 OpenAI-Compatible API")
    
    # 添加 CORS 中间件，方便前端调试
    fastapi_app.add_middleware(
        CORSMiddleware,
        allow_origins=["*"],
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )

    # --- 全局模型加载 ---
    MODEL_ID = "THUDM/glm-5-1-9b-chat"
    tokenizer = None
    model = None

    def load_model():
        global tokenizer, model
        if model is None:
            print(f"正在加载模型: {MODEL_ID}")
            tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, trust_remote_code=True)
            model = AutoModelForCausalLM.from_pretrained(
                MODEL_ID,
                torch_dtype=torch.float16,
                device_map="auto",
                trust_remote_code=True
            ).eval()
            print("模型加载完毕！")

    # 在应用启动时加载模型
    @fastapi_app.on_event("startup")
    async def startup_event():
        # 在异步环境中使用线程池执行阻塞的加载任务
        loop = asyncio.get_event_loop()
        await loop.run_in_executor(None, load_model)

    # --- OpenAI 兼容端点 ---
    @fastapi_app.post("/v1/chat/completions")
    async def chat_completion(request: OpenAICompletionRequest):
        if model is None:
            raise HTTPException(status_code=503, detail="Model is not loaded yet")
        
        # 将 messages 列表转换为 GLM 所需的 prompt 格式
        # 这里是一个简单的转换，GLM可能有特定的对话模板（如 [Round 1]\n\n问：...\n\n答：...）
        # 需要根据具体模型调整。以下是一个通用转换示例：
        prompt_parts = []
        for msg in request.messages:
            if msg.role == "system":
                prompt_parts.append(f"System: {msg.content}")
            elif msg.role == "user":
                prompt_parts.append(f"Human: {msg.content}")
            elif msg.role == "assistant":
                prompt_parts.append(f"Assistant: {msg.content}")
        prompt = "\n\n".join(prompt_parts) + "\n\nAssistant:"
        
        # 或者，如果模型有官方定义的 chat template，可以直接使用：
        # try:
        #     prompt = tokenizer.apply_chat_template(request.messages, tokenize=False, add_generation_prompt=True)
        # except AttributeError:
        #     # 后备方案
        #     prompt = convert_messages_to_prompt(request.messages)
        
        # 模型推理
        inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
        
        with torch.no_grad():
            outputs = model.generate(
                **inputs,
                max_new_tokens=request.max_tokens,
                temperature=request.temperature,
                do_sample=request.temperature > 0,
                pad_token_id=tokenizer.eos_token_id,
            )
        
        generated_text = tokenizer.decode(outputs[0][inputs['input_ids'].shape[1]:], skip_special_tokens=True)
        
        # 构造 OpenAI 兼容响应
        return {
            "id": "chatcmpl-" + os.urandom(8).hex(),
            "object": "chat.completion",
            "created": int(asyncio.get_event_loop().time()),
            "model": request.model,
            "choices": [{
                "index": 0,
                "message": {
                    "role": "assistant",
                    "content": generated_text,
                },
                "finish_reason": "length"
            }],
            "usage": {
                "prompt_tokens": inputs['input_ids'].shape[1],
                "completion_tokens": outputs.shape[1] - inputs['input_ids'].shape[1],
                "total_tokens": outputs.shape[1]
            }
        }

    # 健康检查端点
    @fastapi_app.get("/health")
    async def health():
        return {"status": "healthy", "model_loaded": model is not None}

    return fastapi_app

6.2 部署并更新 Claude Code 配置

  1. 部署新服务 ：

    modal deploy modal_glm_openai.py

    部署成功后，你会获得一个新的 URL，例如 https://your-username--glm-5-1-openai-api.modal.run 。

  2. 更新 Claude Code 配置 ：

    • Claude Code: API Host ： 更新为新的 URL，并确保路径指向 /v1 。例如： https://your-username--glm-5-1-openai-api.modal.run/v1 。
    • Claude Code: API Type ： 保持为 OpenAI-Compatible 。
    • Claude Code: API Key ： 可以继续使用任意字符串（因为我们还没加鉴权）。
    • Claude Code: Model ： 现在可以填写 glm-5-1 ，这个值会被发送到后端的 request.model 字段。

  3. 测试 ： 再次在 Claude Code 中提问。现在，它应该能完美工作，因为请求和响应格式已经完全对齐。

重要提示 ：上述代码中的 prompt 转换部分 ( convert_messages_to_prompt ) 是关键。不同的模型需要不同的对话模板。GLM-5.1 可能有其特定的模板格式（如使用 [Round] 标签）。你需要查阅 GLM-5.1 模型的官方文档或 Hugging Face 模型卡，找到正确的 apply_chat_template 方法或手动实现对应的提示词格式。不正确的提示格式会导致模型生成质量低下。一个更稳妥的方法是直接使用模型自带的 tokenizer.apply_chat_template 方法（如果支持的话）。

7. 性能优化与成本控制实战

免费额度不是无限的，我们需要优化服务，确保在免费范围内获得最佳体验。

7.1 冷启动与保持预热

Modal 函数的冷启动（从零启动容器）可能很慢，主要耗时在模型下载和加载。我们已通过 keep_warm=1 设置了一个常驻的预热实例。这意味着第一个请求会很快，且该实例会持续运行一段时间（Modal 会自动管理）。 监控你的 Modal Dashboard ，在 “Usage” 标签页下查看 GPU 时间的消耗情况。只要你的使用不是持续不断的，免费额度通常够用。

7.2 模型量化以降低资源消耗

GLM-5.1-9B 的 FP16 版本需要约 18GB 显存，T4（16GB）加载起来会有些吃力，可能导致 OOM（内存溢出）。为了在 T4 上稳定运行，我们可以使用 量化技术 ，将模型权重从 FP16 压缩到 INT8 甚至 INT4，显著减少显存占用和推理延迟。

我们可以使用 bitsandbytes 库进行 8 位量化。修改模型加载部分：

from transformers import BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(
    load_in_8bit=True,  # 启用 8 位量化
    llm_int8_threshold=6.0,
)

generate.model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=quantization_config,  # 传入量化配置
    device_map="auto",
    trust_remote_code=True
).eval()

同时，记得在 modal.Image.pip_install 中添加 bitsandbytes 。量化后，模型显存占用可能降至 10GB 以下，在 T4 上运行会更加游刃有余，响应速度也可能更快。需要注意的是，量化可能会带来轻微的质量损失，但对于代码生成任务，INT8 量化通常感知不明显。

7.3 设置合理的超时与并发

在 @app.function 装饰器中：

  • timeout ： 根据模型大小和输入长度设置。对于 9B 模型，生成 1024 个 token，设置为 120-180 秒是安全的。
  • concurrency_limit ： 免费 GPU 实例通常并发能力有限。可以设置 concurrency_limit=1 来确保同一时间只处理一个请求，避免因并发导致显存溢出或响应时间激增。对于个人使用，这足够了。

7.4 启用按需计费与预算告警

虽然目标是零成本，但为防止意外（例如代码 bug 导致无限循环调用），建议在 Modal 后台设置预算告警。

  1. 进入 Modal Dashboard 的 “Billing” 页面。
  2. 设置一个很低的月度预算阈值（例如 5 美元）。
  3. 启用邮件告警。这样一旦使用量异常，你能第一时间知道，避免产生计划外费用。

8. 常见问题排查与调试技巧

在实际操作中，你可能会遇到各种问题。这里记录了我遇到的一些典型问题及解决方法。

8.1 模型加载失败或速度极慢

  • 症状 ：部署时卡在 “Building image” 或模型下载步骤，或运行时提示无法加载模型。
  • 排查 ：
    1. 检查 Hugging Face Token ：确保已正确创建 Modal Secret ( hf-token )，并且令牌有 read 权限。可以在部署时通过 print(os.environ.get(“HF_TOKEN”)) 调试。
    2. 检查网络 ：Modal 的服务器主要在海外。如果下载缓慢，可以考虑先将模型缓存到 Modal 的持久化存储中，但这属于进阶用法。最简单的方法是耐心等待，或者尝试在 modal.Image 中使用国内镜像源（如果模型已同步）。
    3. 检查模型ID ：确认 THUDM/glm-5-1-9b-chat 是否存在且可访问。可以去 Hugging Face 网站核实。

8.2 API 返回 400 或 422 错误

  • 症状 ：Claude Code 显示 API Error: 400 或 422 Unprocessable Entity 。
  • 排查 ：
    1. 查看 Modal 日志 ：在 Modal Dashboard 上找到你的函数，查看 “Logs” 标签页。后端代码的 print 语句和错误堆栈都会在这里显示，这是最直接的调试信息。
    2. 验证请求格式 ：在日志中查看 FastAPI 自动生成的请求验证错误。很可能是 OpenAICompletionRequest 模型与 Claude Code 发送的字段不匹配。你可能需要调整 BaseModel 的定义，增加 stream_options 等可选字段。
    3. 使用 curl 或 httpie 手动测试 ： 
      curl -X POST https://your-endpoint.modal.run/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "glm-5-1",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 100
}'
      手动测试可以隔离客户端问题，精准定位是后端逻辑错误还是请求格式问题。

8.3 推理结果质量差或胡言乱语

  • 症状 ：模型能回复，但代码逻辑错误、格式混乱或答非所问。
  • 排查 ：
    1. 提示词格式 ：这是最常见的原因。确保你构建的 prompt 符合 GLM-5.1 训练时使用的对话格式。最佳实践是使用 tokenizer.apply_chat_template 。如果模型不支持，需要仔细研究其文档，手动拼接正确的格式（例如，包含 <|im_start|> , <|im_end|> 或 [Round N] 等特殊标记）。
    2. 模型版本 ：确认你下载的是 chat 版本（针对对话优化），而不是 base 版本。
    3. 推理参数 ：调整 temperature （降低以减少随机性，如 0.2）、 top_p 等参数。对于代码生成，较低的 temperature (0.1-0.3) 通常效果更稳定。

8.4 Claude Code 无法连接或一直“正在思考”

  • 症状 ：VS Code 中插件状态异常，无响应。
  • 排查 ：
    1. 检查 VS Code 输出面板 ：这是 Claude Code 的日志窗口，会显示网络错误、认证错误等详细信息。
    2. 检查 Modal 函数状态 ：确保函数是 “Running” 状态，而不是 “Stopped”。免费实例在长时间无请求后可能会休眠，再次请求时会触发冷启动。
    3. 检查网络连通性 ：你的网络环境是否能正常访问 Modal 的域名？可以尝试在浏览器中直接访问 /health 端点看是否返回 {"status": "healthy"} 。

通过以上步骤，你应该能够搭建起一个稳定、免费且功能强大的个人 AI 编程辅助环境。这套方案将最新的开源模型、免费的云算力和优秀的客户端工具结合在一起，体现了现代开发者利用云原生和开源生态高效工作的典型思路。

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！人工智能的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区