Paperless-AI项目Playground功能故障分析与修复

问题背景

在Paperless-AI文档管理系统的使用过程中，发现了一个关于Playground功能的异常现象。该系统通过AI技术自动分析文档内容并提取元数据，其中Playground功能允许用户测试不同的提示词(prompt)变体来优化分析结果。然而在实际使用中，虽然常规文档分析功能运行正常，但Playground功能却无法正常工作。

故障现象

当用户尝试在Playground中使用任何提示词（包括已知在常规分析中有效的提示词）时，系统会抛出以下关键错误：

1. 404资源未找到错误(NotFoundError)
2. 无法读取null的promptTokens属性
3. 日志显示分析过程完全失败

值得注意的是，这些错误仅出现在Playground功能中，常规文档分析功能完全正常，能够正确生成标签和元数据。

技术分析

深入分析日志和代码后，发现问题根源在于Azure服务接口调用时的路径配置错误。具体表现为：

1. 当系统尝试通过Azure OpenAI服务执行Playground分析时，发送了错误的API端点路径
2. 服务返回404错误表明请求的资源不存在
3. 由于主分析流程和Playground流程使用不同的代码路径，导致主功能正常而Playground失败

解决方案

修复方案主要涉及azureService.js文件的修改：

1. 修正Azure API调用的端点路径配置
2. 确保Playground模式下的请求参数与常规分析模式一致
3. 完善错误处理逻辑，避免null引用异常

该修复已通过Pull Request提交并合并到主分支，解决了Azure服务用户在Playground功能中遇到的普遍性问题。

经验总结

这个案例展示了分布式系统中常见的几个重要问题：

1. 环境一致性：开发环境和生产环境的API端点可能存在差异，需要确保配置的一致性
2. 错误处理：需要全面考虑各种异常情况，特别是外部服务调用失败时的处理
3. 代码复用：相似功能的不同实现路径可能导致不一致的行为，应尽可能复用代码

对于Paperless-AI用户来说，升级到包含此修复的版本后，Playground功能将恢复正常使用，用户可以安全地测试不同的提示词变体来优化文档分析结果。