BAML：用声明式语言终结提示工程混乱，实现AI应用类型安全开发

1. BAML 项目概述：当提示工程遇上模式工程

如果你和我一样，在过去一两年里深度参与了基于大语言模型（LLM）的应用开发，那你一定对“提示工程”这个词又爱又恨。爱的是，它确实是我们与这些“黑盒”模型沟通的主要桥梁；恨的是，维护一堆散落在代码各处、由脆弱的字符串拼接而成的提示词（prompt），简直是一场噩梦。变量替换、格式控制、多轮对话管理、输出解析……这些工作不仅繁琐，而且极易出错，调试起来更是让人抓狂。我常常感觉自己不是在写代码，而是在玩一种极其不稳定的“文字炼金术”。

直到我遇到了BAML，全称是“Basically a Made-up Language”。这个名字起得挺有意思，直译是“基本上是一种编造的语言”，带着点自嘲和极客的幽默感。但别被名字骗了，这可不是什么玩具。它来自 BoundaryML 团队，本质上是一种专为构建可靠 AI 工作流和智能体（Agent）而设计的声明式提示语言。它的核心思想非常吸引我：将混乱的“提示工程”转变为结构化的“模式工程”。也就是说，你不再需要去精心雕琢每一句话术，而是把精力集中在定义你希望模型输出的数据结构（Schema）上。BAML 编译器会帮你处理剩下的一切——生成符合你结构的提示、调用模型、解析输出，并以完全类型安全的方式将结果返回给你的主程序。

简单来说，BAML 让你能用写接口定义的方式去写提示。你定义一个函数，指定输入参数和返回类型，再配上简单的提示模板和模型客户端，剩下的脏活累活它全包了。最妙的是，你不需要把整个应用都用 BAML 重写。它只负责管理你的提示层，你可以继续用你熟悉的 Python、TypeScript、Go 等语言编写业务逻辑，然后像调用本地函数一样调用这些定义在 BAML 文件中的“提示函数”。这对于我们这些已经在现有技术栈上投入巨大的团队来说，迁移成本极低，吸引力巨大。

2. 核心设计哲学：为什么我们需要一门新语言？

在深入细节之前，我觉得有必要先聊聊 BAML 背后的设计哲学。这能帮助我们理解它为何如此设计，而不仅仅是“怎么用”。BoundaryML 团队在官方博客中做了个非常形象的类比：早期的网页开发，人们把 HTML、CSS、JavaScript 全都混写在一个字符串里，用echo或print语句输出，这就是所谓的“PHP/HTML 汤”。现在的 LLM 应用开发何其相似！我们把用户消息、系统指令、上下文、工具描述全都用 f-string 或模板字符串拼接起来，形成一段冗长、难以维护、无法进行静态分析的“提示汤”。

BAML 的诞生，就是为了解决这种“提示汤”的困境。它的设计遵循几个明确的原则：

原则一：能复用现有工具，就绝不发明新轮子。这是我最欣赏的一点。BAML 没有自己去造一套复杂的版本控制系统或存储方案。它认为，管理提示词最好的工具就是Git，存储它们最好的地方就是文件系统。你的.baml文件就是普通的文本文件，可以享受 Git 带来的所有好处：版本对比、分支管理、协作评审。这大大降低了团队的使用和协作门槛。

原则二：任何文本编辑器和终端都应该足以使用它。BAML 不强制绑定某个特定的 IDE 或云平台。虽然它提供了强大的 VS Code 和 JetBrains 插件来提升体验，但理论上你用 Vim 或记事本编辑.baml文件，用命令行调用编译器，也能完成所有工作。这种“不设限”的设计保证了工具的普适性和开发者的自由度。

原则三：必须足够快。BAML 的编译器是用 Rust 编写的，编译速度极快。在你迭代提示的时候，那种即改即得的流畅感至关重要，任何明显的延迟都会打断思路。BAML 在这方面做得很好，快到让你几乎感觉不到编译过程的存在。

原则四：让大学一年级学生也能理解。这意味着语法必须直观、简洁，学习曲线平缓。BAML 的语法借鉴了 TypeScript/Go/Rust 等多种语言中常见的元素，对于有编程基础的人来说非常容易上手。它的目标不是成为一门复杂的通用语言，而是一个精准解决“提示定义”这一特定问题的领域特定语言（DSL）。

基于这些原则，BAML 选择成为一门独立的语言，而不是嵌入在现有语言中的库。这赋予了它最大的表达能力和优化空间，能够为“提示即函数”这个核心概念设计最合适的语法和工具链。

3. 从“提示汤”到“提示函数”：BAML 语法初探

让我们直接看代码，这是理解 BAML 最直接的方式。假设我们要构建一个简单的聊天代理，它能根据指定的情绪（tone）进行回复，并且能判断何时应该礼貌地结束对话。

在传统的 Python 代码中，我们可能会这样写：

import openai import json from typing import Literal, Union from pydantic import BaseModel class StopTool(BaseModel): action: Literal["stop"] = "stop" class ReplyTool(BaseModel): response: str def chat_agent(messages: list[dict], tone: str) -> Union[StopTool, ReplyTool]: # 1. 手动拼接系统提示和上下文 system_prompt = f"You are a {tone} assistant. You can either reply or stop the conversation." # 2. 手动描述输出格式（JSON Schema），容易出错 output_format_instruction = """ You MUST output a JSON object matching ONE of these schemas: - For replying: `{"response": "your reply here"}` - For stopping: `{"action": "stop"}` """ # 3. 拼接整个提示 prompt_messages = [ {"role": "system", "content": system_prompt + output_format_instruction} ] prompt_messages.extend(messages) # 4. 调用 API response = openai.chat.completions.create( model="gpt-4o-mini", messages=prompt_messages, response_format={"type": "json_object"}, # 依赖模型对 JSON 模式的支持 ) # 5. 解析并验证输出 raw_output = response.choices[0].message.content try: data = json.loads(raw_output) if "response" in data: return ReplyTool(**data) elif data.get("action") == "stop": return StopTool(**data) else: raise ValueError("Invalid output format") except json.JSONDecodeError: # 6. 处理解析失败，可能需要重试或降级 raise

这段代码充满了隐患：字符串拼接容易出错，JSON Schema 描述是孤立的字符串，输出解析逻辑脆弱，错误处理繁琐。现在，我们看看用 BAML 如何实现同样的功能：

// 首先，定义数据结构 class Message { role string content string } // 定义可能的返回工具（Tool） class StopTool { action "stop" @description(#" Use this when it might be a good time to end the conversation politely. "#) } class ReplyTool { response string } // 核心：定义一个 BAML 函数 function ChatAgent( messages: Message[], tone: "happy" | "sad" // 输入参数，tone 被限定为两种字面量 ) -> StopTool | ReplyTool { // 返回类型是两种工具的联合类型 // 指定使用的模型客户端 client "openai/gpt-4o-mini" // 提示模板，清晰易读 prompt #" You are a {{ tone }} assistant. Your task is to chat with the user. {{ ctx.output_format }} {% for msg in messages %} {{ _.role(msg.role) }}: {{ msg.content }} {% endfor %} Assistant: "# }

两相对比，高下立判。BAML 版本的优势非常明显：

1. 声明式与类型安全：输入messages是Message数组，tone是明确的枚举值。输出要么是StopTool要么是ReplyTool。这些类型会在编译时和生成代码的运行时被严格检查。
2. 关注点分离：你只需要关心数据结构（class）和函数签名（function）。繁琐的提示词组装、API 调用、输出解析、错误重试，全部由 BAML 编译器自动生成。
3. 内置的提示模板引擎：{{ }}用于变量插入，{% %}用于逻辑控制（如循环）。ctx.output_format是一个特殊的上下文变量，BAML 会自动将你定义的返回类型（StopTool | ReplyTool）转换成模型能理解的自然语言指令，并注入到提示中。你不再需要手动编写容易出错的 JSON Schema 描述。
4. 模型无关性：client "openai/gpt-4o-mini"这一行声明了使用的模型。如果你想换模型，比如换成claude-3-5-sonnet，只需修改这一行。BAML 会自动适配不同模型的 API 调用方式。

实操心得：从“如何让模型输出 JSON”切换到“我需要模型返回一个什么结构”，这种思维转变是使用 BAML 最大的收获。它迫使你在写提示前先想清楚业务逻辑真正需要的数据形状，这本身就是一个非常好的设计实践。

4. 在现有项目中集成：无缝的类型安全调用

定义好 BAML 函数后，如何在我们的主程序（比如一个 FastAPI 后端）中使用它呢？BAML 的流程非常清晰：

1. 安装 CLI 和运行时：

   # 安装 BAML 编译器 CLI pip install baml-cli # 安装对应语言的客户端库，例如 Python pip install baml-py

2. 编译 BAML 文件：在项目根目录（通常和pyproject.toml同级）运行baml-cli update。这个命令会读取你的.baml文件，并生成对应的客户端代码（如baml_client目录）。

3. 像调用本地函数一样调用：生成后，你就可以在 Python 中享受完整的类型提示和自动补全了。

from baml_client import b # 导入生成的客户端 from baml_client.types import Message, StopTool, ReplyTool # 初始化对话 conversation_history = [ Message(role="system", content="You are a helpful assistant."), Message(role="user", content="Hello!") ] # 调用 BAML 函数！完全类型安全。 # IDE 会提示你参数类型：messages: List[Message], tone: Literal["happy", "sad"] result = b.ChatAgent(conversation_history, "happy") # 根据返回类型进行逻辑处理 if isinstance(result, StopTool): print("Agent decided to stop the conversation.") elif isinstance(result, ReplyTool): print(f"Agent replied: {result.response}") # 将助手的回复加入历史，继续对话 conversation_history.append(Message(role="assistant", content=result.response))

这个过程干净利落。b.ChatAgent就是一个普通的 Python 函数，但它背后封装了模型调用、提示渲染、输出解析、错误处理等所有复杂性。你的业务代码变得极其简洁和健壮。

流式处理（Streaming）的支持也同样优雅。如果你需要处理模型逐字生成的结果，比如构建一个实时聊天的前端，可以这样做：

# 获取流式响应 stream = b.stream.ChatAgent(conversation_history, "sad") for partial in stream: # partial 是一个 Partial[StopTool | ReplyTool] 类型 # 在流式过程中，字段可能是 None，直到最终确定 if isinstance(partial, StopTool): if partial.action is not None: print("Agent is stopping...") elif isinstance(partial, ReplyTool): if partial.response is not None: # 可以实时将 partial.response 发送到前端 print(f"New token: {partial.response}") # 获取最终解析好的对象 final_tool = stream.get_final_response()

BAML 为流式场景也生成了完整的类型定义，确保你在处理部分结果时依然是类型安全的。这对于构建现代、响应式的 AI 应用至关重要。

5. 开发体验革命：在 IDE 中实现 10 倍速提示迭代

如果说 BAML 的语言特性让我眼前一亮，那么它的开发工具链则彻底征服了我。高效的 AI 应用开发，核心瓶颈往往不是代码逻辑，而是提示迭代的速度。如果跑一次完整的流程需要 2 分钟（准备数据、调用 API、解析结果、验证），那么 20 分钟你只能尝试 10 个想法。如果把每次测试缩短到 5 秒，同样的时间你能尝试 240 个想法！这完全是质的不同。

BAML 通过其强大的VS Code和JetBrains IDE插件，将迭代速度提升到了极致。安装插件后，你的.baml文件会获得：

• 语法高亮和自动补全：对函数、类、客户端名称的智能提示。
• 内联预览与测试：这是杀手级功能。你可以在函数定义的旁边直接点击一个“播放”按钮，弹出一个测试面板。

在这个测试面板里，你可以：

1. 直接编辑输入参数：提供一个 JSON 格式的输入，模拟调用。
2. 一键运行：插件会调用你指定的模型，并实时显示结果。
3. 可视化完整提示：你可以展开查看 BAML 实际发送给模型的完整提示文本，包括所有自动注入的格式指令。这对于调试和优化提示至关重要。
4. 查看原始 API 请求/响应：插件甚至能显示出它生成的 curl 命令，方便你进行更深度的调试或复现问题。
5. 并行测试：你可以同时运行多个测试用例，对比不同输入或不同模型配置下的输出。

这意味着，你不再需要：

• 在代码和 OpenAI Playground 之间来回切换。
• 手动复制粘贴提示词。
• 编写临时脚本去测试一个微小的提示改动。
• 担心本地测试与线上行为不一致。

所有测试都在你的 IDE 环境中完成，与你的项目上下文完全一致。这种“编码-测试”的紧密循环，极大地提升了开发效率和幸福感。

注意事项：IDE 插件的测试功能会真实调用你配置的模型 API 并产生费用。建议在测试时使用成本较低的模型（如gpt-4o-mini），或者配置好 API 密钥的用量提醒。

6. 解锁任意模型的工具调用能力：SAP 算法解析

结构化输出（或称为“工具调用”、“函数调用”）是构建复杂 AI 工作流的基石。然而，一个巨大的痛点是：不是所有模型都原生支持可靠的 JSON 模式输出。像 OpenAI 的gpt-4-turbo系列提供了response_format: { "type": "json_object" }参数，但很多其他模型（特别是开源模型和某些专用模型）要么不支持，要么支持得很差。即使支持，对于复杂的嵌套结构、联合类型（oneOf,anyOf）或数组，输出也经常不稳定。

BAML 引入了其核心技术之一：SAP（Schema-Aligned Parsing，模式对齐解析）算法。这套算法让 BAML 能够从任何 LLM 的文本输出中，可靠地解析出符合预定模式的结构化数据，即使模型在输出中夹杂了 Markdown、推理链（Chain-of-Thought）或其他自由文本。

它是如何工作的？我们不用深究其数学细节，但可以理解其核心思想：

1. 提示增强：BAML 在编译时，会根据你定义的返回类型，自动生成一段精确的自然语言描述，嵌入到系统提示中。这段描述旨在“引导”模型按照所需的结构进行思考和组织答案。
2. 灵活解析：SAP 算法接收模型的原始文本输出，它不是简单地寻找一个 JSON 块。它会尝试理解文本的语义，识别出与目标模式对应的部分。例如，即使模型这样回复：

   用户想结束对话。我认为这是一个合适的时机。 {"action": "stop"} 以上就是我的判断。

   SAP 算法也能准确地从中提取出{"action": "stop"}这个 JSON 对象，并将其映射到StopTool类型。
3. 重试与降级：如果首次解析失败，BAML 可以根据配置的重试策略，自动用更明确的指令重新提问，或者尝试不同的解析路径。

这意味着，只要一个模型能理解指令并生成文本，你就能用 BAML 让它进行可靠的结构化输出。这在实践中带来了巨大的灵活性：

• 模型选型自由：你可以立即使用最新的模型（如 DeepSeek-R1, OpenAI o1），而无需等待其官方支持函数调用。
• 成本优化：你可以为不同的任务选择性价比最高的模型，而不受其原生功能限制。
• 一致性：无论底层模型如何更换，你上层的业务逻辑代码（基于 BAML 生成的类型化接口）都完全不需要改动。

// 你可以自信地为任何模型使用复杂的返回类型 function AnalyzeDocument(doc: string) -> AnalysisResult { client "anthropic/claude-3-haiku" // 即使 Claude 3 Haiku 没有官方工具调用 // 或者使用本地的 Ollama 模型 // client "ollama/llama3.2" prompt #" Analyze the following document and extract information. {{ ctx.output_format }} Document: {{ doc }} "# } class AnalysisResult { summary string entities Entity[] sentiment "positive" | "negative" | "neutral" } class Entity { name string type "PERSON" | "ORG" | "LOCATION" }

7. 生产级特性：故障转移、重试与多模型策略

在实际生产环境中，直接调用一个 LLM API 是远远不够的。我们需要考虑：

• 容错：某个模型暂时不可用或返回错误怎么办？
• 降级：如果主模型太贵或太慢，有没有备选？
• 负载均衡：如何在多个模型或 API 端点间分配请求？
• 重试：对于可重试的错误（如速率限制、临时过载），应该重试几次？

在传统代码中，实现这些特性意味着要写大量的try-catch块、配置管理和状态维护代码。而在 BAML 中，这些都可以通过声明式的配置来完成。

7.1 故障转移与回退策略

你可以在 BAML 函数中定义一个fallback策略。当主模型失败时，会自动尝试备选模型。

function AnswerQuestion(question: string) -> string { // 主模型 client "openai/gpt-4o" // 备选模型列表，按顺序尝试 fallback [ "openai/gpt-4o-mini", "anthropic/claude-3-sonnet" ] prompt #" Answer the following question concisely. Question: {{ question }} "# }

7.2 重试策略

你可以配置针对特定错误的重试行为，比如在遇到速率限制时等待并重试。

function SummarizeText(text: string) -> string { client "openai/gpt-4o" // 配置重试策略 retry_policy { // 遇到这些错误码时重试 on_status: [429, 500, 502, 503] // 最多重试 3 次 max_retries: 3 // 使用指数退避策略，初始延迟 1 秒 strategy: exponential_backoff(initial_delay_ms: 1000, max_delay_ms: 10000) } prompt #" Summarize the following text. Text: {{ text }} "# }

7.3 模型轮询

对于负载均衡或 A/B 测试，你可以使用round_robin策略，让请求在多个模型间轮询。

function GenerateTag(content: string) -> string[] { // 在多个性能相近但成本不同的模型间轮询 round_robin [ "openai/gpt-4o-mini", "anthropic/claude-3-haiku", "google/gemini-1.5-flash" ] prompt #" Generate relevant tags for this content. Content: {{ content }} "# }

所有这些策略都是在 BAML 文件里静态定义的，编译器会生成相应的鲁棒性代码。你的业务逻辑代码依然保持简洁，b.GenerateTag(content)，但背后已经具备了生产级的韧性。

实操心得：将策略配置从业务代码中剥离出来，集中到 BAML 文件里管理，是一个最佳实践。这让你能统一团队所有提示的可靠性标准，并且当需要调整策略时（比如增加重试次数），只需修改一处，所有相关函数都会生效。

8. 构建流式 UI：与前端框架的深度集成

现代 AI 应用离不开流畅的用户体验，而流式响应是其中关键。BAML 不仅在后端支持流式，还为前端框架提供了深度集成方案，特别是Next.js/React。

BAML 可以生成一套完整的TypeScript 类型定义和 React Hooks，让你在前端也能享受端到端的类型安全。

后端（Python FastAPI 示例）:

from fastapi import FastAPI from fastapi.responses import StreamingResponse from baml_client import b import asyncio app = FastAPI() async def stream_chat_response(messages): stream = b.stream.ChatAgent(messages, "happy") async for partial in stream: # 将部分结果以 SSE 格式 yield 出去 if isinstance(partial, ReplyTool) and partial.response: yield f"data: {json.dumps({'type': 'token', 'data': partial.response})}\n\n" elif isinstance(partial, StopTool): yield f"data: {json.dumps({'type': 'stop'})}\n\n" yield "data: [DONE]\n\n" @app.post("/chat") async def chat_endpoint(request: ChatRequest): return StreamingResponse( stream_chat_response(request.messages), media_type="text/event-stream" )

前端（Next.js with Generated Hooks）: BAML 编译后，会生成一个baml_client包供前端使用。

// 使用 BAML 生成的 React Hook import { useStreamingFunction } from '@/baml_client/react'; import { ChatAgent } from '@/baml_client/functions'; // 生成的函数定义 function ChatComponent() { const [messages, setMessages] = useState<Message[]>([]); const [input, setInput] = useState(''); // useStreamingFunction 是一个封装好的 Hook，处理了连接、流式解析和状态管理 const { invoke, isStreaming, currentResponse } = useStreamingFunction(ChatAgent); const handleSend = async () => { const newMessages = [...messages, { role: 'user' as const, content: input }]; setMessages(newMessages); setInput(''); // 调用函数。流式结果会通过 `currentResponse` 实时更新 await invoke({ messages: newMessages, tone: 'happy' }); // 流式结束后，`currentResponse` 就是最终解析好的对象 if (currentResponse && 'response' in currentResponse) { setMessages(prev => [...prev, { role: 'assistant', content: currentResponse.response }]); } }; return ( <div> {/* 消息列表 */} {/* 输入框 */} <button onClick={handleSend} disabled={isStreaming}> {isStreaming ? 'Thinking...' : 'Send'} </button> {/* 可以实时显示 currentResponse 的部分内容 */} {isStreaming && currentResponse?.response && ( <div>Assistant is typing: {currentResponse.response}</div> )} </div> ); }

通过这种方式，前端开发者无需关心 SSE 连接、数据块拼接和复杂的 JSON 解析。他们只需要使用类型安全的 Hook 和函数，就能构建出体验优秀的流式 AI 交互界面。BAML 生成的类型定义确保了从后端到前端数据结构的一致性，极大地减少了前后端联调的摩擦。

9. 项目现状、生态与未来展望

BAML 是一个开源项目，采用Apache 2.0 许可证，这意味着你可以在商业项目中自由使用它。它的核心编译器由 Rust 编写，确保了高性能和可靠性。项目处于非常活跃的开发状态，团队每周都会发布更新。

核心优势总结：

1. 开发者体验至上：从语言设计到 IDE 工具链，一切围绕提升提示迭代速度和开发幸福感构建。
2. 真正的类型安全：从 BAML 定义到生成的各种语言客户端，全程类型安全，将运行时错误提前到编译时。
3. 模型无关与强大解析：SAP 算法让你摆脱对模型原生功能绑定的依赖，自由选型。
4. 声明式配置：故障转移、重试、流式等生产级特性通过配置即可实现，无需编写冗长的胶水代码。
5. 无缝集成：“仅管理提示层”的定位让它能轻松融入现有技术栈。

当前支持的生态：

• 语言：Python、TypeScript/JavaScript 提供一流支持（生成类型化客户端）。Ruby、Go、REST API 等也在支持中。
• 模型提供商：OpenAI、Anthropic、Google Gemini & Vertex AI、AWS Bedrock、Azure OpenAI，以及任何 OpenAI 兼容的 API（如 Ollama、OpenRouter、vLLM、LM Studio、Together AI 等）。
• 编辑器：VS Code 和 JetBrains IDE 有官方扩展，其他编辑器可通过 CLI 使用。

给开发者的建议： 如果你正在或计划开发涉及复杂提示、多步骤工作流、智能体或需要稳定结构化输出的 LLM 应用，BAML 绝对值得你花一个下午的时间尝试。你可以从一个小功能开始，比如用 BAML 重写你项目中最复杂、最不稳定的一段提示词逻辑。亲自体验一下在 IDE 里实时测试、一键切换模型、并享受完整类型提示的感觉。它可能不会解决你所有的问题，但它为解决“提示工程”这个核心痛点提供了一套极具说服力的工程化方案。至少对我来说，它已经彻底改变了我构建 AI 功能的方式。