Vercel AI SDK 中 Anthropic API 工具调用时文本内容块空值的处理方案

在开发基于 Vercel AI SDK 的聊天应用时，当使用 Anthropic 的 Claude 模型（如 claude-3-5-sonnet-latest）进行工具调用时，开发者可能会遇到一个常见问题：系统生成的助手消息中包含空的文本内容块，导致 API 调用失败。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象分析

当开发者使用 Vercel AI SDK 结合 Anthropic 的 Claude 模型进行工具调用时，系统会在以下场景产生错误：

1. 模型在响应过程中触发工具调用
2. SDK 生成的助手消息中可能包含形如 {"type": "text", "text": ""} 的空文本内容块
3. 当这些消息被发送回 Anthropic API 时，会触发 [AI_APICallError: messages: text content blocks must be non-empty] 错误

这与 Anthropic API 的严格验证机制有关，该 API 要求所有文本内容块必须包含非空字符串，而其他模型（如 OpenAI）则可能允许空文本块。

技术背景

在 AI 对话系统中，消息通常由多种内容块组成，包括：

• 文本内容块：包含对话文本
• 工具调用块：指示模型希望调用的函数
• 工具结果块：包含函数调用的返回结果

Anthropic 的 Claude 模型在处理这些内容块时采用了严格的验证策略，特别是对于文本内容块，要求必须包含实际内容。这种设计可能是为了防止模型生成无意义的空响应，确保对话质量。

解决方案演进

Vercel AI SDK 团队针对此问题提供了两种解决方案：

临时解决方案：使用 LLM 中间件

在官方修复发布前，开发者可以通过实现 LLM 中间件来自行处理空文本内容块。具体方法是使用 transformParams 钩子，在消息发送到 API 前过滤掉空文本块：

const anthropicWithMiddleware = anthropic.withConfig({
  transformParams(params) {
    return {
      ...params,
      messages: params.messages.map(message => ({
        ...message,
        content: message.content.filter(
          block => block.type !== 'text' || block.text.trim() !== ''
        )
      }))
    };
  }
});

这种方法灵活且即时可用，但需要开发者自行维护过滤逻辑。

官方永久解决方案

在 Vercel AI SDK 4.3.7 版本中，官方已内置了对空文本内容块的过滤逻辑。更新到最新版本后，系统会自动处理以下情况：

1. 自动移除助手消息中的空文本块
2. 保留有效的工具调用块
3. 确保消息结构符合 Anthropic API 的要求

最佳实践建议

1. 版本控制：确保使用 Vercel AI SDK 4.3.7 或更高版本
2. 消息结构验证：在开发过程中验证所有消息内容块的有效性
3. 错误处理：实现适当的错误处理逻辑，捕获并处理可能的 API 错误
4. 测试策略：特别针对工具调用场景进行充分测试，验证消息结构的正确性

技术实现示例

以下是一个完整的实现示例，展示了如何安全地使用 Anthropic Claude 模型进行工具调用：

import { streamText } from 'ai';
import { createAnthropic } from '@ai-sdk/anthropic';

const anthropic = createAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const tools = {
  getData: {
    description: '数据查询工具',
    parameters: {
      type: 'object',
      properties: { query: { type: 'string' } },
      required: ['query'],
    },
    execute: async ({ query }) => {
      return `查询结果: ${query}`;
    },
  },
};

async function safeToolCalling() {
  const messages = [{ role: 'user', content: '查询示例数据' }];
  
  const result = await streamText({
    model: anthropic('claude-3-5-sonnet-latest'),
    messages,
    tools,
  });

  for await (const chunk of result.fullStream) {
    if (chunk.type === 'tool-call') {
      const toolResult = await tools.getData.execute(chunk.args);
      
      // 安全地添加消息，确保无空内容块
      messages.push({
        role: 'assistant',
        content: [
          {
            type: 'tool_use',
            id: chunk.toolCallId,
            name: 'getData',
            input: chunk.args,
          },
        ],
      });
      
      messages.push({
        role: 'user',
        content: [
          {
            type: 'tool_result',
            tool_call_id: chunk.toolCallId,
            content: toolResult,
          },
        ],
      });
    }
  }
}

总结

Vercel AI SDK 与 Anthropic Claude 模型的集成提供了强大的工具调用能力，但需要注意 Anthropic API 对消息内容的特殊要求。通过理解这一限制并采用适当的解决方案，开发者可以构建稳定可靠的 AI 对话应用。官方在 4.3.7 版本中的修复简化了这一过程，使开发者能够更专注于业务逻辑的实现。