Modal 免费 $30 循环额度申请与自建 API 教程

Modal 没有提供现成的模型名和 API Key，你要做的是把一个推理服务部署上去，拿到属于自己的调用地址。整个链路分为写部署脚本、部署上线、调用测试三步。

一、安装客户端并登录

本地安装 Modal 的 Python 客户端，然后用浏览器授权完成登录，凭证会写入本机配置目录。

pip install modal
modal setup

二、部署一个 OpenAI 兼容服务

推荐用 vLLM 或 SGLang 的官方镜像部署开源模型，下面是部署 vLLM 的示意脚本，模型名与显存配置按你选的模型调整，具体可用 GPU 型号与价格以控制台实际显示为准。

import modal

app = modal.App("vllm-server")

@app.function(
    gpu="A10G",
    timeout=3600,
    image=modal.Image.debian_slim().pip_install("vllm"),
)
@modal.web_server(port=8000)
def serve():
    import subprocess
    subprocess.Popen([
        "python", "-m", "vllm.entrypoints.openai.api_server",
        "--model", "Qwen/Qwen2.5-7B-Instruct",
        "--host", "0.0.0.0",
        "--port", "8000",
    ])

执行 modal deploy 后，控制台会返回一个以 https:// 开头、以 .modal.run 结尾的公网地址。base_url 就是在该地址后拼接 /v1，例如 https://你的工作区名--vllm-server-serve.modal.run/v1。

三、发起一次对话补全调用

vLLM 提供的接口与 OpenAI 兼容，服务端不校验密钥时 api_key 填任意非空字符串即可。关键参数说明：model 必须与部署时 --model 指定的名称完全一致；messages 是角色与内容组成的数组；max_tokens 控制输出长度；temperature 控制随机性。

curl https://你的工作区名--vllm-server-serve.modal.run/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dummy-key" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "用一句话解释什么是无服务器 GPU"}],
    "max_tokens": 256,
    "temperature": 0.7
  }'

四、额度耗尽与限流的典型表现

• 额度耗尽：新任务启动卡在排队或被直接拒绝，账单页显示当月赠送额度为 0，此时若已绑卡会转为按量扣费。
• 冷启动超时：首次请求可能等待数十秒到几分钟，日志里能看到容器拉取镜像和加载权重，属于正常现象，不是额度问题。
• 限流或 429：请求过于密集时接口返回 429，需要降低并发或在部署脚本里设置 container_idle_timeout 与并发上限。

排查顺序：先看控制台账单页的额度余额与扣费记录，再打开该次运行的日志检查服务是否成功监听 8000 端口，然后用 curl 直接访问 base_url 加 /models 确认服务存活，最后再怀疑 model 名称写错或请求体格式不合法。