跳转至

SAGE 改进建议和问题追踪

本文档记录 SAGE 系统的改进建议和待解决问题，供开发团队参考和规划。

待实现功能

1. 可配置的 Sink 排空参数

状态: 🟡 规划中
创建时间: 2025-09-27
优先级: 中

问题描述

当前 BaseTask 中的优雅排空功能使用硬编码的默认值： - drain_timeout: 10秒 - drain_quiet_period: 0.3秒

这些固定值在当前回归测试中工作良好，但可能不适用于所有部署场景，特别是： - 处理大负载的环境 - 分布式队列系统 - 需要更高可靠性的生产环境

解决方案

需要添加配置选项，允许用户自定义这些参数：

sink:
  drain_timeout: 30.0        # 自定义超时时间
  drain_quiet_period: 0.5    # 自定义静默期

验收标准

  1. ✅ SinkOperator 接受可选的配置参数
  2. ✅ BaseTask 读取配置值，未指定时使用默认值
  3. ✅ 单元测试覆盖自定义排空值和优雅关闭行为
  4. ✅ 更新文档和配置示例

开放问题

  • 是否通过环境变量全局暴露设置，还是仅限于操作器级别配置？
  • 是否需要参数验证（最小/最大边界）以防止配置错误？

2. 优雅关闭文档完善

状态: ✅ 已完成
创建时间: 2025-09-27
优先级: 高

问题描述

尽管在 BaseTask 中实现了优雅排空逻辑并添加了回归测试，但公开文档没有提及新的保证机制或关闭时可能的等待时间。

解决方案

已在以下文档中添加相关内容： - ✅ 运维指南中描述优雅关闭语义 - ✅ 提供操作指导：如何观察排空进度（日志、指标） - ✅ 包含故障排除部分：常见场景和调优建议 - ✅ 添加示例和配置参考

交付成果

  • ✅ 文档明确说明 sink 在 autostop 期间排空运行中数据
  • ✅ 引用默认超时/静默期值
  • ✅ 提供排空日志识别和设置覆盖示例
  • ✅ 发布说明或变更日志条目

已解决问题

LLM 服务自动配置 ✅

问题: 用户需要手动修改配置文件来适配 Ollama/vLLM 服务
解决方案: 实现 sage config llm auto 命令，自动检测和配置本地 LLM 服务
状态: 已完成并集成到文档

CI/CD 嵌入模型集成 ✅

问题: CI/CD 环境中 HuggingFace 模型下载失败
解决方案: 提供模型预缓存脚本和完整的 CI/CD 集成指南
状态: 已完成并添加到开发者文档

改进建议

用户体验改进

  1. 配置验证: 添加配置文件语法检查和验证工具
  2. 交互式配置: 提供配置向导帮助新用户快速上手
  3. 模板管理: 提供常见场景的配置模板
  4. 性能监控: 增强运行时性能监控和告警

开发体验改进

  1. 热重载: 支持配置文件热重载，避免重启服务
  2. 调试工具: 提供更好的调试和日志分析工具
  3. 测试工具: 增强集成测试和性能测试工具
  4. 文档生成: 自动从代码生成 API 文档

架构改进

  1. 插件系统: 支持第三方插件和扩展
  2. 微服务化: 支持组件的独立部署和扩缩容
  3. 云原生: 改进 Kubernetes 和容器化支持
  4. 监控集成: 与 Prometheus、Grafana 等监控系统集成

反馈渠道

如果您遇到问题或有改进建议，请通过以下方式反馈：

  1. GitHub Issues: 在项目仓库创建 issue
  2. 讨论区: 参与 GitHub Discussions
  3. 开发者邮件列表: 发送邮件至开发团队
  4. 技术文档: 直接提交文档改进的 PR

相关文档