OpenAI Node.js SDK 文件搜索工具使用问题解析

问题背景

在使用OpenAI Node.js SDK创建带有文件搜索(file_search)功能的AI助手时，开发者在上传文件到向量存储(vector store)时遇到了一个常见错误。这个错误表现为当尝试使用fileBatches.uploadAndPoll方法时，系统抛出"TypeError: Cannot read properties of undefined (reading 'length')"异常。

错误原因分析

经过开发者社区和OpenAI团队成员的深入讨论，发现这个问题主要源于两个因素：

1. 文档示例代码不准确：官方文档中提供的示例代码片段使用了错误的参数传递方式，直接传递了文件流数组，而实际上该方法需要接收一个包含files属性的对象。

2. 参数类型不匹配：uploadAndPoll方法期望接收的参数结构是{ files: Uploadable[]; fileIds?: string[] | undefined; }，而文档示例中直接传递了文件流数组。

正确使用方法

要正确实现文件上传到向量存储的功能，开发者应该采用以下两种方式之一：

方法一：使用files.createAndPoll

const fileData = await openai.files.create({
  file: fs.createReadStream("document.pdf"),
  purpose: "fine-tune",
});

let vectorStore = await openai.beta.vectorStores.create({
  name: "文档存储",
});

await openai.beta.vectorStores.files.createAndPoll(
  vectorStore.id,
  {
    file_id: fileData.id,
  }
);

方法二：正确使用fileBatches.uploadAndPoll

const fileStreams = [
  "document1.pdf",
  "document2.pdf"
].map((path) => fs.createReadStream(path));

let vectorStore = await openai.beta.vectorStores.create({
  name: "文档存储",
});

await openai.beta.vectorStores.fileBatches.uploadAndPoll(vectorStore.id, {
  files: fileStreams,
});

最佳实践建议

1. 类型检查：在TypeScript项目中，可以利用类型系统来避免此类问题，错误的参数传递会在编译时就被发现。

2. 错误处理：在实际应用中，应该为文件上传操作添加适当的错误处理和重试机制。

3. 文档验证：虽然官方文档通常是可靠的，但在使用时仍建议结合API定义进行验证。

4. 替代方案：如果只是上传少量文件，使用files.createAndPoll方法可能更为直接和可靠。

总结

这个问题的出现提醒我们，在使用任何SDK时都应该：

1. 仔细阅读API定义而不仅仅是示例代码
2. 理解方法参数的实际结构
3. 在TypeScript项目中充分利用类型系统
4. 遇到问题时查阅社区讨论和issue跟踪

OpenAI团队已经确认会在下一个版本中修复文档示例并改进错误提示信息，这将帮助开发者更容易地正确使用文件搜索功能。