1. 项目概述从“提示工程”到“工程化提示”如果你在过去一年里深度参与过基于大语言模型LLM的应用开发大概率经历过这样的场景为了调用某个API你写了几十行代码来处理HTTP请求、解析JSON响应、处理可能的错误和重试最后还要把返回的文本小心翼翼地塞进你的业务逻辑里。更头疼的是当你需要切换模型提供商比如从OpenAI换到Anthropic或Google或者只是想调整一下提示词Prompt的结构和参数却发现这些逻辑像藤蔓一样缠绕在你的核心业务代码中牵一发而动全身。“Mirascope”这个项目正是为了解决这种痛苦而生的。它不是一个简单的SDK包装器而是一个旨在将“提示工程”这一看似随意、实验性的工作提升到“工程化”高度的全栈框架。其核心哲学是提示Prompt及其相关的调用逻辑应该像数据库模型Model或API端点Endpoint一样成为应用中可以清晰定义、方便测试、易于维护和复用的第一公民。简单来说Mirascope让你能用声明式的、面向对象的方式来定义你的提示模板、调用参数以及后处理逻辑。它抽象了底层不同LLM提供商如OpenAI, Anthropic, Gemini, Groq等的API差异提供了统一的、类型安全的接口。更重要的是它内置了强大的工具调用Function/Tool Calling支持、流式响应处理、异步操作、以及可观测性日志、追踪等现代应用开发所必需的特性。你可以把它理解为LLM应用领域的“ORM”对象关系映射或“Web框架”它帮你处理了所有繁琐的“管道”plumbing代码让你能更专注于构建真正的业务价值。2. 核心设计理念与架构拆解2.1 声明式与面向对象将提示词提升为“一等公民”传统开发中提示词往往以字符串模板的形式散落在代码各处或者存放在配置文件里。这种方式有几个明显缺陷缺乏结构难以管理复杂的、多部分的提示如系统指令、用户消息、上下文示例。难以复用和测试一个提示的修改可能影响多处且对其进行单元测试非常不便。与调用逻辑耦合提示内容、模型参数、解析逻辑常常混在一起。Mirascope的核心抽象是BasePrompt类。通过继承这个类并利用Python的类型注解和Pydantic你可以定义一个结构清晰、自包含的提示单元。from mirascope import BasePrompt, OpenAICallParams, OpenAICallResponse from pydantic import Field class RecipeGeneratorPrompt(BasePrompt): template SYSTEM: 你是一位资深厨师擅长根据现有食材创作美味、易操作的菜谱。 USER: 我手头有以下食材{ingredients}。 请为我设计一道菜并满足以下要求 - 菜系风格{cuisine_style} - 烹饪时间不超过{max_cooking_time}分钟 - 难度级别{difficulty} 请以JSON格式回复包含“菜名”、“所需完整食材清单”、“步骤”和“预估时间”。 ingredients: str cuisine_style: str Field(default中式) max_cooking_time: int Field(default30, ge10, le120) difficulty: str Field(default初级, pattern^(初级|中级|高级)$) call_params OpenAICallParams(modelgpt-4o, temperature0.7, max_tokens1000) prompt RecipeGeneratorPrompt( ingredients鸡胸肉、青椒、洋葱、大蒜, cuisine_style家常, max_cooking_time25 )在这个例子中RecipeGeneratorPrompt类不仅定义了提示模板还通过Pydantic字段定义了模板变量的类型、默认值和验证规则如max_cooking_time必须在10到120之间。call_params属性则绑定了调用OpenAI API时使用的参数。这种设计使得一个提示单元具备了完整的自描述性可以独立进行实例化、验证和调用。提示这种面向对象的设计模式特别适合在团队协作中建立“提示库”。你可以将不同业务域的提示如客服回复、内容摘要、代码生成定义为不同的类存放在统一的模块中方便查找、复用和版本管理。2.2 统一的提供者抽象告别供应商锁定LLM生态日新月异今天用GPT-4明天可能就需要接入Claude 3或Gemini Pro。如果代码里到处都是openai.ChatCompletion.create这样的硬编码迁移成本会非常高。Mirascope通过BaseCall抽象层解决了这个问题。对于上面定义的BasePrompt你可以使用对应的Call类来执行而无需关心底层是哪个供应商。from mirascope import OpenAI # 使用OpenAI调用 response: OpenAICallResponse OpenAI().call(prompt) recipe response.content print(recipe) # 如果需要切换到Anthropic假设已配置API密钥 from mirascope import Anthropic class RecipeGeneratorPromptClaude(RecipeGeneratorPrompt): call_params AnthropicCallParams(modelclaude-3-sonnet-20240229, max_tokens1024) prompt_claude RecipeGeneratorPromptClaude(...) response_claude Anthropic().call(prompt_claude)框架内部处理了不同API的请求格式、错误码映射和响应解析。你只需要更换Call类和相应的call_params业务逻辑代码几乎无需改动。这为成本优化、性能对比和故障转移提供了极大的灵活性。2.3 深度集成的工具调用让LLM成为“执行者”工具调用Function/Tool Calling是让LLM与外部世界交互、执行具体操作的关键能力。Mirascope对此的支持堪称一流它让工具的定义和调用变得异常优雅和类型安全。首先你可以用Pydantic模型来定义工具的参数结构from mirascope import BaseTool from pydantic import Field from typing import Literal class GetWeather(BaseTool): 获取指定城市的当前天气信息。 city_name: str Field(..., description城市名称例如北京、上海) unit: Literal[celsius, fahrenheit] Field(celsius, description温度单位) def call(self) - str: # 这里是模拟的实现实际项目中会调用真实的天气API if self.city_name 北京: return f{self.city_name}当前天气晴温度25{ if self.unit celsius else °F}。 return f未找到{city_name}的天气信息。然后在你的提示类中你可以通过tools属性声明可用的工具from mirascope import BasePrompt, OpenAICallParams class WeatherAssistantPrompt(BasePrompt): template USER: {query} query: str call_params OpenAICallParams(modelgpt-4o, temperature0) tools [GetWeather] # 声明可用的工具 prompt WeatherAssistantPrompt(query北京今天天气怎么样)最后使用OpenAI().call_with_tools进行调用。框架会自动处理工具描述的生成、LLM对工具的选择、参数的解析以及工具的执行from mirascope import OpenAI response OpenAI().call_with_tools(prompt) if response.tool_call: # 如果LLM决定调用工具 tool response.tool_call print(f模型决定调用工具{tool.__class__.__name__}) print(f工具参数{tool.model_dump()}) # 执行工具 result tool.call() print(f工具执行结果{result}) # 你可以选择将结果再次发送给LLM进行后续对话 else: print(f模型直接回复{response.content})这种深度集成意味着你不再需要手动拼接复杂的工具描述JSON也不需要自己写逻辑去解析LLM返回的function_call字段。Mirascope帮你完成了所有繁重的工作你只需要关注工具本身的业务逻辑实现。实操心得工具的参数描述Field(..., description...)至关重要。清晰、具体的描述能极大提高LLM选择正确工具和填充正确参数的准确率。建议像编写API文档一样认真对待这些描述。3. 高级特性与实战应用解析3.1 流式处理与实时反馈对于生成较长内容或需要实时显示的场景流式响应Streaming是必备功能。Mirascope的流式调用设计得非常直观。from mirascope import OpenAI prompt WeatherAssistantPrompt(query用一段话描述夏天的氛围。) stream OpenAI().stream(prompt) # 注意这里是 .stream for chunk in stream: if chunk.content: # 内容块 print(chunk.content, end, flushTrue) # 逐块打印模拟打字机效果 # 流式响应中也支持工具调用chunk.tool_call 会包含部分信息stream方法返回一个迭代器每次产生一个OpenAIStreamChunk对象。你可以实时处理其中的content来构建前端打字机效果或者处理tool_call的增量信息。这对于构建聊天应用或需要长时间运行的文本生成任务来说能显著提升用户体验。3.2 消息历史管理与对话上下文多轮对话是LLM应用的常态。Mirascope通过BaseMessage和messages属性来优雅地管理对话历史。from mirascope import BasePrompt, OpenAICallParams, BaseMessage from typing import List class ChatPrompt(BasePrompt): template SYSTEM: 你是一个乐于助人的助手。 {message_history} USER: {current_query} current_query: str message_history: List[BaseMessage] [] # 用于存储历史消息 call_params OpenAICallParams(modelgpt-4o) property def messages(self) - List[BaseMessage]: # 将系统提示、历史消息和当前用户查询组合成API所需的格式 system_msg BaseMessage(rolesystem, content你是一个乐于助人的助手。) history_msgs self.message_history user_msg BaseMessage(roleuser, contentself.current_query) return [system_msg] history_msgs [user_msg] # 使用示例 prompt ChatPrompt(current_query你好) response OpenAI().call(prompt) first_reply response.content # 将第一轮的用户消息和助手回复存入历史 new_history [ BaseMessage(roleuser, content你好), BaseMessage(roleassistant, contentfirst_reply) ] # 进行第二轮对话 prompt2 ChatPrompt(current_query我刚才说了什么, message_historynew_history) response2 OpenAI().call(prompt2) print(response2.content) # 助手能根据历史上下文回答通过重写messages属性你可以完全控制发送给LLM的消息列表结构。结合Pydantic模型你可以轻松地将整个对话历史可能包含工具调用结果等复杂消息序列化存储到数据库并在下次会话中还原实现有状态的、连续的对话体验。3.3 可观测性与调试让黑盒变得透明LLM应用调试一直是个挑战。Mirascope内置了与logfire由Pydantic团队开发或langfuse等可观测性平台的集成可以自动记录每次调用的详细信息。import logfire from mirascope import OpenAI logfire.configure() # 初始化logfire logfire.instrument_mirascope() # 启用对Mirascope的自动检测 prompt RecipeGeneratorPrompt(...) response OpenAI().call(prompt)启用后每次API调用、工具执行都会被自动追踪。你可以在logfire的控制台看到请求和响应的完整内容包括提示模板、填充后的消息、模型参数。令牌使用量输入/输出。耗时和延迟。工具调用的参数和结果。任何发生的错误。这对于监控成本、分析性能瓶颈、复现和调试生产环境中的问题、以及评估提示词效果A/B测试都至关重要。你不再需要手动在代码里打日志框架提供了开箱即用的可观测性。4. 从零构建一个智能任务代办应用让我们通过一个更复杂的实战项目将Mirascope的各项特性串联起来。我们将构建一个“智能任务解析器”它能理解用户用自然语言描述的任务如“明天下午三点提醒我和老王开会”并自动调用相应的工具创建日历事件、设置提醒、添加到待办列表。4.1 步骤一定义工具集首先我们定义应用需要的几个核心工具。from mirascope import BaseTool from pydantic import Field, field_validator from datetime import datetime from typing import Optional import uuid class CreateCalendarEvent(BaseTool): 在日历中创建一个新事件。 title: str Field(..., description事件的标题) start_time: datetime Field(..., description事件的开始时间) end_time: Optional[datetime] Field(None, description事件的结束时间如未指定则默认为开始时间后1小时) description: Optional[str] Field(None, description事件的详细描述) location: Optional[str] Field(None, description事件地点) field_validator(end_time) classmethod def default_end_time(cls, v, info): if v is None: # 如果未提供结束时间默认为开始时间后1小时 start_time info.data.get(start_time) if start_time: from datetime import timedelta return start_time timedelta(hours1) return v def call(self) - str: # 模拟创建日历事件实际应接入Google Calendar、Outlook等API event_id str(uuid.uuid4())[:8] return f日历事件创建成功事件ID: {event_id}标题{self.title}时间{self.start_time.strftime(%Y-%m-%d %H:%M)}。 class SetReminder(BaseTool): 设置一个一次性提醒。 task: str Field(..., description需要被提醒的事项) remind_time: datetime Field(..., description提醒触发的时间) priority: str Field(medium, description提醒优先级low, medium, high) def call(self) - str: # 模拟设置提醒 return f提醒已设置将在 {self.remind_time.strftime(%Y-%m-%d %H:%M)} 提醒您{self.task} (优先级: {self.priority}) class AddToTodoList(BaseTool): 添加一项任务到待办事项列表。 item: str Field(..., description待办事项的具体内容) due_date: Optional[datetime] Field(None, description截止日期) category: Optional[str] Field(None, description任务分类如工作、个人、购物) def call(self) - str: # 模拟添加到待办列表 return f待办事项已添加{self.item}。分类{self.category or 无}截止日期{self.due_date.strftime(%Y-%m-%d) if self.due_date else 无}。4.2 步骤二构建智能提示与调用逻辑接下来我们创建一个能理解用户意图并选择合适工具的提示类。from mirascope import BasePrompt, OpenAICallParams from typing import List class TaskParserPrompt(BasePrompt): 智能任务解析器。分析用户的自然语言输入判断其意图并调用相应的工具。 用户可能想创建日历事件、设置提醒或添加待办事项。 template SYSTEM: 你是一个任务解析助手。请分析用户的输入判断他们想做什么并调用最合适的工具来完成任务。 你可以使用的工具 1. CreateCalendarEvent: 当用户提到会议、约会、活动等需要安排在特定时间的事件时使用。 2. SetReminder: 当用户明确要求“提醒”或“记得”做某事时使用。 3. AddToTodoList: 当用户提到需要完成一项任务但没有明确时间或需要记录到清单时使用。 如果输入含糊不清无法确定意图或者输入不构成一个可执行的任务请直接回复用户要求澄清。 当前时间参考{current_time} 用户输入{user_input} user_input: str current_time: datetime Field(default_factorydatetime.now) call_params OpenAICallParams( modelgpt-4o, temperature0.1, # 较低的温度使工具调用决策更稳定 response_format{type: json_object} # 强制JSON输出便于解析工具调用 ) tools [CreateCalendarEvent, SetReminder, AddToTodoList] # 注册可用工具4.3 步骤三实现主应用逻辑现在我们将所有部分组合起来形成一个完整的处理循环。from mirascope import OpenAI import json def process_user_task(input_text: str): 处理用户任务输入的主函数。 print(f\n用户输入: {input_text}) # 1. 创建提示实例 prompt TaskParserPrompt(user_inputinput_text) # 2. 调用LLM并允许其使用工具 client OpenAI() try: response client.call_with_tools(prompt) except Exception as e: print(f调用API时发生错误: {e}) return # 3. 处理响应 if response.tool_call: # LLM决定调用工具 tool response.tool_call print(f 解析意图: 模型决定调用工具 {tool.__class__.__name__}) print(f 工具参数: {tool.model_dump_json(indent2)}) try: # 执行工具 result tool.call() print(f✅ 工具执行结果: {result}) # 这里可以将结果返回给用户或者进一步处理 return result except Exception as e: print(f❌ 工具执行失败: {e}) return f操作失败: {e} else: # LLM直接回复可能是要求澄清或无法处理 print(f 模型直接回复: {response.content}) return response.content # 测试几个例子 if __name__ __main__: test_inputs [ 明天下午三点提醒我和老王开会地点在二号会议室。, 记得下周一早上九点给客户发项目报告。, 把买牛奶加到我的购物清单里。, 今天天气怎么样, # 无法处理的输入 ] for inp in test_inputs: result process_user_task(inp) print(- * 50)运行结果预期对于第一个输入模型应调用CreateCalendarEvent工具并正确解析出标题、时间、地点。对于第二个输入可能调用SetReminder因为是“记得”做某事或CreateCalendarEvent因为是具体时间点的事件这取决于模型对上下文的理解。对于第三个输入应调用AddToTodoList。对于第四个输入由于不构成任务模型应直接回复无法处理或要求澄清。这个示例展示了Mirascope如何将复杂的自然语言理解、工具决策和执行业务逻辑的过程封装成清晰、可维护的代码流。你可以轻松地在此基础上扩展更多工具如发送邮件、创建GitHub Issue、查询数据库构建出功能强大的智能体Agent应用。5. 部署、测试与最佳实践5.1 配置管理与环境变量在实际项目中API密钥、模型选择等配置不应硬编码。Mirascope遵循常见的环境变量模式。# .env 文件 OPENAI_API_KEYsk-... ANTHROPIC_API_KEYsk-ant-... LOGTAIL_API_KEY... # 用于logfire等可观测性平台 DEFAULT_MODELgpt-4o在代码中可以通过os.getenv或pydantic-settings来管理from mirascope import OpenAICallParams from pydantic_settings import BaseSettings class Settings(BaseSettings): openai_api_key: str default_model: str gpt-4o class Config: env_file .env settings Settings() class MyPrompt(BasePrompt): template ... call_params OpenAICallParams(modelsettings.default_model, api_keysettings.openai_api_key)5.2 单元测试与集成测试Mirascope的面向对象设计让测试变得简单。你可以模拟mockAPI响应专注于测试提示逻辑和工具调用。import pytest from unittest.mock import Mock, patch from mirascope import OpenAICallResponse from your_app import TaskParserPrompt, process_user_task def test_task_parser_prompt_creation(): 测试提示实例化是否正确填充模板。 prompt TaskParserPrompt(user_input设置一个提醒) assert 设置一个提醒 in prompt.template assert prompt.current_time is not None patch(your_app.OpenAI) def test_calendar_event_tool_call(mock_openai): 测试模型正确调用日历工具。 # 1. 模拟一个返回工具调用的LLM响应 fake_response Mock(specOpenAICallResponse) fake_tool CreateCalendarEvent( title团队周会, start_timedatetime(2024, 6, 15, 14, 0), location一号会议室 ) fake_response.tool_call fake_tool fake_response.content None mock_client Mock() mock_client.call_with_tools.return_value fake_response mock_openai.return_value mock_client # 2. 执行被测试函数 result process_user_task(下周一下午两点团队周会在一号会议室) # 3. 验证 mock_client.call_with_tools.assert_called_once() # 验证返回结果中包含预期的成功信息 assert 日历事件创建成功 in result assert 团队周会 in result5.3 性能优化与成本控制缓存对于内容确定、结果可复用的提示如文本标准化、分类考虑对LLM响应进行缓存。可以使用functools.lru_cache或Redis等外部缓存。批处理如果需要处理大量相似的提示如批量生成产品描述可以探索是否支持批处理APIMirascope可能提供或底层供应商支持以减少网络开销。降级策略在call_params中配置备用模型。例如主要使用gpt-4o但在达到速率限制或需要降低成本时自动降级到gpt-3.5-turbo。令牌预算密切关注response.usage如果提供商返回。为不同的提示设置大致的令牌上限并在提示设计中通过指令如“请用不超过100字总结”进行控制。5.4 版本管理与提示迭代提示词是不断迭代优化的。建议为每个BasePrompt子类添加版本号或日期后缀如SalesEmailV2。使用配置管理工具或特性开关逐步将新提示推向生产环境。利用Mirascope的可观测性功能收集新老提示在成功率、输出质量、成本等方面的对比数据用数据驱动决策。Mirascope通过其严谨的设计将LLM应用开发从“脚本小子”式的粘合代码提升到了软件工程的高度。它强迫开发者思考抽象、边界和测试最终产出的是更健壮、更易维护、也更容易协作的代码库。虽然初期需要花一点时间学习其模式但长远来看这对于构建可持续演进的生产级AI应用是绝对值得的投资。