Vercel AI SDK

Vercel AI SDK 使添加 AI 模型可调用的工具变得简单。本指南展示如何将 EmailVerify 邮箱验证集成为工具。

安装

npm install ai @ai-sdk/openai zod

基础工具定义

import { tool } from 'ai';
import { z } from 'zod';

export const verifyEmailTool = tool({
  description: '验证邮箱地址是否有效且可送达。返回状态、可送达性，以及邮箱是否为一次性或角色邮箱。',
  parameters: z.object({
    email: z.string().email().describe('要验证的邮箱地址'),
  }),
  execute: async ({ email }) => {
    const response = await fetch('https://api.emailverify.ai/v1/verify', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.EMAILVERIFY_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email }),
    });

    if (!response.ok) {
      throw new Error(`验证失败: ${response.statusText}`);
    }

    return response.json();
  },
});

使用 streamText

用于流式响应:

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { verifyEmailTool } from './tools/verify-email';

const result = await streamText({
  model: openai('gpt-4-turbo'),
  tools: {
    verifyEmail: verifyEmailTool,
  },
  prompt: '验证 user@example.com 是否为有效的邮箱地址',
});

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

使用 generateText

用于带工具结果的非流式响应:

import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { verifyEmailTool } from './tools/verify-email';

const { text, toolCalls, toolResults } = await generateText({
  model: anthropic('claude-3-5-sonnet-20241022'),
  tools: {
    verifyEmail: verifyEmailTool,
  },
  maxToolRoundtrips: 3,
  prompt: '检查这些邮箱并告诉我哪些是有效的: john@google.com, test@mailinator.com',
});

console.log(text);
console.log('工具调用:', toolCalls);
console.log('工具结果:', toolResults);

Next.js API 路由

创建用于 AI 聊天和邮箱验证的 API 路由:

// app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { verifyEmailTool } from '@/lib/tools/verify-email';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai('gpt-4-turbo'),
    messages,
    tools: {
      verifyEmail: verifyEmailTool,
    },
  });

  return result.toDataStreamResponse();
}

React 客户端组件

使用 useChat hook:

'use client';

import { useChat } from 'ai/react';

export function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat',
  });

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="让我验证一个邮箱..."
        />
        <button type="submit">发送</button>
      </form>
    </div>
  );
}

批量验证工具

一次验证多个邮箱:

import { tool } from 'ai';
import { z } from 'zod';

export const verifyEmailsBulkTool = tool({
  description: '一次验证多个邮箱地址。检查邮箱列表时使用此工具。',
  parameters: z.object({
    emails: z.array(z.string().email()).max(100).describe('要验证的邮箱地址数组'),
  }),
  execute: async ({ emails }) => {
    const response = await fetch('https://api.emailverify.ai/v1/verify/bulk', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.EMAILVERIFY_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ emails }),
    });

    return response.json();
  },
});

完整示例

以下是包含多个工具的完整示例:

// lib/tools/index.ts
import { tool } from 'ai';
import { z } from 'zod';

export const verifyEmailTool = tool({
  description: `验证邮箱地址是否有效且可送达。

返回结果:
- status: "valid"（有效）、"invalid"（无效）或 "unknown"（未知）
- deliverable: 邮箱是否可以接收消息
- disposable: 是否为临时邮箱服务
- role: 是否为角色邮箱，如 info@ 或 support@
- score: 置信度分数，范围从 0 到 1

使用场景:
- 用户请求验证邮箱
- 检查邮箱是否真实
- 验证联系信息`,
  parameters: z.object({
    email: z.string().email().describe('要验证的邮箱地址'),
  }),
  execute: async ({ email }) => {
    try {
      const response = await fetch('https://api.emailverify.ai/v1/verify', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.EMAILVERIFY_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ email }),
      });

      if (!response.ok) {
        if (response.status === 429) {
          return { error: '超出速率限制。请稍后重试。' };
        }
        return { error: `验证失败: ${response.statusText}` };
      }

      return response.json();
    } catch (error) {
      return { error: '网络错误。无法连接到验证服务。' };
    }
  },
});

export const checkCreditsTool = tool({
  description: '检查剩余的邮箱验证额度',
  parameters: z.object({}),
  execute: async () => {
    const response = await fetch('https://api.emailverify.ai/v1/credits', {
      headers: {
        'Authorization': `Bearer ${process.env.EMAILVERIFY_API_KEY}`,
      },
    });
    return response.json();
  },
});

// app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { verifyEmailTool, checkCreditsTool } from '@/lib/tools';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai('gpt-4-turbo'),
    system: '你是一个可以验证邮箱地址的助手。当被要求验证邮箱时，请使用 verifyEmail 工具。',
    messages,
    tools: {
      verifyEmail: verifyEmailTool,
      checkCredits: checkCreditsTool,
    },
    maxToolRoundtrips: 5,
  });

  return result.toDataStreamResponse();
}

下一步

LangChain 集成

与 LangChain 代理一起使用

OpenAI 函数调用

直接 OpenAI 集成

API 参考

完整 API 文档

Vercel AI SDK

LangChain 集成

OpenAI 函数调用

API 参考

On this page