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