企业官网建设流程全解析

1. 项目概述：Magentic，一个让LLM与Python无缝协作的框架

如果你和我一样，在尝试将大型语言模型（LLM）集成到自己的Python应用时，常常感到一种割裂感——一边是灵活但“原始”的API调用，需要手动拼接提示词、解析JSON、处理错误；另一边是你精心设计的业务逻辑和数据结构。这种来回切换不仅让代码变得冗长，更让整个开发流程变得笨重，难以维护和迭代。今天要聊的Magentic，正是为了解决这个痛点而生的。

简单来说，Magentic是一个Python库，它的核心目标是把LLM的能力变成像调用普通Python函数一样自然。你不用再写一大堆client.chat.completions.create，也不用担心返回的JSON字符串解析失败。它通过装饰器（如@prompt和@chatprompt），让你用定义函数签名和类型注解的方式，直接“声明”一个由LLM驱动的函数。这个函数能返回结构化的数据（比如Pydantic模型实例），能流式输出，能自动调用工具（函数），甚至能通过链式调用构建复杂的智能体（Agent）系统。它支持OpenAI、Anthropic、Ollama等多种后端，并且天生与Pydantic和Python的类型系统深度集成，让IDE的自动补全和类型检查器（如mypy）也能很好地工作。

在我看来，Magentic的价值在于它极大地提升了开发“AI原生应用”的体验和效率。它不是一个试图封装一切、给你一个黑盒Agent的框架，而是一个增强你现有Python代码能力的工具。你可以从小处着手，比如用一个@prompt函数来润色文案或提取信息；也可以构建复杂的多步骤工作流，让LLM自动决策调用哪个工具，并处理中间结果。接下来，我会结合自己的使用经验，从设计思路到实战细节，为你拆解这个框架。

2. 核心设计理念与架构解析

2.1 为什么是“函数即提示词”？

Magentic最核心的设计，是将一个LLM提示词模板与一个Python函数绑定。当你调用这个函数时，框架内部做了以下几件事：

1. 模板渲染：将函数参数的值，填充到装饰器中定义的字符串模板的对应位置（{参数名}）。
2. LLM调用：将渲染后的完整提示词，发送给配置好的LLM（如GPT-4）。
3. 输出解析与结构化：根据函数返回值的类型注解（比如str、List[str]，或一个自定义的Pydantic模型），将LLM返回的文本解析成对应的Python对象。
4. 返回结果：将这个Python对象作为函数调用的结果返回给你。

这个设计的精妙之处在于，它利用了Python开发者最熟悉的抽象单元——函数。一个函数有明确的输入（参数）和输出（返回值）。Magentic把LLM的“黑魔法”封装在这个熟悉的接口后面。对你来说，你只是在调用一个函数result = my_llm_function(some_input)，至于背后是GPT-4还是Claude在干活，返回的是文本还是对象，你都不需要关心。

这带来了几个直接的好处：

• 代码清晰：业务逻辑和AI调用逻辑分离。你的主流程代码里没有散落的API调用和字符串处理。
• 类型安全：得益于Pydantic，你可以为LLM的输出定义严格的模式（Schema）。如果LLM返回的内容不符合模式，在解析阶段就会抛出验证错误，而不是让一个格式错误的数据污染你的后续流程。
• 可测试性：虽然LLM本身具有不确定性，但你可以为这些函数编写单元测试，模拟其返回结果，从而测试集成这些函数后的业务逻辑是否正确。
• 可组合性：一个@prompt函数可以像普通函数一样，被另一个@prompt函数调用，这为构建复杂的、多步骤的Agent逻辑奠定了基础。

2.2 与主流方案的对比：LangChain vs. LlamaIndex vs. Magentic

在LLM应用开发领域，LangChain和LlamaIndex是两位重量级选手。它们和Magentic的设计哲学有显著不同。

• LangChain：更像一个“全家桶”或“乐高积木”工具箱。它提供了海量的组件（Chains, Agents, Tools, Memory等），强调通过连接这些标准化组件来构建应用。它的抽象层次很高，功能极其强大，但学习曲线也相对陡峭，有时会感觉为了完成一个简单任务，需要理解和配置相当多的概念。
• LlamaIndex：专注于“数据接入与检索”（RAG）场景。它擅长将你的私有数据（文档、数据库等）进行索引，并为LLM查询提供高效的检索能力。它的核心价值在于解决“如何让LLM使用你的数据”这个问题。
• Magentic：定位非常聚焦，就是**“让LLM调用像函数调用一样简单”**。它不试图解决RAG（那是LlamaIndex的领域），也不提供那么多现成的、复杂的Agent范式（那是LangChain的领域）。它解决的是集成层的基础体验问题：如何用最Pythonic、最类型安全的方式，把一次LLM交互封装起来。

如何选择？

• 如果你的核心需求是快速构建一个基于私有知识的问答系统，LlamaIndex是首选。
• 如果你需要构建一个高度定制化、涉及复杂流程和多种工具调用的智能体，并且不介意一定的学习成本，LangChain提供了最丰富的可能性。
• 如果你希望以最小的心智负担，将LLM能力快速、优雅地嵌入到一个现有的Python项目或新项目的某些模块中，或者你崇尚“简单即美”的哲学，Magentic会给你带来惊喜。它特别适合作为你技术栈中的“胶水”，将LLM能力粘合到你的核心业务逻辑上。

一个很形象的类比：LangChain像是一个功能齐全的厨房，有烤箱、洗碗机、料理机；LlamaIndex是一个专业的食材处理台和冷柜；而Magentic，则是一把极其锋利、称手的主厨刀。对于很多烹饪任务（开发场景），一把好刀往往就够了。

2.3 核心组件深度剖析

Magentic的架构围绕几个核心装饰器和类展开，理解它们的关系至关重要。

1. @prompt装饰器：这是最基础的构建块。它接受一个字符串模板，并基于函数的返回类型注解来解析LLM的输出。它处理的是“单轮对话”场景。
2. @chatprompt装饰器：这是@prompt的升级版，用于多轮对话或需要提供上下文（如系统指令、少样本示例）的场景。它接受一个消息列表（SystemMessage,UserMessage,AssistantMessage）作为模板，能更精细地控制与LLM的交互。
3. FunctionCall对象：当你在@prompt中传入functions参数时，LLM可能会选择调用其中一个函数。此时，@prompt函数返回的不是最终结果，而是一个FunctionCall对象。这个对象封装了“要调用哪个函数”以及“用什么参数调用”的信息。你需要显式地调用这个对象（output()）来执行真正的函数，并获得其结果。这给了开发者最大的控制权。
4. @prompt_chain装饰器：这是构建多步Agent的关键。它会自动处理FunctionCall的解析和执行，并将执行结果作为新的上下文，再次发送给LLM，循环直到LLM给出最终的非函数调用回答。这实现了简单的“思考-行动-观察”循环。
5. ChatModel类及其子类：这是与不同LLM提供商（OpenAI, Anthropic, Mistral等）交互的抽象层。你可以通过配置ChatModel实例来指定使用哪个模型、什么参数（温度、最大token数等）。

这些组件的关系是层层递进的：@prompt和@chatprompt定义了单次交互；FunctionCall实现了工具调用；@prompt_chain利用工具调用实现了自动化的多步推理。而所有的装饰器，最终都依赖于一个ChatModel实例来完成与LLM的通信。

3. 从零开始：环境配置与基础用法实战

3.1 安装与基础配置

安装Magentic非常简单，推荐使用uv或pip。

# 使用 pip pip install magentic # 或使用更现代的 uv (推荐，管理依赖和虚拟环境更高效) uv add magentic

安装后，最关键的一步是配置LLM API密钥。Magentic默认使用OpenAI的后端。

# 在终端中设置环境变量 (Linux/macOS) export OPENAI_API_KEY='sk-your-openai-api-key-here' # Windows (PowerShell) $env:OPENAI_API_KEY='sk-your-openai-api-key-here'

你也可以在Python代码中直接设置，但这通常不是最佳实践，因为可能会意外将密钥提交到代码仓库。

import os os.environ["OPENAI_API_KEY"] = "sk-..."

注意：永远不要将真实的API密钥硬编码在源代码中或提交到版本控制系统（如Git）。使用环境变量或专业的密钥管理服务（如AWS Secrets Manager, HashiCorp Vault）是必须遵守的安全规范。

3.2@prompt装饰器：你的第一个AI函数

让我们从一个最简单的例子开始，感受一下Magentic的魔力。

from magentic import prompt @prompt('将这句话翻译成中文: {text}') def translate_to_chinese(text: str) -> str: """一个简单的翻译函数，函数体通常用 ... 省略。""" ... # 调用它！ result = translate_to_chinese("Hello, world! This is Magentic.") print(result) # 输出可能是：你好，世界！这是Magentic。

看，这就完成了。你定义了一个函数translate_to_chinese，它接受一个text参数。@prompt装饰器里的模板字符串{text}会被实际传入的参数值替换。函数返回类型注解是str，所以Magentic会要求LLM生成一段文本，并作为字符串返回。

但Magentic的强大之处在于结构化输出。假设我们想让LLM分析一段产品评论，并提取结构化信息：

from magentic import prompt from pydantic import BaseModel from typing import Literal class ProductReview(BaseModel): sentiment: Literal["positive", "neutral", "negative"] summary: str key_points: list[str] rating: int # 假设是1-5分 @prompt(""" 请分析以下产品评论，并提取信息。 评论内容：{review_text} """) def analyze_review(review_text: str) -> ProductReview: ... review = analyze_review(""" 这款手机的屏幕太棒了，色彩鲜艳，亮度高，户外也能看清。 电池续航也不错，正常使用一天一充。就是价格有点贵，而且系统偶尔会卡顿。 """) print(f"情感: {review.sentiment}") # 输出: 情感: positive (可能是积极偏中性) print(f"总结: {review.summary}") # 输出: 总结: 屏幕出色，续航好，但价格高且系统偶有卡顿。 print(f"关键点: {review.key_points}") # 输出: 关键点: ['屏幕色彩好亮度高', '电池续航不错', '价格偏高', '系统偶尔卡顿'] print(f"评分: {review.rating}") # 输出: 评分: 4 (LLM推断的)

现在，analyze_review函数直接返回了一个ProductReview类的实例。你可以像使用任何Python对象一样，访问它的属性（sentiment,summary等）。Pydantic确保了数据的结构符合你的定义。如果LLM返回的文本无法被解析成有效的ProductReview（例如，rating返回了“很好”这样的文字），Magentic会抛出一个验证错误。

实操心得：充分利用Pydantic的字段验证和默认值。例如，可以为rating字段设置一个验证器，确保它在1-5之间，或者为key_points设置一个默认的空列表default_factory=list。这能让你的AI函数更加健壮。

3.3@chatprompt装饰器：复杂的对话与少样本学习

有些任务需要更复杂的提示工程，比如给模型一个角色（系统指令），或者提供几个例子来引导它（少样本学习）。@chatprompt就是为这种场景设计的。

它接受一个消息列表，每条消息都是一个类的实例，如SystemMessage,UserMessage,AssistantMessage。FunctionResultMessage用于在链式调用中传递函数执行结果，通常不手动使用。

from magentic import chatprompt, SystemMessage, UserMessage, AssistantMessage from pydantic import BaseModel class CodeSnippet(BaseModel): language: str code: str explanation: str @chatprompt( SystemMessage("你是一个资深的Python开发助手，擅长编写简洁、高效、符合PEP 8规范的代码。"), UserMessage("写一个函数，计算斐波那契数列的第n项。"), AssistantMessage( CodeSnippet( language="python", code="def fibonacci(n: int) -> int:\n if n <= 1:\n return n\n a, b = 0, 1\n for _ in range(2, n + 1):\n a, b = b, a + b\n return b", explanation="使用迭代法计算，时间复杂度O(n)，空间复杂度O(1)。" ) ), UserMessage("现在，写一个函数，判断一个字符串是否是回文。"), ) def generate_palindrome_checker() -> CodeSnippet: ... snippet = generate_palindrome_checker() print(f"语言: {snippet.language}") print(f"代码:\n{snippet.code}") print(f"解释: {snippet.explanation}")

在这个例子中，我们首先通过SystemMessage设定了AI的角色。然后我们提供了一个UserMessage和AssistantMessage的配对作为示例（少样本），告诉AI我们期望的输入输出格式。最后，我们提出新的UserMessage请求。AI会参考之前的对话历史（尤其是提供的示例）来生成符合CodeSnippet格式的回复。

注意事项：@chatprompt模板中的格式化字段（如{movie}）会被填充到所有类型的消息中（除了FunctionResultMessage）。这意味着你可以在系统消息、用户消息、助手消息中都使用相同的变量，它们会被统一替换。这在构建动态对话模板时非常有用。

4. 进阶功能：流式输出、函数调用与异步并发

4.1 流式输出：实时处理LLM的“思考”

默认情况下，调用一个@prompt函数会阻塞，直到LLM生成完整的响应。对于长文本或需要实时显示的场景，这体验不好。Magentic提供了流式输出支持。

文本流式输出： 通过将返回类型注解为StreamedStr（或异步的AsyncStreamedStr），你可以逐个token地接收输出。

from magentic import prompt, StreamedStr import time @prompt("用大约100字介绍量子计算的基本概念。") def describe_quantum_computing() -> StreamedStr: ... print("开始流式接收：") streamed_response = describe_quantum_computing() for chunk in streamed_response: print(chunk, end='', flush=True) # 逐块打印，模拟打字机效果 time.sleep(0.05) # 稍微延迟，方便观察 print("\n--- 接收完毕 ---")

结构化对象流式输出： 更强大的是，你甚至可以流式接收结构化的对象列表。例如，让LLM生成一个英雄团队，并逐个英雄地返回。

from collections.abc import Iterable from magentic import prompt from pydantic import BaseModel class Superhero(BaseModel): name: str power: str @prompt("生成一个包含5名成员的超级英雄团队，团队主题是‘元素掌控’。") def generate_elemental_team() -> Iterable[Superhero]: ... print("英雄团队正在生成：") for i, hero in enumerate(generate_elemental_team(), 1): print(f"{i}. {hero.name} - 能力：{hero.power}") # 输出可能是： # 1. 焰心 - 能力：操控火焰 # 2. 浪涌 - 能力：控制水流 # 3. 岩盾 - 能力：塑造岩石与大地 # 4. 风语者 - 能力：驾驭狂风 # 5. 雷霆之怒 - 能力：召唤闪电

流式输出对于构建交互式应用（如聊天界面）或处理大量生成内容时特别有用，可以提升用户体验和响应感知。

4.2 函数调用：让LLM使用你的工具

这是构建智能体（Agent）的核心。你可以将普通的Python函数（或异步函数）作为“工具”提供给LLM，LLM在推理后，可以决定调用哪个工具，并生成调用参数。

from typing import Literal from magentic import prompt, FunctionCall import requests # 定义两个工具函数 def get_weather(city: str, unit: Literal["celsius", "fahrenheit"] = "celsius") -> str: """获取指定城市的当前天气。这是一个模拟函数。""" # 这里应该调用真实的天气API，例如 OpenWeatherMap print(f"[模拟调用] 查询{city}的天气，单位：{unit}") # 模拟返回 weather_data = { "Beijing": {"temp": 22, "condition": "Sunny"}, "London": {"temp": 15, "condition": "Cloudy"}, } data = weather_data.get(city, {"temp": 20, "condition": "Unknown"}) return f"{city}当前天气：{data['condition']}, 温度 {data['temp']}°{unit[0].upper()}" def search_web(query: str, max_results: int = 3) -> str: """在网络上搜索信息。这是一个模拟函数。""" print(f"[模拟调用] 搜索：'{query}'，最大结果数：{max_results}") # 这里可以集成 SerperAPI、Google Search API 等 return f"关于'{query}'的模拟搜索结果：1. 相关文章A, 2. 相关文章B, 3. 相关文章C" @prompt( "请根据用户的问题，选择合适的工具来获取信息并回答。问题：{question}", functions=[get_weather, search_web], ) def answer_question(question: str) -> FunctionCall[str]: ... # 调用 output = answer_question("北京今天天气怎么样？") print(f"LLM决定调用: {output.function.__name__}") # 输出: LLM决定调用: get_weather print(f"调用参数: {output.args}, {output.kwargs}") # 输出: 调用参数: ('北京',), {'unit': 'celsius'} # 执行函数调用 weather_info = output() print(f"最终答案: {weather_info}") # 输出: 最终答案: 北京当前天气：Sunny, 温度 22°C

关键点在于answer_question的返回值是FunctionCall[str]。这意味着函数返回的不是最终答案，而是一个“待执行的动作”。你需要通过output()来实际执行这个动作（即调用get_weather函数），并获得其返回的字符串结果。

避坑技巧：为工具函数编写清晰、详细的文档字符串（docstring）至关重要。LLM主要依靠这些描述来理解函数的功能和参数含义。好的描述能极大提高工具调用的准确性。

4.3@prompt_chain：自动化执行函数调用链

手动执行FunctionCall虽然灵活，但对于多步任务显得繁琐。@prompt_chain装饰器可以自动完成“LLM生成FunctionCall-> 执行函数 -> 将结果返回给LLM -> LLM继续生成或调用下一个函数”的循环，直到LLM给出最终的自然语言答案。

from magentic import prompt_chain # 复用之前的工具函数 get_weather def get_current_weather(location: str, unit: Literal["celsius", "fahrenheit"] = "celsius") -> str: print(f"[模拟API调用] 获取{location}的天气...") return f"{location}的天气是晴朗，25度。" @prompt_chain( "请回答用户的问题。如果需要查询信息，请使用提供的工具。问题：{query}", functions=[get_current_weather], ) def intelligent_assistant(query: str) -> str: ... result = intelligent_assistant("我周末想去杭州玩，那边的天气适合穿短袖吗？") print(result) # 输出可能是一个连贯的回答： # “根据查询，杭州本周末天气晴朗，气温大约25摄氏度。这个温度穿短袖是非常舒适的，但建议也带一件薄外套以防早晚温差。”

在这个过程中，@prompt_chain内部自动处理了以下流程：

1. LLM看到问题“杭州天气...”，决定调用get_current_weather(location="杭州")。
2. 框架执行该调用，获得结果“杭州的天气是晴朗，25度。”
3. 框架将这个结果连同原始问题，再次发送给LLM。
4. LLM结合天气结果，生成最终的自然语言回答。

这使得构建一个能自动使用工具的问答助手变得异常简单。

4.4 异步支持：大幅提升并发性能

当你的应用需要同时处理多个LLM调用时，同步方式会导致严重的性能瓶颈，因为大部分时间都在等待网络I/O。Magentic全面支持异步async/await。

import asyncio from magentic import prompt from typing import AsyncIterable @prompt("列举三个关于{topic}的关键事实。") async def list_facts_about(topic: str) -> AsyncIterable[str]: ... async def main(): topics = ["人工智能", "区块链", "太空探索"] # 错误示范：顺序执行，总耗时约等于各次调用之和 # for topic in topics: # async for fact in await list_facts_about(topic): # print(fact) # 正确示范：并发执行，总耗时约等于最慢的那次调用 tasks = [] for topic in topics: # 创建异步任务，立即开始执行，而不是等待 task = asyncio.create_task(_gather_facts(topic)) tasks.append(task) # 等待所有任务完成 all_results = await asyncio.gather(*tasks) for topic, facts in zip(topics, all_results): print(f"\n--- {topic} ---") for fact in facts: print(f" - {fact}") async def _gather_facts(topic: str): """辅助协程，收集一个主题的所有流式事实。""" facts = [] async for fact in await list_facts_about(topic): facts.append(fact) return facts # 运行异步主函数 asyncio.run(main())

在这个例子中，我们同时发起三个list_facts_about的调用。由于它们是并发的，总的执行时间不会比单个最慢的调用长太多，效率提升显著。这对于构建需要同时处理多个用户请求或批量处理数据的AI服务至关重要。

注意事项：使用异步时，确保你提供的工具函数（functions参数中的）也是异步的（定义为async def），否则在@prompt_chain中调用它们时会阻塞事件循环。如果工具函数是同步的，可以考虑用asyncio.to_thread在单独的线程中运行。

5. 多后端配置与生产环境调优

5.1 支持的后端与配置详解

Magentic支持多种LLM提供商，通过不同的ChatModel子类来抽象。配置方式非常灵活，优先级从高到低如下：

1. 装饰器中的model参数（最高优先级）。
2. 使用with model:上下文管理器。
3. 全局环境变量配置。

OpenAI (默认)无需额外安装。支持所有特性（流式、函数调用、结构化输出等）。

from magentic import OpenaiChatModel, prompt # 方式1：通过装饰器参数指定 @prompt("Say hello", model=OpenaiChatModel("gpt-4o", temperature=0.7, max_tokens=500)) def hello_gpt4o() -> str: ... # 方式2：通过上下文管理器指定 gpt_model = OpenaiChatModel("gpt-4o-mini") with gpt_model: response = hello_gpt4o() # 在这个with块内，会使用gpt-4o-mini # 方式3：环境变量 # 设置环境变量 MAGENTIC_OPENAI_MODEL=gpt-4o， MAGENTIC_OPENAI_TEMPERATURE=0.5

通过OpenAI后端连接Ollama如果你在本地运行了Ollama，可以将其配置为OpenAI兼容的API端点。

# 首先，启动Ollama并拉取模型 ollama pull llama3.2 # Ollama服务默认运行在 http://localhost:11434

from magentic import OpenaiChatModel, prompt local_model = OpenaiChatModel( model="llama3.2", # Ollama中的模型名 base_url="http://localhost:11434/v1/", # Ollama的OpenAI兼容端点 api_key="ollama", # Ollama不需要真正的key，但需要传一个非空值 ) @prompt("Write a haiku about programming.", model=local_model) def write_haiku() -> str: ...

Anthropic (Claude)需要安装anthropic依赖。

pip install "magentic[anthropic]" # 或 pip install anthropic

from magentic.chat_model.anthropic_chat_model import AnthropicChatModel from magentic import prompt import os # 设置环境变量 ANTHROPIC_API_KEY os.environ["ANTHROPIC_API_KEY"] = "your-key-here" claude_model = AnthropicChatModel("claude-3-5-sonnet-latest") @prompt("Explain quantum entanglement like I'm five.", model=claude_model) def explain_quantum() -> str: ...

LiteLLM (统一网关)LiteLLM是一个统一的代理，支持上百种模型（包括OpenAI、Anthropic、Cohere、本地模型等）。如果你需要频繁切换或使用多种模型，LiteLLM后端非常方便。

pip install "magentic[litellm]" # 或 pip install litellm

from magentic.chat_model.litellm_chat_model import LitellmChatModel # 使用OpenAI模型 litellm_openai = LitellmChatModel("gpt-4o") # 使用Anthropic模型 (需配置相应环境变量) litellm_claude = LitellmChatModel("claude-3-5-sonnet-latest") # 使用本地Ollama模型 litellm_ollama = LitellmChatModel("ollama/llama3.2")

重要提示：不是所有模型都支持函数调用（结构化输出）和流式输出。在使用LiteLLM或非OpenAI/Anthropic的主流模型时，需要查阅对应模型的文档确认功能支持情况。

5.2 环境变量配置大全

对于生产环境，使用环境变量来配置是更规范和安全的方式。以下是Magentic支持的主要环境变量：

5.3 生产环境最佳实践与性能调优

1. 错误处理与重试：网络请求和LLM API调用可能失败。务必在你的@prompt函数调用外层添加重试逻辑。Magentic自身也提供了LLM-assisted retries功能，可以在输出不符合Pydantic模型时自动重试。

   from tenacity import retry, stop_after_attempt, wait_exponential from magentic import prompt @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) @prompt("这是一个可能失败的任务：{task}") def robust_llm_task(task: str) -> str: ...

2. 超时设置：为LLM调用设置合理的超时时间，防止长时间阻塞。这通常需要在HTTP客户端层面配置，例如在使用httpx（OpenAI SDK底层使用）时。

3. 速率限制与配额管理：尤其是使用OpenAI、Anthropic等付费API时，必须考虑速率限制。可以在应用层实现令牌桶或漏桶算法，或者使用像langchain的RateLimiter这样的中间件。对于关键生产应用，考虑使用提供负载均衡和缓存的LLM网关（如OpenAI的负载均衡功能或自建代理）。

4. 成本控制：监控token使用量。OpenAI等提供商通常会在响应头中返回使用的token数。你可以编写一个中间件或回调来记录这些数据，并设置预算警报。

5. 缓存：对于内容生成相对稳定、对实时性要求不高的查询（例如，将固定产品描述翻译成多种语言），可以考虑对LLM响应进行缓存。可以使用functools.lru_cache内存缓存，或者Redis等外部缓存。注意：缓存时需谨慎，确保不会缓存包含敏感信息或个人数据的响应。

6. 可观测性：Magentic集成了OpenTelemetry，可以方便地与Logfire（Pydantic官方观测性平台）或其他支持OpenTelemetry的后端（如Jaeger, Prometheus）集成，追踪每次LLM调用的耗时、token使用、函数调用链等，这对于调试和性能分析至关重要。

6. 常见问题排查与调试技巧

在实际使用中，你肯定会遇到各种问题。以下是一些常见问题的排查思路和解决方案。

6.1 类型检查器报错（mypy, pyright）

由于@prompt装饰的函数没有函数体（或只有...），类型检查器会认为函数没有返回值。有几种解决方法：

1. （推荐）全局配置忽略：在pyproject.toml或mypy.ini中配置全局忽略empty-body错误。

   # pyproject.toml [tool.mypy] disable_error_code = ["empty-body"]

2. 行内忽略：在每个函数上添加忽略注释。

   @prompt("Choose a color") def random_color() -> str: # type: ignore[empty-body] """返回一个随机颜色。"""

3. 使用raise占位：有些类型检查器接受raise语句。

   @prompt("Choose a color") def random_color() -> str: raise NotImplementedError("This function is implemented by the LLM.")

6.2 LLM输出不符合Pydantic模型

这是最常见的问题之一。LLM可能生成格式错误、缺少字段或字段类型不匹配的JSON。

• 启用LLM辅助重试：Magentic内置了重试机制。当解析失败时，它可以将错误信息反馈给LLM，让LLM修正输出。

  from magentic import prompt from magentic.retry import retry @retry(max_attempts=2) # 最多重试2次 @prompt("提取信息：{text}") def extract_info(text: str) -> YourPydanticModel: ...

• 提供更清晰的指令和示例：在提示词中明确说明输出格式。使用@chatprompt提供少样本示例是极其有效的方法。
• 简化模型：如果字段太多或结构太复杂，LLM容易出错。尝试拆分成多个更小的、更简单的模型和函数调用。
• 使用更强大的模型：GPT-4系列在遵循复杂指令和输出结构化数据方面通常比GPT-3.5-turbo好得多。

6.3 函数调用不准确或不被触发

LLM没有调用你期望的函数。

• 优化工具描述：确保工具函数的文档字符串（__doc__）清晰、无歧义地描述了函数的功能和每个参数的含义。LLM完全依赖这个描述。
• 调整提示词：在@prompt的指令中，明确要求LLM使用工具。例如：“请使用提供的search_web函数来查找最新信息，然后基于结果回答。”
• 检查函数签名：确保函数参数有恰当的类型注解。使用Literal类型来限制枚举值非常有用（如unit: Literal["celsius", "fahrenheit"]）。
• 提供示例：在@chatprompt中，可以包含一个UserMessage和AssistantMessage（其中AssistantMessage包含一个FunctionCall）的示例，来教LLM如何调用工具。

6.4 流式输出不工作或卡住

• 确认模型支持：并非所有模型/后端都支持流式输出。例如，某些通过LiteLLM连接的模型可能不支持。优先使用OpenAI或Anthropic的主流模型。
• 检查网络：流式响应对网络稳定性要求较高。检查是否有代理或防火墙干扰了SSE（Server-Sent Events）连接。
• 异步上下文：在异步函数中使用AsyncStreamedStr时，确保你在正确的事件循环中。

6.5 性能问题

• 并发与异步：这是提升吞吐量最有效的手段。将同步调用改为异步，并使用asyncio.gather并发执行多个独立请求。
• 减少上下文长度：提示词越长，消耗的token越多，处理时间越长，成本也越高。定期清理@chatprompt中积累的历史消息，或使用摘要技术。
• 使用更快的模型：对于不需要极高推理能力的任务，使用更小、更快的模型（如gpt-4o-minivsgpt-4o）。
• 启用缓存：如前所述，对可缓存的请求实施缓存策略。

6.6 调试与日志

• 启用详细日志：设置logging级别为DEBUG，可以查看Magentic与LLM API交互的详细请求和响应。

  import logging logging.basicConfig(level=logging.DEBUG)

• 使用OpenTelemetry：集成Logfire或其他观测性工具，可视化整个调用链，包括每个@prompt函数的执行、工具调用、token消耗等。这对于理解复杂Agent的工作流程和性能瓶颈不可或缺。

Magentic以其极简的设计和强大的类型安全特性，在LLM应用开发领域独树一帜。它可能不像一些大而全的框架那样提供开箱即用的所有功能，但它精准地解决了“如何优雅地将LLM集成到Python代码中”这个核心问题。从快速原型到生产部署，它都能提供一致且高效的开发体验。如果你厌倦了在字符串模板和JSON解析之间挣扎，渴望用编写普通Python函数的方式来驾驭AI能力，那么Magentic绝对值得你深入尝试。