🚀 Vercel AI SDK 使用指南：模型设置 (Settings)

在构建 AI 应用时，仅仅能够"调用"模型是不够的。为了让 LLM（大语言模型）不仅能"跑通"，还能"跑好"，我们需要精准地控制它的输出行为、响应时间以及容错机制。

Vercel AI SDK Core 提供了一套强大的标准设置（Settings） ，无论你使用的是 OpenAI、Anthropic 还是国内的智谱 AI (GLM) ，都可以通过这套统一的 API 来微调模型表现。

本文将基于最新的 Vercel AI SDK Core 文档，结合智谱 AI 最新发布的 GLM-5 模型 ，带你深入挖掘 generateText 和 streamText 中的关键配置项。

🛠️ 前置准备：接入智谱 GLM-5

智谱 GLM-5 是刚发布的旗舰模型，具备强大的系统工程和 Agent 能力。在 Vercel AI SDK 中，我们可以通过 OpenAI 兼容模式轻松接入。

首先，安装必要的依赖：

Bash

npm install ai @ai-sdk/openai dotenv

然后，配置智谱的 Provider。由于智谱兼容 OpenAI 协议，我们可以直接使用 createOpenAI 并指定 baseURL：

TypeScript

// src/ai.ts
import { createOpenAI } from '@ai-sdk/openai';
import 'dotenv/config';

// 创建智谱 AI 实例
export const zhipu = createOpenAI({
  apiKey: process.env.ZHIPU_API_KEY, // 在 .env 中设置你的 API Key
  baseURL: 'https://open.bigmodel.cn/api/paas/v4', // 智谱官方兼容端点
});

// 指定最新模型 GLM-5
export const model = zhipu('glm-5');

注意 ：请确保你的 .env 文件中包含 ZHIPU_API_KEY=你的API_KEY。

---

🎛️ 核心生成参数 (Generation Settings)

这部分设置直接决定了"模型会说什么"以及"怎么说"。

1. 创造性控制：Temperature 与 Top-P

这是最常用的两个参数，用于平衡模型的"严谨性"与"创造性"。

• temperature (0.0 - 1.0+) : 控制输出的随机性。

  • 0: 极度严谨，适合代码生成、数据提取。
  • 0.7 - 1.0: 适合通用对话、创意写作。

• topP (0.0 - 1.0) : 核采样 (Nucleus Sampling)。限制模型仅从累积概率达到 P 的 Token 集合中选择。

最佳实践：通常建议只调整其中一个，不要同时调整。在 Vercel AI SDK 5.0+ 中，默认 temperature 不再是 0，建议显式设置。

TypeScript

import { generateText } from 'ai';
import { model } from './ai';

const result = await generateText({
  model,
  prompt: '给一款赛博朋克风格的咖啡饮料起3个创意名字',
  // 高 temperature 激发创意
  temperature: 0.9, 
});

console.log(result.text);

2. 输出长度与停止词：MaxOutputTokens & StopSequences

防止模型"废话连篇"或生成你不想要的内容。

• maxOutputTokens: 强制限制生成的最大 Token 数。
• stopSequences: 当模型生成特定的字符串时立即停止（不包含该字符串）。

TypeScript

const result = await generateText({
  model,
  prompt: '写一个 Python Hello World 函数',
  // 限制输出长度
  maxOutputTokens: 100, 
  // 当模型试图开始写解释时停止（假设它在代码块后会换行写解释）
  stopSequences: ['```\nExplanation:'], 
});

3. 避免复读机：Presence & Frequency Penalty

如果你的模型陷入了重复循环，可以通过这两个参数进行惩罚。

• frequencyPenalty : 惩罚多次出现的词（降低词频）。
• presencePenalty : 惩罚已经出现过的词（鼓励讲新话题）。

TypeScript

const result = await generateText({
  model,
  prompt: '列出10个完全不同的创意营销方案，不要重复',
  // 强力惩罚重复内容
  frequencyPenalty: 0.5,
  presencePenalty: 0.5,
});

---

🛡️ 请求与工程化配置 (Request Options)

这部分设置关乎应用的稳定性、性能和用户体验，是生产环境不可或缺的。

1. 智能重试：MaxRetries

网络波动是常态。AI SDK 默认会重试 2 次。你可以根据业务重要性调整。

TypeScript

const result = await generateText({
  model,
  prompt: '提取这份财报中的关键数据...',
  // 关键任务，增加重试次数
  maxRetries: 5, 
});

2. 精细化超时控制：Timeout

Vercel AI SDK 提供了非常灵活的超时策略，支持数字（总时长）或对象配置。

• totalMs: 整个调用的总超时时间。
• stepMs: 单次 LLM 推理步骤的超时（适合多步 Agent）。
• chunkMs : 流式传输中，两个数据块之间的最大间隔（检测卡死的神器）。

场景：防止流式响应卡死

TypeScript

import { streamText } from 'ai';

const { textStream } = streamText({
  model,
  prompt: '用 GLM-5 详细解释量子纠缠，写一篇 2000 字的文章',
  timeout: {
    // 如果 5 秒内没有收到新的文字块，就自动断开，防止用户一直空等
    chunkMs: 5000, 
    // 整个任务最长允许运行 60 秒
    totalMs: 60000, 
  },
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}

3. 随时取消：AbortSignal

在前端 UI 中，用户可能会点击"停止生成"按钮。你需要通过 abortSignal 将这个信号传递给后端。

TypeScript

// 模拟一个 AbortController（通常在前端组件中创建）
const controller = new AbortController();

// 3秒后模拟用户点击取消
setTimeout(() => controller.abort(), 3000);

try {
  const result = await generateText({
    model,
    prompt: '生成一个非常复杂的 SQL 查询...',
    // 传入信号，一旦 controller.abort() 被调用，请求会立即终止
    abortSignal: controller.signal, 
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('用户取消了生成');
  }
}

4. 自定义 Headers

智谱 GLM-5 或其他模型可能支持特定的 Header（例如用于追踪调试的 Trace-Id）。

TypeScript

const result = await generateText({
  model,
  prompt: '你好，GLM-5',
  headers: {
    'X-Custom-Trace-ID': 'user-123-session-abc',
    'X-App-Source': 'juejin-tutorial',
  },
});

---

🚀 实战代码：构建一个稳健的 GLM-5 翻译器

下面我们将所有知识点结合，编写一个生产可用的翻译脚本。它具备自动重试 、超时保护 和参数微调功能。

TypeScript

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
import 'dotenv/config';

// 1. 初始化智谱 Provider
const zhipu = createOpenAI({
  apiKey: process.env.ZHIPU_API_KEY,
  baseURL: 'https://open.bigmodel.cn/api/paas/v4',
});

async function robustTranslate(text: string) {
  console.log(`🚀 正在使用 GLM-5 翻译: "${text.substring(0, 10)}..."`);

  try {
    const { text: translatedText, usage } = await generateText({
      // 2. 指定模型 GLM-5
      model: zhipu('glm-5'), 
      
      // System Prompt 设定角色
      system: '你是一位精通中英互译的资深翻译家，信达雅是你的准则。',
      prompt: `请翻译以下内容：\n"${text}"`,

      // 3. 生成参数：低温度保证准确性
      temperature: 0.1, 
      maxOutputTokens: 2000,

      // 4. 工程参数：超时与重试
      maxRetries: 3, // 失败自动重试3次
      timeout: {
        stepMs: 15000, // 每一步推理最多15秒
      },
      
      // 5. 注入追踪 Header
      headers: {
        'X-Task-Type': 'translation-job'
      }
    });

    console.log('\n✅ 翻译结果：');
    console.log(translatedText);
    console.log(`\n📊 消耗 Token: ${usage.totalTokens}`);

  } catch (error) {
    console.error('❌ 翻译任务失败:', error);
  }
}

// 运行示例
robustTranslate('Vercel AI SDK Core is a library for building AI-powered applications with React, Svelte, Vue, and Solid.');

总结

Vercel AI SDK 的 Settings 设计非常精炼，它将不同模型的差异抹平，让我们能用一套标准化的参数（如 temperature, timeout, maxRetries）来控制智谱 GLM-5 等任何模型。

掌握这些设置，你的 AI 应用将从单纯的"能对话"进化为"可控、可靠、生产即用"的系统。

---

📚 参考文档：

• Vercel AI SDK Core Settings
• 智谱 AI 开放平台