# https://github.com/SylphAI-Inc/AdalFlow 项目说明书 生成时间：2026-06-26 23:28:36 UTC ## 目录 - [AdalFlow 概述与系统架构](#page-1) - [Agent 与 Runner：同步、异步与流式执行](#page-2) - [模型客户端与提供商集成](#page-3) - [自动优化框架：TextGrad、Few-Shot 与 Trainer](#page-4) ## AdalFlow 概述与系统架构 ### 相关页面 相关主题：[Agent 与 Runner：同步、异步与流式执行](#page-2), [模型客户端与提供商集成](#page-3), [自动优化框架：TextGrad、Few-Shot 与 Trainer](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/README.md) - [adalflow/adalflow/README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/README.md) - [adalflow/adalflow/components/agent/README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/README.md) - [adalflow/adalflow/components/agent/agent.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/agent.py) - [adalflow/adalflow/components/agent/react.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/react.py) - [adalflow/adalflow/components/agent/prompts.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/prompts.py) - [adalflow/adalflow/optim/README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/README.md)
# AdalFlow 概述与系统架构 ## 1. 项目定位与设计理念 AdalFlow 是 SylphAI 推出的、面向大语言模型（LLM）应用工作流的 Python 库，定位为「类 PyTorch 的 LLM 任务流水线构建与自动优化框架」。其官方表述为： > 「AdalFlow is a PyTorch-like library to build and auto-optimize any LM workflows, from Chatbots, RAG, to Agents.」 资料来源：[README.md:3-3]() 该库的核心设计动机在于：LLM 应用具有高度定制化的业务逻辑、数据与用户体验，没有任何库能够开箱即用地提供解决方案；因此库本身必须是模块化、可读且稳健的。README 中明确指出： > 「The only code you should put into production is code you either 100% trust or are 100% clear about how to customize and iterate.」 资料来源：[adalflow/adalflow/README.md:14-16]() 项目在致谢部分列举了其设计哲学的灵感来源：`Component`、`Parameter`、`Sequential` 借鉴自 [PyTorch](https://github.com/pytorch/pytorch/)；自动微分思想参考 [Micrograd](https://github.com/karpathy/micrograd)；文本梯度下降（Textual Gradient Descent）参考 [TextGrad](https://github.com/zou-group/textgrad)；少样本引导与 `__{input/output}__fields` 借鉴 [DSPy](https://github.com/stanfordnlp/dspy)；`AdalComponent` 与 `Trainer` 借鉴 [PyTorch Lightning](https://github.com/Lightning-AI/pytorch-lightning)。资料来源：[README.md:152-160]() ## 2. 核心架构 AdalFlow 的整体架构可抽象为「组件 + 参数 + 生成器 + 训练器」四层结构。Generator 负责调用 ModelClient 与 LLM 通信；AdalComponent 负责组织 Generator；Trainer 驱动自动优化。下面的流程图展示了从用户查询到最终答案、再到优化反馈的主要数据流： ```mermaid flowchart LR A[用户查询 input_str] --> B[Prompt 模板渲染] B --> C[Generator] C --> D[ModelClient 模型 API] D --> E[原始响应 raw_response] E --> F[OutputProcessor 解析器] F --> G[GeneratorOutput.data] G --> H[AdalComponent.forward] H --> I[Loss / Eval 反馈] I --> J[Trainer + Textual Optimizer] J --> K[更新 Parameter 提示词与少样本] K --> C ``` ### 2.1 Component 与 Parameter `Component` 是所有可组合模块的基类，相当于 PyTorch 中的 `nn.Module`，用于序列化、可视化与算子拼接。`Parameter` 则把 prompt 文本、少样本示例、指令等纳入可优化的「带类型参数」之中。AdalFlow 通过统一的基类体系让 LLM 应用既能像普通 Python 对象一样组装，也能在 `Trainer` 中被识别为待优化节点。资料来源：[README.md:152-160]() ### 2.2 Generator 与 ModelClient `Generator` 是「LLM 调用 + prompt 模板 + 输出解析」的最小执行单元。其构造函数同时接受 `template`、`prompt_kwargs`、`output_processors` 与 `model_client`、`model_kwargs`。模型无关性通过 `ModelClient` 抽象实现：只需更换 `model_client`（如 `OpenAIClient`、`GroqAPIClient`）与对应的 `model_kwargs`，即可在 OpenAI、Groq、Anthropic 等不同提供商之间切换，而无需改动业务代码。资料来源：[adalflow/adalflow/README.md:46-72]() 输出侧使用 `JsonOutputParser` 与 `DataClass`（如 `QAOutput`、`Function`）约束模型输出结构，结合 `format_instructions()` 自动注入到 prompt 中，实现类型安全的结构化输出。资料来源：[adalflow/adalflow/README.md:36-44]() ## 3. Agent 系统 Agent 模块位于 `adalflow/adalflow/components/agent/`，文档将其定位为： > 「The agent uses LLM models to plan and replan steps that each involves the usage of various tools, such as function calls, another LLM model based on the context and history (memory) to complete a task autonomously.」 资料来源：[adalflow/adalflow/components/agent/README.md:1-3]() Agent 由两个核心子组件构成： 1. **Planner（Generator）**：负责基于对话历史、工具描述、当前步骤生成下一步的 Thought + Action； 2. **ToolManager**：负责注册、描述、执行各类工具（含函数调用、其它 LLM、MCP 工具等）。 其内部使用 ReAct（Reasoning and Acting）架构，迭代地规划与执行工具调用，直到 `_is_answer_final=True` 时返回 `_answer`。资料来源：[adalflow/adalflow/components/agent/agent.py:18-35]() 默认的 Planner 解析 `Function` 数据类，当模型为推理类（thinking）模型时省略 `thought` 字段，反之包含 `thought`、`name`、`kwargs`、`_is_answer_final`、`_answer` 等输出字段。资料来源：[adalflow/adalflow/components/agent/agent.py:118-138]() 系统提示模板 `DEFAULT_ADALFLOW_AGENT_SYSTEM_PROMPT` 与 ReAct 变体 `react_agent_task_desc` 在 [prompts.py](adalflow/adalflow/components/agent/prompts.py) 中集中定义，便于通过 `Parameter(role_desc=..., param_type=ParameterType.PROMPT, requires_opt=True)` 注入优化路径。资料来源：[adalflow/adalflow/components/agent/react.py:30-60]() ## 4. 自动优化机制 AdalFlow 的优化器目录位于 `adalflow/adalflow/optim/`，文档列出了至少四类文本优化器： 1. **Bootstrap Few-Shot**：在大上下文 LLM 中根据 input/output 批量合成少样本示例； 2. **Textual Gradient Descent (TSGD)**：以 LLM 反馈作为「文本梯度」迭代改进 prompt； 3. **Instruction History / OPRO 风格**：在优化器中保留历史指令及其准确率，用于下一次采样； 4. **TSGD-M（带 Momentum 的文本梯度下降）**：从历史缓存采样并评估 K 条 prompt，再以最佳历史 prompt + 梯度生成下一轮 prompt。 资料来源：[adalflow/adalflow/optim/README.md:1-12]() `Parameter` 与 `GradComponent` 是该机制的关键：前者用于声明哪些 prompt、示例、指令需要优化；后者继承自 `Component`，具备 `forward` / `backward` 接口，可在文本梯度范式中作为「层」参与反向传播。资料来源：[adalflow/adalflow/optim/README.md:16-22]() ## 5. 已知问题与社区关注 从社区 issue 来看，用户对 AdalFlow 的关注点主要集中在以下方面： - **Function 字段解包异常**（#479）：当 LLM 仅返回关键字参数时，`Function.args` 反序列化为 `None`，下游 `*func.args` 会抛出 `TypeError: argument after * must be an iterable, not NoneType`。这是一个典型的 Optional 类型字段被强制解包的问题。 - **OpenAI Responses API 兼容**（#481）：Quickstart Colab 中 `o3-mini` 教师模型调用 `train()` 时，因 `frequency_penalty` 参数在 Responses API 中不被接受而失败。 - **超时错误**（#474）：`TimeoutError: Request failed` 在 macOS 环境下偶发。 - **凭证泄露扫描**（#489）：第三方扫描提示仓库中存在凭证处理风险，需维护者复核。 - **AWS Bedrock 集成**（#201、#283）：用户长期请求官方支持 AWS Bedrock 模型与嵌入，并改善凭证配置文档。 - **MCP 工具集成**（#386）：社区希望把 Model Context Protocol 工具接入 Agent，以复用现有 MCP server。 最新发布版本为 v1.1.3，可在 [GitHub Releases](https://github.com/SylphAI-Inc/AdalFlow/releases) 查阅。 ## See Also - [AdalFlow GitHub 仓库主页](https://github.com/SylphAI-Inc/AdalFlow) - [官方文档站点](https://adalflow.sylph.ai/) - [快速开始 Colab Notebook](https://colab.research.google.com/drive/1_YnD4H4shzPRARvishoU4IA-qQuX9jHrT?usp=sharing) - [CHANGELOG.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/CHANGELOG.md) - [Issue #479：Function 字段解包异常](https://github.com/SylphAI-Inc/AdalFlow/issues/479) - [Issue #481：OpenAI Responses API 兼容性](https://github.com/SylphAI-Inc/AdalFlow/issues/481) - [Issue #201 / #283：AWS Bedrock 集成需求](https://github.com/SylphAI-Inc/AdalFlow/issues/201) --- ## Agent 与 Runner：同步、异步与流式执行 ### 相关页面 相关主题：[AdalFlow 概述与系统架构](#page-1), [模型客户端与提供商集成](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [adalflow/adalflow/components/agent/agent.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/agent.py) - [adalflow/adalflow/components/agent/runner.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/runner.py) - [adalflow/adalflow/components/agent/react.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/react.py) - [adalflow/adalflow/components/agent/prompts.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/prompts.py) - [adalflow/adalflow/components/agent/README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/README.md) - [README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/README.md)
# Agent 与 Runner：同步、异步与流式执行 ## 概述与定位 AdalFlow 将"Agent"定位为基于 LLM 的高层规划组件，将"Runner"定位为负责驱动 Agent 执行的工作流管理器；二者协作构成可同步、可异步、可流式运行的智能体执行栈。AdalFlow 自身宣称是"PyTorch-like library to build and auto-optimize any LM workflows, from Chatbots, RAG, to Agents"，Agent 与 Runner 正是其中"Agents"一类的实现载体。 按照 README 中的设计语言，AdalFlow 借鉴 PyTorch 的组件/参数化思路、PyTorch Lightning 的 `Trainer` 模式，将 Agent 的推理循环封装成 `Component`，并由 `Runner` 完成执行与跟踪。资料来源：[README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/README.md) ## Agent 组件结构 `Agent` 类继承自 `Component`，由两个核心部分组成：基于 `Generator` 的规划器（Planner）和负责工具调用的 `ToolManager`。它采用 ReAct（Reasoning + Acting）架构，让 LLM 反复生成"Thought → Action → Observation"，直至产出最终答案。 Agent 的关键属性包括：`name`（唯一标识）、`tool_manager`（工具管理）、`planner`（LLM 规划器）、`answer_data_type`（最终答案类型）、`max_steps`（默认 10，由常量 `DEFAULT_MAX_STEPS` 定义）和 `is_thinking_model`（是否启用 CoT 字段）。资料来源：[adalflow/adalflow/components/agent/agent.py:1-80](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/agent.py) `create_default_tool_manager` 与 `_create_planner` 这两个工厂函数用于构造默认的工具集和规划器。规划器中间步骤的输出数据类为 `Function`，并由 `JsonOutputParser` 解析为结构化对象；当模型支持思维链时，会跳过 `thought` 字段，仅保留 `name`、`kwargs`、`_is_answer_final`、`_answer`。资料来源：[adalflow/adalflow/components/agent/agent.py:120-200](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/agent.py) ## 提示模板与 ReAct 流程 Agent 使用 `prompts.py` 中的 `adalflow_agent_task_desc` 作为任务说明，并结合系统提示构建 ReAct 循环。提示要求模型： - 每一步读取前序 Thought、Action（name、kwargs）、Observation（执行结果），再生成下一步 Thought 与 Action； - 对于简单查询可直接将 `_is_answer_final` 设为 True 并在 `_answer` 中给出答案； - 对于复杂查询则拆解为多步，每次仅调用一个工具； - `_answer` 字段必须可被 Python 内置类型或 JSON 反序列化。资料来源：[adalflow/adalflow/components/agent/prompts.py:5-40](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/prompts.py) `react.py` 中则提供了历史版本的 `react_agent_task_desc`，描述了"每步调用一个工具，最终以 `finish` 收尾"的 ReAct 协议，用于多跳检索等场景。资料来源：[adalflow/adalflow/components/agent/react.py:1-25](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/react.py) ## Runner：同步、异步与流式执行 `Runner` 是真正驱动 Agent 的执行器。从 `runner.py` 的导入与类型签名来看，它同时暴露三类执行模式： | 执行模式 | 关键返回类型 | 关键流式事件 | | --- | --- | --- | | 同步 | `RunnerResult` | — | | 异步 | `RunnerResult` | `AsyncIterable` | | 流式 | `RunnerStreamingResult` | `RawResponsesStreamEvent`、`RunItemStreamEvent`、`ToolCallRunItem`、`ToolOutputRunItem`、`StepRunItem`、`FinalOutputItem`、`QueueCompleteSentinel` | `Runner` 通过 `inspect` 与 `asyncio` 区分同步/异步调用，并使用 `uuid`、`datetime` 构造运行轨迹；它内部还会与 `PermissionManager`（权限控制）、`ConversationMemory`（对话记忆）以及 `tracing` 模块中的 `runner_span`、`tool_span`、`response_span`、`step_span` 集成，为每一次工具调用与模型响应提供可观测链路。资料来源：[adalflow/adalflow/components/agent/runner.py:1-60](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/runner.py) ## 架构总览 下图展示了 Agent 与 Runner 的协同关系：Runner 调度 Agent，Agent 由 Planner（Generator）与 ToolManager 组成，Planner 产生 Function 形式的中间结果，ToolManager 调用工具并把 Observation 写回步骤历史。 ```mermaid flowchart LR User[用户查询] --> Runner Runner -->|acall / call / stream| Agent subgraph Agent Planner[Planner / Generator] -->|Thought + Action| Parser[JsonOutputParser -> Function] Parser --> ToolManager ToolManager -->|Observation| StepHistory[step_history] StepHistory --> Planner end ToolManager --> Tools[工具集 / MCP Tools] Tools --> ToolManager Parser -->|最终 _answer| Runner Runner --> Result[RunnerResult / RunnerStreamingResult] Runner -. tracing .-> Spans[runner_span / step_span / tool_span / response_span] ``` ## 社区关注与已知问题 社区中与 Agent 紧密相关的讨论集中在工具接入与提示优化两个方向： - **MCP 工具接入**：#386 提议将 Model Context Protocol 集成进 Agent，以简化工具调用流程。 - **提示缓存优化**：#389 希望 AdalFlow 把 prompt caching 视为一等公民，这对 Agent 长上下文尤其重要。 - **Function 参数解包缺陷**：#479 报告 `Function.args` 字段被声明为 `Optional`，但部分代码用 `*func.args` 无条件解包，导致 LLM 仅返回关键字参数时崩溃。该问题与 Agent 的 Function 输出解析直接相关，修复需要把解包逻辑改为对 `None` 容错。 - **超时错误**：#474 报告 `TimeoutError: Request failed`，多由 Provider 网络抖动引发；Runner 的 `runner_span`/`response_span` 链路是定位该类问题的首选入口。 上述议题反映了 Agent + Runner 栈在稳定性与扩展性上的核心痛点：解析鲁棒性、Provider 兼容性与工具生态广度。 ## 配置要点与常见失败模式 构建 Agent 时通常需要关注以下配置： - `model_client` 与 `model_kwargs`：决定 Planner 的底层 Provider；切换 Provider 仅需替换 `model_client`。资料来源：[adalflow/adalflow/components/agent/agent.py:50-90](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/agent.py) - `is_thinking_model`：当模型支持原生 CoT 时开启，可让 JsonOutputParser 跳过 `thought` 字段。 - `max_steps`：默认 10；超出后会触发终止逻辑，需在 `task_desc` 中同步说明。 - `add_llm_as_fallback`：将 LLM 自身注册为兜底工具。 - `context_variables` / `permission_manager` / `memory`：影响多轮与权限审计能力。资料来源：[adalflow/adalflow/components/agent/runner.py:30-55](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/runner.py) 常见失败模式包括：(1) `Function.args` 为 `None` 时解包异常（#479）；(2) Provider 不支持的字段如 `frequency_penalty` 在 Responses API 中报错（#481）；(3) `max_steps` 过小导致任务中途被截断；(4) 流式模式下未消费 `QueueCompleteSentinel` 导致生成器泄漏。建议在调试阶段启用 `Runner` 的 tracing span，并将 `Generator` 的 `use_cache` 与 `cache_path` 与 Agent 共享，以复用 Planner 结果。 ## See Also - [Generator 与 Prompt：构建可优化的 LLM 调用]() - [Trainer 与 Textual Gradient：自动优化 LLM 工作流]() - [Model Client 与 Provider：多模型统一接口]() - [Tracing 与可观测性：runner / step / tool / response span]() --- ## 模型客户端与提供商集成 ### 相关页面 相关主题：[AdalFlow 概述与系统架构](#page-1), [自动优化框架：TextGrad、Few-Shot 与 Trainer](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/README.md) - [adalflow/README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/README.md) - [adalflow/adalflow/components/agent/agent.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/agent.py) - [adalflow/adalflow/components/agent/react.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/react.py) - [adalflow/adalflow/components/agent/prompts.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/prompts.py) - [adalflow/adalflow/optim/README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/README.md) - [adalflow/adalflow/utils/config.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/utils/config.py) - [adalflow/adalflow/utils/registry.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/utils/registry.py)
# 模型客户端与提供商集成 `ModelClient`（模型客户端）层是 AdalFlow 与外部 LLM / Embedding 服务之间的"水龙头"：它把 OpenAI、Anthropic、Google、AWS Bedrock、Azure AI、Ollama 等不同供应商的 SDK 调用差异收敛到一个统一接口之后，让上层 `Generator`、`Agent`、`Trainer` 可以无差别地跨供应商复用业务逻辑，而不必关心底层 HTTP 协议、参数命名或错误码。 ## 设计目标与核心抽象 AdalFlow 明确将自身定位为"模型无关（model-agnostic）"的 LLM 应用框架。顶层 README 将 "Many providers and models accessible via the same interface" 作为核心特性列出，并在图像资源中以 "multi-providers.png" 强调这种"多供应商同接口"的设计。 抽象的核心是 `ModelClient` 基类：一个 `Generator` 必须持有它的实例（`model_client`），并通过 `model_kwargs` 把供应商特定的参数（如 `model`、`temperature`、`max_tokens`）原样透传下去。 ```mermaid graph LR P[Providers
OpenAI / Anthropic / Bedrock
Google / Azure / Ollama] M[ModelClient
统一基类] G[Generator
template + prompt_kwargs + model_kwargs] A[AdalComponent / Agent / ReActAgent] T[Trainer / Textual Optimizer] P --> M M --> G G --> A A --> T ``` 资料来源：[README.md:1-200]()；[adalflow/adalflow/components/agent/agent.py:create_default_planner()]()；[adalflow/adalflow/components/agent/react.py:ReActAgent.__init__()]() ## 在 Generator 与 Agent 中的集成方式 无论是 `Agent` 还是 `ReActAgent`，都遵循一致的"注入模式"： 1. 用户在构造时显式传入 `model_client`（指向某个具体供应商的客户端实现）； 2. 通过 `model_kwargs: Dict[str, Any]` 携带模型 ID、temperature、max_tokens 等供应商私有字段； 3. `model_type` 字段决定调用形态——LLM 推理、Embedding 或其它； 4. 可选 `cache_path` / `use_cache` 启用提示缓存，这与社区 issue #389 "Optimize prompt for caching" 的诉求方向一致。 在契约层面，`create_default_planner` 在缺失 `model_client` 时直接抛出 `ValueError("model_client and model_kwargs are required")`，把"模型客户端是必需依赖"这一约束硬编码到了代理构造路径中。 资料来源：[adalflow/adalflow/components/agent/agent.py:create_default_planner()]()；[adalflow/adalflow/components/agent/react.py:ReActAgent.__init__()]() ## 配置序列化与注册中心 为了让任务管道可序列化、可重建，AdalFlow 提供了一套 JSON 配置体系。`adalflow/adalflow/utils/config.py` 的注释文档直接给出了供应商客户端的声明范式： ```json "model_client": { "entity_name": "OpenAIClient", "entity_config": {} } ``` 其中 `entity_name` 是注册到 `EntityMapping` 中的字符串键。`EntityMapping`（`adalflow/adalflow/utils/registry.py`）以最朴素的字典 `_registry: Dict[str, Type]` 维护从名字到类的映射，并暴露 `register / get / get_all` 三个类方法。这种"名字 → 类"的间接层正是供应商可插拔的关键：任何实现了 `ModelClient` 接口的新类，只要调用 `EntityMapping.register("MyClient", MyClient)` 注册，就能在 JSON 配置中按名字引用、并在反序列化时自动重建。 资料来源：[adalflow/adalflow/utils/config.py:1-60]()；[adalflow/adalflow/utils/registry.py:EntityMapping]() ## 已知问题与社区反馈 模型客户端层是用户最容易"踩坑"的位置，仓库公开 issues 已记录多起与提供商相关的事故： | 现象 | 影响范围 | |------|---------| | `Responses.create() got an unexpected keyword argument 'frequency_penalty'`（#481） | OpenAI Responses API（`o3-mini`）拒绝 quickstart 默认参数 | | `Function.args` 反序列化为 `None` 导致 `*func.args` 抛 `TypeError`（#479） | 函数调用解析未覆盖"仅 kwargs"分支 | | `TimeoutError: Request failed`（#474） | 网络/供应商稳定性问题 | | AWS Bedrock 集成改进请求（#201、#283） | 缺少 `modelId` 查找指引、凭证配置不清晰 | 这些问题提示：跨供应商抽象并不是"一次实现、处处运行"。不同 provider 的参数语义（Responses API vs Chat Completions）、错误归因方式、以及凭证发现机制都需要逐个适配；同时也印证了 #389 关于"为缓存优化提示"的请求——在多供应商异构环境下缓存键的标准化尤为关键。 资料来源：[README.md:Multi-providers 段落]()；[adalflow/adalflow/optim/README.md:GradComponent 与损失函数]()；仓库 issues #481、#479、#474、#201、#283 ## See Also - `Generator` / `Parameter` 编程模型（参见 [`optim/README.md`](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/README.md)） - 代理与 ReAct 推理循环（参见 [`agent/agent.py`](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/components/agent/agent.py)） - 配置序列化与 `EntityMapping` 注册机制（参见 [`utils/config.py`](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/utils/config.py) 与 [`utils/registry.py`](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/utils/registry.py)） --- ## 自动优化框架：TextGrad、Few-Shot 与 Trainer ### 相关页面 相关主题：[AdalFlow 概述与系统架构](#page-1), [Agent 与 Runner：同步、异步与流式执行](#page-2), [模型客户端与提供商集成](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [adalflow/adalflow/optim/README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/README.md) - [adalflow/adalflow/optim/parameter.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/parameter.py) - [adalflow/adalflow/optim/grad_component.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/grad_component.py) - [adalflow/adalflow/optim/text_grad/tgd_optimizer.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/text_grad/tgd_optimizer.py) - [adalflow/adalflow/optim/text_grad/llm_text_loss.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/text_grad/llm_text_loss.py) - [adalflow/adalflow/optim/text_grad/ops.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/text_grad/ops.py) - [adalflow/adalflow/optim/few_shot/bootstrap_optimizer.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/few_shot/bootstrap_optimizer.py) - [adalflow/adalflow/trainer/trainer.py](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/trainer/trainer.py)
# 自动优化框架：TextGrad、Few-Shot 与 Trainer ## 概览与设计哲学 AdalFlow 的自动优化框架将"提示词与少样本示例"视为一等公民，通过 `Parameter`、`GradComponent`、`Generator` 三大抽象把 LLM 应用的指令、示例和响应纳入统一的可微路径。其灵感源自 PyTorch 的自动求导与 TextGrad 的"文本梯度"思路（[README.md:1-120](https://github.com/SylphAI-Inc/AdalFlow/blob/main/README.md)）。框架核心目标包含四点： 1. **零样本提示优化**：通过 LLM 直接改写系统指令； 2. **少样本示例挖掘**：用 Bootstrap 方式自动筛选高质量 in-context 示例； 3. **文本梯度下降 (TSGD)**：把 LLM 反馈当作"梯度"，迭代地精炼参数； 4. **指令历史回放**：借鉴 OPRO，将过去的最优指令与准确率回传给优化器。 资料来源：[adalflow/optim/README.md:1-60]() 下表列出 AdalFlow 在 `optim/` 目录下提供的核心优化策略： | 策略 | 关键参数 | 适用场景 | |------|---------|---------| | ORPO（提出—测试—精炼） | `max_steps` | 多轮精炼单一提示 | | TextGrad (TSGD) | `inference_engine`、`num_steps` | 多 `Parameter` 联合优化 | | Lazy Brute-Force | `context_window` | 大上下文 LLM 一次性全量优化 | | TSGD-Momentum | `tsgd_m_momentum_window`、`exploration_epsilon` | 长历史缓存、动量式收敛 | | Few-Shot Bootstrap | `num_demos`、`bootstrap_ratio` | 缺少示例的冷启动任务 | 资料来源：[adalflow/optim/README.md:60-95]() ## Parameter 与 GradComponent 基础 `Parameter` 是可被优化器更新的容器，包装 `Prompt`、示例列表或字符串等可编辑对象，并通过 `param_type` 区分 `PROMPT` / `DEMOS` / `OUTPUT` 等类别（[optim/parameter.py:1-80](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/parameter.py)）。`GradComponent` 则提供 `forward` / `backward` 接口，相当于 PyTorch 中的 `Module`，但其梯度是自然语言文本。任意继承 `GradComponent` 的类既可作为损失函数，也可作为可优化层。 ```python from adalflow.optim import Parameter, GradComponent from adalflow.optim.types import ParameterType task_desc = Parameter( name="react_agent_task_desc", data=prompt_template, role_desc="Task instruction for the agent to plan steps...", param_type=ParameterType.PROMPT, requires_opt=True, ) ``` `GradComponent.backward` 返回的是 `BackwardPass` 对象，包含对每个 `Parameter` 的"文本梯度"——本质上是由 LLM 生成的改写建议。资料来源：[optim/grad_component.py:1-60]()、[components/agent/agent.py:60-110]() ## TextGrad 文本梯度下降 `TGDOptimizer` 是 TextGrad 思想在 AdalFlow 中的具体实现。它在每轮迭代中执行 `step()`： 1. 对训练样本运行 `Generator.acall(...)` 取得预测； 2. 调用 `LLMTextLoss`（或自定义 `GradComponent`）计算文本损失； 3. 通过 `SumBackwardEngine` / `SequentialBackwardEngine` 沿 `Parameter` 反向聚合反馈； 4. 使用 `GradProcessors` 对反馈进行裁剪、去噪，再用 `TextualGradientDescent` 生成新候选参数； 5. 将新参数回写到 `Parameter.data`。 资料来源：[optim/text_grad/tgd_optimizer.py:1-120](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/text_grad/tgd_optimizer.py)、[optim/text_grad/ops.py:1-80]() `LLMTextLoss` 把"预测与期望的差距"转化为自然语言反馈，例如"答案应为 5，但模型输出 3"，因此下游 `Engine` 能直接消费。资料来源：[optim/text_grad/llm_text_loss.py:1-60]() ```mermaid flowchart LR A[Generator 前向] --> B[预测输出] B --> C[LLMTextLoss] C -->|文本梯度| D[BackwardEngine 聚合] D --> E[TGDOptimizer.step] E -->|新参数| F[Parameter.data 回写] F --> A ``` ## Few-Shot Bootstrap 优化器 当用户没有高质量示例时，`BootstrapFewShot` 会在教师模型（通常是更强的 LLM）上反复运行训练集，挑出模型答对且多样性达标的轨迹作为演示。核心字段包括 `max_steps`、`max_bootstrapped_demos`、`max_labeled_demos`（[optim/few_shot/bootstrap_optimizer.py:1-100](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/few_shot/bootstrap_optimizer.py)）。 典型流程： 1. 用 `AdalComponent` 的 `train(...)` 把 `Generator` 暴露给优化器； 2. `Trainer` 在每个 epoch 调用 `BootstrapFewShot.propose()`； 3. 优化器评估每个候选示例集在验证集上的准确率； 4. 保留 Top-K 示例并替换 `Generator` 内部的 `Parameter(..., param_type=DEMOS)`。 ## Trainer 与社区已知问题 `Trainer`（PyTorch Lightning 风格）负责把 `AdalComponent` 与优化器组合，提供 `train(debug=False, ...)`、`evaluate`、`checkpoint` 等接口（[adalflow/README.md:1-80](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/README.md)）。社区在 Issue #382「Question Answer tutorial notebook error」中反馈过 `train()` 抛出 `ValueError`，多由模型客户端字段不匹配或 `Function.args` 反序列化失败导致（Issue #479）。若教师模型使用 OpenAI Responses API（如 `o3-mini`），需注意它不支持 `frequency_penalty` 等参数，否则 Quickstart 会在 `train()` 阶段失败（Issue #481）。此外，Issue #389 提议把"提示缓存优化"集成到 `TGDOptimizer.step` 中，可在减少 token 消耗的同时保留文本梯度效果。 ## See Also - [adalflow/optim/README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/optim/README.md) — 优化策略总览 - [README.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/README.md) — 项目顶层介绍 - [CHANGELOG.md](https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/adalflow/CHANGELOG.md) — 1.1.x 系列版本说明 --- --- ## Doramagic 踩坑日志 项目：SylphAI-Inc/AdalFlow 摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[phantomcreds] Exposed secrets detected in this repository。 ## 1. 安全/权限坑 · 来源证据：[phantomcreds] Exposed secrets detected in this repository - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[phantomcreds] Exposed secrets detected in this repository - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/SylphAI-Inc/AdalFlow/issues/489 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Quickstart Colab fails with `frequency_penalty` error on OpenAI Responses API (`o3-mini` teacher model) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Quickstart Colab fails with `frequency_penalty` error on OpenAI Responses API (`o3-mini` teacher model) - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/SylphAI-Inc/AdalFlow/issues/481 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 配置坑 · 来源证据：API Error: TimeoutError: Request failed - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：API Error: TimeoutError: Request failed - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/SylphAI-Inc/AdalFlow/issues/474 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 配置坑 · 来源证据：TypeError: argument after * must be an iterable, not NoneType — Function.args/kwargs typed Optional but unpacked uncond… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：TypeError: argument after * must be an iterable, not NoneType — Function.args/kwargs typed Optional but unpacked unconditionally - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/SylphAI-Inc/AdalFlow/issues/479 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/SylphAI-Inc/AdalFlow | README/documentation is current enough for a first validation pass. ## 6. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/SylphAI-Inc/AdalFlow | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/SylphAI-Inc/AdalFlow | no_demo; severity=medium ## 8. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/SylphAI-Inc/AdalFlow | no_demo; severity=medium ## 9. 安全/权限坑 · 来源证据：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/SylphAI-Inc/AdalFlow/issues/475 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 10. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/SylphAI-Inc/AdalFlow | issue_or_pr_quality=unknown ## 11. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/SylphAI-Inc/AdalFlow | release_recency=unknown