The Grafana AI SDK for Go: a shared foundation for building AI applications

使用大语言模型（LLM）启动实验从未如此简单。但保持这些实验的持续一致性却是一个更大的挑战。

今年早些时候，随着Grafana Labs越来越多团队开始探索AI功能，我们反复遇到相同的问题模式：每当启动新实验时，团队会快速推进并为所需模型提供商构建专属客户端。下一个实验也会采用类似方式，但流式处理、工具、错误或提供商配置的抽象层会略有不同。

这种现象在当时是可以理解的。模型提供商的更新速度很快，我们的团队也在快速学习，而代码代理技术让想法转化为可用集成的速度比以往任何时候都快。但这种速度也导致每个集成都发展出独特的架构。

最终，我们不得不维护一套本质上解决相同问题的解决方案集合。

由于我们大部分后端服务使用Go语言编写，因此我们开发了Grafana AI SDK for Go，为团队提供统一的开发基础。该SDK提供了通用接口用于调用模型、流式响应、执行工具、生成结构化输出以及运行多步骤代理。它还支持Vercel AI SDK前端钩子使用的协议，因此Go后端可以直接流式传输到useChat、useCompletion和useObject。

我们开发这个SDK是因为Grafana Labs内部有此需求，但我们在上个月将其开源（同时发布了更广泛的工具集，用于构建、运营和理解AI系统，详见我们首次Grafana Labs AI Week活动）。我们认为其他使用Go开发AI应用的团队很可能也会遇到类似问题。

我们希望与社区共同推进下一步发展，因此在本文中将详细介绍该项目，包括您今天如何使用它，以及如何帮助我们改进它。

今天团队可以使用它构建哪些内容

SDK支持从简单模型调用到复杂应用工作流的多种场景：

• 生成完整响应或实时流式输出
• 将类型化Go函数暴露为工具，并支持多步骤模型和工具流程
• 暂停需要人工或应用审批的关键工具
• 生成符合模式验证的Go对象、数组和选项
• 添加超时、重试、模型降级、日志、指标和代理可观测性
• 为AI SDK React钩子提供流式Go端点

代码库包含一个全栈代理聊天示例和一个结构化提取示例，以及测试、安全、错误处理和生产运营的指南。

这是许多 Grafana Labs 团队现在依赖的通用基础，而不是为每个新集成重新实现相同模式。它仍然是一个年轻的项目，所处的生态系统变化异常迅速。随着我们从更多应用中学习，我们预计接口、提供方和合规基线将持续演变。

[从快速实验到通用模式](https://grafana.com/blog/the-grafana-ai-sdk-for-go-a-shared-foundation-for-building-ai-applications/#from-fast-experiments-to-common-patterns)

接下来，我想多说一些我们是如何走到这一步的，因为我猜你们中有很多人经历过类似的情况。

我们早期的 LLM 集成是有意作为实验进行的。在那个阶段，本地决策和重复代码通常是最快的学习方式。但随着这些实验的增加，问题也随之出现。

每个提供方都有自己的 API、认证模型、流式事件、错误行为和特定模型的功能。当一个应用超出单次提示和响应的范围后，还需要对工具、结构化输出、重试、超时、对话历史以及流式传输中途失败时的处理方式做出决策。

当每个团队都拥有整个堆栈时，微小的差异会逐渐积累：

• 一个集成在提供方层进行重试，而另一个则对整个操作进行重试。
• 一个向前端流式传输自定义事件，而另一个则等待完整响应。
• 每个应用在能够添加或修改 AI 驱动的工作流之前，都必须学习一套不同的惯例。

这些实现本身未必是错误的。然而，总体来看，它们使得共享改进变得更加困难，也更难建立一致的操作和安全实践。

SDK 的目标是将这些重复的基础设施集中到一个地方。产品团队仍然拥有自己的提示、工具、授权、工作流和用户体验，但他们不应该在开始之前就必须发明新的提供方抽象和流式传输协议。

这并不意味着这是一个逐行移植的版本，也不表示在功能特性上实现了完全一致。Go SDK 中目前仍缺少一些上游功能，某些概念在 Go 中也需要不同的实现方式。我们维护了一份公开的兼容性基准和一份已知差距与偏差的覆盖地图，以便让这些差异清晰可见，而不是被宽泛的兼容性声明所掩盖。

跨提供者的统一接口

Grafana AI SDK 当前支持 Anthropic、Amazon Bedrock、OpenAI 的 Responses API 以及 OpenAI 兼容 API。提供者集成分布在独立的 Go 模块中，因此应用程序只需安装实际使用的依赖项。一旦构建了模型，围绕生成和编排的 API 保持一致。

一个基本调用的示例如下：

相同的模型接口支持流式传输、类型化工具、结构化输出、代理循环、降级和中间件。切换提供者仍可能暴露真实差异——模型并不普遍支持相同的输入、推理选项或工具——但应用程序无需为每个提供者完全改变架构。

这种共享的提供者边界正是使 SDK 其余部分可组合的关键。它让我们能够一次性围绕模型调用添加行为，并在所有应用程序中保持一致的应用。

通过中间件添加 Grafana Labs 风格

对我们而言，这种共享行为最重要的体现是可观测性。

一个 AI 应用可能将一个用户请求转化为多个模型调用。代理可能调用工具、经过多步处理、重试失败请求或切换到其他提供者。如果我们仅观察外部 HTTP 请求，大量工作和许多失败模式将仍然不可见。

SDK 的 Agent Observability 中间件会在 Grafana 中记录模型和代理活动，包括使用情况、错误、多步关系以及路由调用的提供者。SDK 还包含可选的中间件用于结构化日志和 Prometheus 指标。

监控是起点而非终点。更大的挑战是利用生产信号来理解代理行为、发现故障、构建更好的测试用例，并在变更影响用户前进行评估。如需深入了解这一演进过程——从实时流量监控到评估、测试套件、实验和 CI/CD——请阅读我们的博文 如何通过 Grafana Agent Observability 为您的代理构建信任平台。

由于中间件封装了通用模型接口，应用团队无需独立为每个提供者集成进行监控。他们可以基于共享惯例起步，并将时间投入到真正使产品有价值的行为实现上。

注意： 可观测性只是负责任地运营 AI 系统的一部分。我们还在开发大语言模型安全中间件，未来将分享更多相关内容。更广泛地说，应用程序仍需要验证用户身份、授权工具、验证模型生成的输入、限制资源使用，并仔细决定哪些内容可以存储或记录。SDK 为这些决策提供了构建模块；它不会代表应用程序做出决策。

[从 Go 到前端的更简单路径](https://grafana.com/blog/the-grafana-ai-sdk-for-go-a-shared-foundation-for-building-ai-applications/#a-simpler-path-from-go-to-the-frontend)

后端并不是我们实现差异化的唯一地方。将模型响应流式传输到浏览器可能需要自己的事件格式、消息表示、工具状态、错误处理和对话持久化机制。

Grafana AI SDK 实现了 @ai-sdk/react 使用的 UI 消息流协议。Go 处理程序可以直接将服务器发送事件写入 useChat，而工具、推理、来源、文件和应用程序数据则通过类型化消息片段传输。

这使后端团队可以继续使用 Go，而前端团队可以使用他们已经熟悉的生态系统和原始组件。这也意味着当后端逻辑迁移到 Go 服务时，团队可以复用现有的 AI SDK 前端，而无需在两者之间创建协议适配器。

[让我们一起构建](https://grafana.com/blog/the-grafana-ai-sdk-for-go-a-shared-foundation-for-building-ai-applications/#lets-build-it-together)

Grafana AI SDK 最初源于一个实际的内部需求：防止基于 Go 的 AI 工作演变为一组孤立的提供商客户端和自定义协议。现在，它为我们的团队提供了一种通用的方式来构建和观察这些应用。

如果您的后端使用 Go 编写，我们希望它也能为您提供类似的起点。

您可以在 grafana/ai-sdk 仓库 中找到代码、文档和可运行示例。尝试使用现有的 AI SDK 前端进行测试，构建一个提供商或中间件，告诉我们抽象层在哪些地方不适用，或为需要的功能提交问题。

Grafana AI SDK 是我们在 AI 周期间分享的多个项目和功能之一。阅读 AI 周回顾，了解其他公告以及我们关于 AI 和可观测性工作的更广泛思考。

我们知道这个基础对我们来说很有用。现在，我们希望了解在 Go 社区和开源社区的参与下，它能发展成什么样子。