第六章可能出现的问题：依赖冲突与成本乘法

分析对象 ：code/chapter6/（AutoGenDemo/ · AgentScopeDemo/ · CAMEL/ · Langgraph/）与 docs/chapter6/ 的四个案例

运行环境 ：腾讯云 Lighthouse（2C2G / 无 GPU / Python 3.14 ），模型 kimi-k2.6（temperature 仅接受 1，组织 RPM=3 ）

结论先行 ：本章的问题几乎都不在"算法"里，而在"工程假设"里 ------示例假设了交互式终端、假设了某个 API key、假设了充裕的调用额度、假设了框架之间不会互相踩。把示例搬到一个真实的无头服务器上，这四条假设全被打破。

怎么用这一篇 ：下面每条都是我在真实云服务器上实际遇到并复现过的，不是推测。每条结构固定：现场 → 根因 → 因果链 → 为什么严重 → 分档修复。文末有排障原则与诊断速查表。

本系列其他文章

• 上一章问题篇：第五章可能出现的问题：两类必错设计与生产不可用
• 本章笔记篇：第六章 框架开发实践 · 学习笔记（AutoGen / AgentScope / CAMEL / LangGraph）
• 全系列目录：hello-agent入门学习

---

一、问题：多框架共用一个 venv → 依赖冲突

1.1 现场

依次安装 langgraph / autogen-agentchat / agentscope 后，pip 给出明确警告：

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
autogen-core 0.7.5 requires protobuf~=5.29.3, but you have protobuf 7.36.2 which is incompatible.
Successfully installed agentscope-2.0.8 ... protobuf-7.36.2 ...

1.2 根因（已在本机复现）

根因一句话 ：agentscope 把 protobuf 升到了 7.36.2 ，而 autogen-core 0.7.5 声明需要 ~=5.29.3 。同一个 venv 里，两个框架对同一个公共依赖的版本要求互斥。

autogen-core 0.7.5 ──需要──> protobuf ~=5.29.3
agentscope    2.0.8 ──拉入──> protobuf  7.36.2
                                   ↑
                        同一个 site-packages，只能有一个版本

1.3 逐步因果链

① 为了省事，把三个框架装进同一个 venv
        ↓
② pip 按"后装优先"升级 protobuf 到 7.36.2
        ↓
③ pip 只在安装时打一行 warning，**不阻断**
        ↓
④ 导入层测试：autogen_core / autogen_agentchat / agentscope **全部 import 成功**
        ↓
⑤ 结论：今天是"潜在风险"，不是"立即故障"
   ------但 autogen-core 的版本约束已被违反，运行时某个 gRPC/OTLP 路径可能随时炸

1.4 为什么说这是必然触发的

不是偶然。只要"多个框架"和"一个 venv"同时成立，公共依赖冲突就是概率事件 ------框架越多，公共依赖越多（protobuf、pydantic、httpx、openai 都是高频重叠区）。本轮撞上 protobuf 只是时间问题。

📌 这就是"为什么要用虚拟环境"的现场证据 。它不是教条，是因为真的会撞。

1.5 修复方案

修复 1：一个框架一个 venv（最小成本，本轮结论）

python3 -m venv .venv-langgraph && . .venv-langgraph/bin/activate && pip install langgraph langchain-openai
python3 -m venv .venv-autogen   && . .venv-autogen/bin/activate   && pip install autogen-agentchat autogen-ext

修复 2：用锁文件固化依赖 （pip-tools / uv pip compile），把"能跑的那套组合"记下来。

修复 3：容器隔离（生产推荐）------每个框架一个镜像，避免任何形式的环境耦合。

修复 4：CI 加"导入冒烟测试"，把"能 import"变成每次提交都验的门槛：

# smoke_test.py
for m in ["langgraph", "langchain_openai", "autogen_core", "autogen_agentchat"]:
    __import__(m)
print("imports OK")

📌 补充证据（第二个依赖冲突样本） ：pip install --dry-run camel-ai 显示它会把 pydantic 从 2.13 降到 2.12.0 ，并同时下调 pydantic_core / tiktoken / websockets。

即：这不是 autogen↔agentscope 的偶发个例，而是"框架越多、公共依赖被反复拉扯"的系统性问题。 本轮为保住已验证环境，没有实际安装 camel-ai------"知道它会带来什么代价"本身就是有效信息。

---

二、问题：仓库示例在无头环境"跑不起来"

2.1 现场

code/chapter6/Langgraph/Dialogue_System.py 直接运行会卡在等待输入：

# 第 213-214 行
while True:
    user_input = input("🤔 您想了解什么: ").strip()      # ← 无头/CI 环境下永久阻塞

而 main() 开头还有一道静默退出：

# 第 200-202 行
if not os.getenv("TAVILY_API_KEY"):
    print("❌ 错误：请在.env文件中配置TAVILY_API_KEY")
    return                                              # ← 打印一句话就退出，无输出产物

2.2 根因：示例写的是"演示脚本"，不是"可执行程序"

假设	示例里的体现	真实服务器上
有交互式终端	input() 循环	❌ 无 stdin，永久阻塞
有 Tavily key	if not key: return	❌ 无 key，静默退出
有充裕额度	AutoGen 案例 max_turns=20 × 4 角色	❌ RPM=3，跑十几分钟
有人盯着看	print 到 stdout	❌ 需要落日志文件

2.3 为什么这不能怪框架

这是示例的"工程假设"，不是框架的缺陷。 教材写示例的目标是"讲清原理"，默认读者在本地 IDE 里手动跑------所以用 input() 让读者提问、用 if not key: return 提醒读者配 key，都是合理的教学设计。

🔑 判据 ：看到示例跑不起来，先分清"框架不行"还是"示例没为无头环境设计"。 本轮四个问题里，只有一个是框架层面的（依赖冲突），其余三个都是示例的假设。

2.4 修复方案：把示例改造成"可无人运行"

修复 1：把交互改成参数

import sys
query = sys.argv[1] if len(sys.argv) > 1 else "What is the latest Huawei phone model?"

修复 2：缺 key 时显式失败，而不是静默返回

if not os.getenv("TAVILY_API_KEY"):
    raise SystemExit("[FATAL] TAVILY_API_KEY 未配置")   # 非零退出码

修复 3：给搜索工具做可替换后端（本轮做法）------把 Tavily 换成可用的搜索源，让"搜索节点"在缺 key 时仍能验证：

def search(q):
    if os.getenv("TAVILY_API_KEY"):
        return tavily_search(q)
    return fallback_search(q)      # 例如 Bing / 自建

修复 4：输出落盘 ------python3 -u script.py > run.log 2>&1，用 -u 关掉缓冲，否则日志到进程结束才落盘，中间无法监控 （本轮踩过：wc -l run.log 一直是 0）。

---

三、问题：多智能体的成本是"乘法"，不是"加法"

3.1 现场

AutoGen 案例的默认配置：

team_chat = RoundRobinGroupChat(
    participants=[product_manager, engineer, code_reviewer, user_proxy],   # 4 个
    termination_condition=termination,
    max_turns=20,                                                          # 20 轮
)

潜在调用次数 = 20 轮 × 最多 4 个发言者 = 最多 80 次 LLM 调用。 在 RPM=3 的额度下，仅排队就要 20 分钟以上（还不算每次推理本身的耗时）。

3.2 根因：轮数、角色数、调用数是三个相乘的量

LLM 调用总量 ≈ 轮数 × 每轮发言角色数
延迟 ≈ 调用总量 ÷ RPM          （限额越低，延迟被放大得越厉害）
成本 ≈ 调用总量 × 单次 token

教材示例写 max_turns=20 时，默认的是"本地调试、额度充裕"。参数本身没错，错在它被当成"可以直接搬到生产/受限额度环境"的配置。

3.3 为什么这是严重缺陷

1. 超线性膨胀 ：换成一个 6 角色、30 轮的协作，调用量直接到 180 次------成本和延迟以乘积方式爆炸。
2. 限额环境必断 ：本轮 RPM=3 下，AutoGen 若按默认配置跑，大概率在限流中反复重试甚至失败。
3. 难以预估 ：因为"每轮有几个角色发言"取决于终止条件的触发时点，事前的估算经常偏低。

3.4 修复方案

修复 1：先算账，再启动（本轮做法：把 4 角色/20 轮砍成 2 角色/4 轮）

EST = len(participants) * max_turns
assert EST <= BUDGET, f"预计 {EST} 次调用，超出预算 {BUDGET}"

修复 2：用"确定性终止"替代"轮数上限" ------TextMentionTermination("TERMINATE") 是主终止；max_turns 只当最后安全阀，且要设小。

修复 3：给协作加"进展检测"------连续 N 轮无新增信息即终止，避免"为了轮数而轮数"。

修复 4：成本护栏 ------把 token 预算当作与 max_turns 同级的参数暴露出来。

---

四、顺带发现的几个小问题

4.1 字段抽取"吞掉整段"

LangGraph 的 understand_query_node 用字符串切分抽搜索词：

search_query = text.split("搜索词：")[1].strip()

实测产出：

华为最新手机型号 2024，华为Pura 70，华为Mate 70，Huawei latest flagship phone selling points

模型在一行里列了多个候选，.strip() 把整行 都当成了搜索词------搜索质量随之下降（实测确实只搜回了华为的通用页面）。

修复 ：要求模型用结构化输出 （只给一个 search_query 字段），或至少 split("\n")[0] 再截断。

4.2 "口令接力"式协作很脆弱

AutoGen 案例里，每个角色的 system_message 结尾都埋了一句自然语言口令：

产品经理："......说完后说'请工程师开始实现'。"
工程师：  "......说完后说'请代码审查员检查'。"

协作的推进完全依赖模型记得说这句口令。 模型换一种说法、或者多说了别的，链条就断。

修复 ：口令改为机器可判定的信号 （像 TERMINATE 那样单独成行），并配 TextMentionTermination 之类的条件；让"交接"变成协议，而不是礼貌用语。

4.3 Python 3.14 让"能不能装"变成抽奖

本轮 Python 是 3.14.4 （很新）。实测这三个框架都能装、能导入------但这是运气好：主流框架的轮子主要按 3.10~3.12 发布。

修复 ：显式锁定 Python 3.11 / 3.12（尤其是有 C 扩展依赖时）；把"导入冒烟测试"放进 CI。

4.4 日志缓冲：进程没结束就什么都看不到

python3 script.py > run.log 时，stdout 被块缓冲 ------实测 wc -l run.log 长时间是 0 行，让人误判"卡死了"。

修复 ：用 python3 -u（unbuffered），或在代码里 print(..., flush=True)。

4.5 缺 key 时的"静默退出"会掩盖问题

if not key: print(...); return 这类写法，在批量/CI 场景里会看起来"成功"但什么都没做 （退出码 0）。修复：这类前置检查应 raise SystemExit(1)。

4.6 AgentScope 的 Msg.content 必须是"内容块列表"

实测直接把字符串塞进去会被 pydantic 拒绝：

pydantic_core._pydantic_core.ValidationError: 1 validation error for Msg
content
  Input should be a valid list [type=list_type, input_value='请给出一个关于智能体记忆的论点。', input_type=str]

修法：传内容块列表，而不是裸字符串。

Msg(name="user", content=[{"type": "text", "text": "你的问题"}], role="user")

这条其实是"好消息" ：它说明 AgentScope 用类型系统在编译期（构造时）拦住错误 ，而不是让错误在运行时悄悄变成一个无法解析的字符串------这正是它"结构化输出"理念的体现，也是第四章"正则解析自由文本"那类脆弱做法的正解。

---

五、由这次排障引出的设计原则

原则 1："示例能跑"≠"能在你的环境跑"------先列出它的环境假设

示例隐含了：交互式终端、特定 API key、充裕额度、可观测的 stdout。搬到服务器前，逐条核对这些假设，而不是先怀疑框架。

示例假设	服务器现实	处置
有交互式终端	无 stdin	改参数化
有 Tavily key	无	换后端 / 显式报错
额度充裕	RPM=3	砍轮数 + 加护栏
有人看输出	只有日志	-u + 落盘

原则 2：一个框架一个环境

公共依赖（protobuf / pydantic / httpx）是冲突高发区。框架数量与维护成本正相关 ------本轮 autogen 与 agentscope 已撞 protobuf。

原则 3：多智能体的资源消耗是乘积，不是求和

调用量 = 轮数 × 角色数。先算账，再启动------尤其在低 RPM 的额度下。

原则 4："装上了"不是"能用"------"能跑一个最小回合"也不是"案例跑通"

AgentScope 一开始只做了"安装 + 导入"，我在终检时补跑了一个最小双智能体回合 （Researcher → Writer，退出码 0）才敢写"能用"。但**"三国狼人杀"那种多轮案例仍未跑**，必须与前者分开标注 。拿安装日志冒充运行结果，是最容易自欺的一步。

---

六、快速诊断速查表

# 1) 依赖冲突自检（装完框架后必跑）
pip check 2>&1 | head -20
python3 - <<'PY'
mods = ["langgraph", "langchain_openai", "autogen_core", "autogen_agentchat", "agentscope"]
for m in mods:
    try:
        __import__(m); print("OK  ", m)
    except Exception as e:
        print("FAIL", m, type(e).__name__, str(e)[:80])
import importlib.metadata as md
print("protobuf:", md.version("protobuf"))
PY

# 2) 示例的"环境假设"体检（逐条 grep）
grep -n "input("            code/chapter6/**/*.py     # 是否有交互式阻塞
grep -n "os.getenv"         code/chapter6/**/*.py     # 依赖哪些 key
grep -n "max_turns"         code/chapter6/**/*.py     # 轮数上限
grep -n "TAVILY_API_KEY"    code/chapter6/**/*.py     # 外部服务硬依赖

# 3) 成本预估（先算再跑）
python3 - <<'PY'
participants, max_turns, rpm = 4, 20, 3
est = participants * max_turns
print(f"预计 LLM 调用 <= {est} 次；RPM={rpm} 时排队下限约 {est/rpm:.0f} 分钟")
PY

# 4) 无头运行模板（关缓冲 + 落日志 + 看退出码）
python3 -u script.py > run.log 2>&1; echo "EXIT=$?"; tail -20 run.log