Unstract项目工具执行失败问题分析与解决方案

问题背景

在使用Unstract项目(v0.70.2版本)时，用户遇到了工具执行失败的问题。具体表现为：在Prompt Studio中创建的项目可以正常工作并成功导出为工具，但在创建简单的工作流后尝试执行时出现错误。

错误现象

工作流执行时主要出现两类错误：

1. 构建阶段错误：

Error processing file: AUTH <password> called without any password configured for the default user. Are you sure your configuration is correct?

2. 运行阶段错误：

Tool exception raised for tool, check logs for more information
Execution completed for 0 files out of 1

根本原因分析

经过开发团队调查，发现这是v0.70.2版本中已知的问题，主要涉及以下方面：

1. 工具结构问题：unstract/tool-structure镜像版本(0.0.25)存在模块导入错误，导致容器启动失败。

2. 环境配置问题：默认配置中缺少必要的密码设置，导致认证失败。

3. 日志记录不足：错误信息不够详细，增加了调试难度。

解决方案

针对这些问题，开发团队提供了以下解决方案：

1. 版本升级

建议用户升级到v0.70.3或更高版本，该版本已修复相关问题。升级命令：

./run-platform.sh --upgrade

2. 环境变量调整

修改backend/.env文件中的结构工具配置：

# 原配置
STRUCTURE_TOOL_IMAGE_URL="docker:unstract/tool-structure:0.0.25"
STRUCTURE_TOOL_IMAGE_NAME="unstract/tool-structure"
STRUCTURE_TOOL_IMAGE_TAG="0.0.25"

# 修改为
STRUCTURE_TOOL_IMAGE_URL="docker:unstract/tool-structure:0.0.26"
STRUCTURE_TOOL_IMAGE_NAME="unstract/tool-structure"
STRUCTURE_TOOL_IMAGE_TAG="0.0.26"

3. 调试配置

为便于调试工具执行问题，可以设置：

REMOVE_CONTAINER_ON_EXIT=False

这样容器在退出后不会被立即删除，方便检查容器状态和日志。

4. 日志查看方法

当工具执行失败时，可以通过以下命令查看详细日志：

docker compose logs backend
docker compose logs worker

最佳实践建议

1. 重新导出工具：在完成上述修改后，建议重新从Prompt Studio导出工具，确保使用最新的修复版本。

2. 分步测试：先确保单个工具能正常运行，再构建工作流。

3. 监控容器状态：使用docker ps -a命令检查工具容器的退出状态和日志。

4. 关注已知问题：目前工作流步骤执行功能仍在完善中，建议关注项目更新。

总结

Unstract项目在工具执行方面的问题主要源于特定版本的镜像缺陷和环境配置。通过升级版本、调整配置和合理使用调试工具，可以有效解决这些问题。开发团队正在持续改进系统稳定性和错误报告机制，未来版本将提供更流畅的用户体验。