🚀 Vercel AI SDK 使用指南： 提示词工程 (Prompt Engineering)

在构建基于 LLM 的应用时，Prompt Engineering（提示词工程） 不仅仅是写出漂亮的文案，更是确保模型能够准确调用工具（Tools）、输出结构化数据（Structured Data）的关键。

本文基于 Vercel AI SDK Core 官方文档，结合 智谱 AI 最新的 GLM-5 模型，为你详解如何在 Vercel AI SDK 中通过代码层面的优化，大幅提升 AI 应用的稳定性和准确性。

---

🛠️ 前置准备

由于 GLM-5 是刚刚发布的最新模型，为了确保能够第一时间调用（无需等待社区 Provider 更新），我们将使用 Vercel AI SDK 的 openai 兼容模式来直接连接智谱 API。

1. 安装依赖

Bash

npm install ai @ai-sdk/openai zod dotenv

2. 配置环境变量 (.env)

你需要前往 智谱 AI 开放平台 获取 API Key。

代码段

ZHIPU_API_KEY=your_zhipu_api_key_here

3. 初始化 GLM-5 模型实例

创建一个 utils.ts 或 model.ts 文件：

TypeScript

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

// 使用 createOpenAI 创建智谱专用实例
const zhipu = createOpenAI({
  baseURL: 'https://open.bigmodel.cn/api/paas/v4',
  apiKey: process.env.ZHIPU_API_KEY,
});

// 导出 GLM-5 模型
export const model = zhipu('glm-5');

---

💡 提示词工程最佳实践 (Prompt Engineering Tips)

在使用 generateText 或 streamText 进行工具调用时，遵循以下原则可以让 GLM-5 的表现更上一层楼。

1. 保持工具简单且语义清晰

模型对工具的理解很大程度上依赖于你定义的 名字（Name） 和 描述（Description） 。

• 数量限制 ：尽量将单次交互的工具数量控制在 5 个以内。
• 参数简化：避免过于复杂的嵌套 Zod Schema。
• 使用 .describe() ：这是最重要的！为每一个字段添加 .describe("...")，告诉模型这个参数的具体含义。

❌ 糟糕的写法：

TypeScript

const myTool = tool({
  description: 'Get data',
  parameters: z.object({
    d: z.string(), // ❌ 模型不知道 'd' 是什么
    q: z.string().optional(),
  }),
  execute: async () => { ... },
});

✅ 推荐的写法 (GLM-5 友好型)：

TypeScript

const weatherTool = tool({
  description: '获取指定城市的实时天气信息', // ✅ 清晰的工具描述
  parameters: z.object({
    city: z.string()
      .describe('用户询问的城市名称，例如：北京、上海'), // ✅ 字段级描述
    unit: z.enum(['celsius', 'fahrenheit'])
      .describe('温度单位，默认为摄氏度'),
  }),
  execute: async ({ city, unit }) => { 
    return { city, temp: 25, unit, condition: 'Sunny' }; 
  },
});

2. 处理可选参数：使用 .nullable()

在定义 Schema 时，TypeScript 开发者习惯用 .optional()。但在 LLM 的世界里（尤其是当某些 Provider 开启严格模式时），.optional() 可能会导致参数丢失或验证错误。

官方建议：为了获得最大的兼容性，建议使用 .nullable() 替代 .optional()。

TypeScript

// ⚠️ 可能导致兼容性问题
workdir: z.string().optional(),

// ✅ 推荐写法：明确告诉模型该字段可以为空
workdir: z.string().nullable().describe('工作目录，如果不指定则使用当前目录'),

3. 日期处理 (Zod Dates)

LLM 返回的 JSON 中，日期通常是 字符串 格式。如果你直接使用 z.date()，验证会失败。你需要使用 z.string() 接收，然后通过 transform 转换为 Date 对象。

TypeScript

const eventSchema = z.object({
  eventName: z.string(),
  date: z
    .string()
    .date() // 验证是否为 YYYY-MM-DD 格式
    .transform((val) => new Date(val)), // ✅ 自动转换为 Date 对象
});

4. 温度设置 (Temperature)

对于 工具调用 (Tool Calling) 和 结构化数据生成 (Object Generation) ，为了保证结果的确定性和格式的正确性，强烈建议将 temperature 设置为 0。

TypeScript

const result = await generateText({
  model: model, // GLM-5
  temperature: 0, // ✅ 核心设置：减少随机性，提高指令遵循能力
  tools: { ... },
  prompt: '...',
});

---

🐞 调试技巧 (Debugging)

如果 GLM-5 没有按预期调用工具，你可以检查返回结果中的 warnings。

TypeScript

const result = await generateText({
  model: model,
  prompt: '...',
  tools: { ... },
});

// 打印警告信息，查看是否有参数解析失败或工具未调用的情况
if (result.warnings) {
  console.warn('⚠️ Warnings:', result.warnings);
}

---

💻 完整实战示例：GLM-5 智能日程助手

下面我们将上述所有技巧整合，编写一个使用 GLM-5 处理日程的智能助手。

TypeScript

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

// 1. 配置 GLM-5
const zhipu = createOpenAI({
  baseURL: 'https://open.bigmodel.cn/api/paas/v4',
  apiKey: process.env.ZHIPU_API_KEY,
});

async function main() {
  console.log('🤖 正在连接 GLM-5...');

  try {
    const result = await generateText({
      model: zhipu('glm-5'),
      // ✅ 技巧：设置为 0 以确保工具调用的稳定性
      temperature: 0, 
      
      prompt: '帮我安排下周一上午9点和产品经理开会，地点在302会议室。顺便查一下那天的天气。',
      
      tools: {
        // 工具 1：日程管理
        scheduleMeeting: tool({
          description: '创建一个新的会议日程',
          parameters: z.object({
            topic: z.string().describe('会议主题'),
            // ✅ 技巧：处理日期字符串转换
            time: z.string().describe('会议的具体时间，格式为 YYYY-MM-DD HH:mm').nullable(),
            location: z.string().describe('会议地点').nullable(), // ✅ 技巧：使用 nullable
            participants: z.array(z.string()).describe('参会人员名单').nullable(),
          }),
          execute: async ({ topic, time, location }) => {
            console.log(`✅ [Action] 已预约会议: "${topic}" @ ${location} (${time})`);
            return { status: 'success', id: 12345 };
          },
        }),

        // 工具 2：天气查询
        getWeather: tool({
          description: '查询指定日期的天气情况',
          parameters: z.object({
            date: z.string().describe('需要查询的日期，格式 YYYY-MM-DD'),
            city: z.string().describe('城市名称').nullable(),
          }),
          execute: async ({ date, city }) => {
            console.log(`✅ [Action] 查询天气: ${city || '本地'} on ${date}`);
            return { temp: 22, condition: '多云转晴' };
          },
        }),
      },
      
      // 允许模型进行多步操作（如果需要模型连续调用多个工具，最大步骤数设为 > 1）
      maxSteps: 5,
    });

    console.log('\n💬 GLM-5 回复:');
    console.log(result.text);

  } catch (error) {
    console.error('❌ Error:', error);
  }
}

main();

运行结果预期

GLM-5 凭借其强大的推理能力，会准确识别出两个意图（安排会议 + 查天气），并依次（或并行）调用工具，最后生成自然的回复。

Plaintext

🤖 正在连接 GLM-5...
✅ [Action] 已预约会议: "和产品经理开会" @ 302会议室 (2026-02-16 09:00)
✅ [Action] 查询天气: 本地 on 2026-02-16

💬 GLM-5 回复:
我已经为您安排好了下周一（2月16日）上午9点与产品经理在302会议室的会议。同时，我查询了那天的天气，预计是多云转晴，气温约22度。

---

总结

Prompt Engineering 在 Vercel AI SDK 中不仅仅是 "说话的艺术"，更是 Schema 定义的艺术。

1. 明确的模型选择：使用 GLM-5 这样强逻辑模型。
2. 严谨的类型定义 ：多用 .describe()，善用 .nullable()。
3. 零温度设定 ：temperature: 0 是工具调用的最佳拍档。

掌握这些技巧，你的 AI 应用将从 "偶尔能用" 进化为 "工业级稳定"！🚀