migrate-to-glm

name	migrate-to-glm
description	将 Agno 项目代码从 Gemini、OpenAIResponses 或 OpenAIChat 迁移到 GLM 模型（OpenAILike）。用于用户需要切换模型、替换 Gemini/OpenAI 为 GLM、配置 OpenAI 兼容模型时。

迁移到 GLM 模型

将 Agno 项目中使用 Gemini、OpenAIResponses 或 OpenAIChat 的代码迁移到 GLM 模型（通过 OpenAILike）。

适用场景

• 代码使用 Gemini(id="gemini-3-flash-preview")，需要切换到 GLM
• 代码使用 OpenAIResponses(id="gpt-5.2") 等 OpenAI 系模型，需要切换到 GLM
• 代码使用 OpenAIChat(id="gpt-4o-mini") 等 OpenAI Chat 模型，需要切换到 GLM
• 需要统一项目的模型配置为 GLM-4.7 或其他 OpenAI 兼容模型

迁移步骤

1. 检查当前代码

使用 Grep 查找需要迁移的文件：

# 来自 Gemini 的文件
grep -r "from agno.models.google import Gemini" .
grep -r "Gemini(id=" .

# 来自 OpenAIResponses 的文件（同一 openai 模块，换为 OpenAILike）
grep -r "OpenAIResponses(id=" .
grep -r "from agno.models.openai import OpenAIResponses" .

# 来自 OpenAIChat 的文件（同一 openai 模块，换为 OpenAILike）
grep -r "OpenAIChat(id=" .
grep -r "from agno.models.openai import OpenAIChat" .

2. 更新单个文件

对每个需要迁移的 Python 文件执行以下操作。

场景 A：从 Gemini 迁移

A1. 替换 import 语句

# 旧代码
from agno.models.google import Gemini

# 新代码
import os
from dotenv import load_dotenv
from agno.models.openai import OpenAILike

load_dotenv()

A2. 替换模型配置

# 旧代码
model=Gemini(id="gemini-3-flash-preview")

# 新代码
model=OpenAILike(
    id=os.getenv("MODEL_ID", "GLM-4.7"),
    base_url=os.getenv("MODEL_BASE_URL", "https://open.bigmodel.cn/api/coding/paas/v4"),
    api_key=os.getenv("MODEL_API_KEY"),
)

场景 B：从 OpenAIResponses 迁移

同一文件已使用 agno.models.openai，只需换类名并改为 GLM 配置（如 CultureManager、Agent 等）。

B1. 替换 import 语句

# 旧代码
from agno.models.openai import OpenAIResponses

# 新代码
import os
from dotenv import load_dotenv
from agno.models.openai import OpenAILike

load_dotenv()

B2. 替换模型配置

# 旧代码
model=OpenAIResponses(id="gpt-5.2")

# 新代码
model=OpenAILike(
    id=os.getenv("MODEL_ID", "GLM-4.7"),
    base_url=os.getenv("MODEL_BASE_URL", "https://open.bigmodel.cn/api/coding/paas/v4"),
    api_key=os.getenv("MODEL_API_KEY"),
)

实战示例（02_agents/culture/01_create_cultural_knowledge.py）： CultureManager 的 model 从 OpenAIResponses(id="gpt-5.2") 改为上述 OpenAILike 配置即可，其他逻辑不变。

场景 C：从 OpenAIChat 迁移

同一文件已使用 agno.models.openai，与场景 B 操作相同：换类名为 OpenAILike，并改为 GLM 环境变量配置。常见于护栏、审核等示例（如 gpt-4o-mini）。

C1. 替换 import 语句

# 旧代码
from agno.models.openai import OpenAIChat

# 新代码
import os
from dotenv import load_dotenv
from agno.models.openai import OpenAILike

load_dotenv()

C2. 替换模型配置

# 旧代码
model=OpenAIChat(id="gpt-4o-mini")

# 新代码
model=OpenAILike(
    id=os.getenv("MODEL_ID", "GLM-4.7"),
    base_url=os.getenv("MODEL_BASE_URL", "https://open.bigmodel.cn/api/coding/paas/v4"),
    api_key=os.getenv("MODEL_API_KEY"),
)

注意： 同一文件中若有多个 Agent(...) 或其它使用模型的地方，每一处 model=OpenAIChat(...) 都要替换为上述 OpenAILike 配置。

3. 配置环境变量

创建或更新 .env 文件

在项目根目录创建 .env 文件：

MODEL_ID=GLM-4.7
MODEL_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4
MODEL_API_KEY=your-api-key-here

确保 .env 在 .gitignore 中

检查 .gitignore 包含：

.env

4. 安装依赖

uv add python-dotenv openai sqlalchemy yfinance

Embedder 迁移（知识库场景）

如果代码使用了知识库（Knowledge）和向量搜索，需要同时迁移 Embedder。

1. 替换 import

# 旧代码
from agno.knowledge.embedder.google import GeminiEmbedder

# 新代码
from agno.knowledge.embedder.openai import OpenAIEmbedder

2. 替换 Embedder 配置

# 旧代码
embedder=GeminiEmbedder(id="gemini-embedding-001")

# 新代码
embedder=OpenAIEmbedder(
    id=os.getenv("EMBEDDER_MODEL", "embedding-3"),
    api_key=os.getenv("EMBEDDER_API_KEY"),
    base_url=os.getenv("EMBEDDER_BASE_URL", "https://open.bigmodel.cn/api/paas/v4/"),
)

3. 更新 .env 文件

添加 Embedder 相关环境变量：

# Agent 模型配置
MODEL_ID=GLM-4.7
MODEL_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4
MODEL_API_KEY=your-api-key

# Embedder 配置（用于知识库向量化）
EMBEDDER_MODEL=embedding-3
EMBEDDER_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
EMBEDDER_API_KEY=your-embedder-api-key

注意： Embedder 的 base_url 使用标准端点（paas/v4/），不是 coding 端点。

4. 完整示例（Knowledge 场景）

迁移前：

from agno.knowledge import Knowledge
from agno.knowledge.embedder.google import GeminiEmbedder
from agno.vectordb.chroma import ChromaDb

knowledge = Knowledge(
    name="Agno Documentation",
    vector_db=ChromaDb(
        name="agno_docs",
        embedder=GeminiEmbedder(id="gemini-embedding-001"),
    ),
)

迁移后：

import os
from dotenv import load_dotenv

from agno.knowledge import Knowledge
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.vectordb.chroma import ChromaDb

load_dotenv()

knowledge = Knowledge(
    name="Agno Documentation",
    vector_db=ChromaDb(
        name="agno_docs",
        embedder=OpenAIEmbedder(
            id=os.getenv("EMBEDDER_MODEL", "embedding-3"),
            api_key=os.getenv("EMBEDDER_API_KEY"),
            base_url=os.getenv("EMBEDDER_BASE_URL", "https://open.bigmodel.cn/api/paas/v4/"),
        ),
    ),
)

5. 智谱 AI Embedding 模型

可用模型：

• embedding-3：新一代向量模型（推荐）
• embedding-2：上一代模型

API 端点：

https://open.bigmodel.cn/api/paas/v4/embeddings

向量维度：

• embedding-3: 2048 维
• embedding-2: 1024 维

6. ChromaDB 兼容性问题

Python 3.14 不兼容：

当前 ChromaDB 与 Python 3.14 存在兼容性问题：

pydantic.v1.errors.ConfigError: unable to infer type for attribute "chroma_server_nofile"

解决方案：

1. 降级到 Python 3.12 或 3.13（推荐）
2. 等待 ChromaDB 更新
3. 改用其他向量数据库（如 Qdrant、Weaviate）

受影响文件：

• 07_agent_search_over_knowledge.py
• 08_custom_tool_for_self_learning.py
• 10_human_in_the_loop.py

完整示例

迁移前

from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.yfinance import YFinanceTools

agent = Agent(
    name="Finance Agent",
    model=Gemini(id="gemini-3-flash-preview"),
    tools=[YFinanceTools()],
)

迁移后

import os
from dotenv import load_dotenv

from agno.agent import Agent
from agno.models.openai import OpenAILike
from agno.tools.yfinance import YFinanceTools

load_dotenv()

agent = Agent(
    name="Finance Agent",
    model=OpenAILike(
        id=os.getenv("MODEL_ID", "GLM-4.7"),
        base_url=os.getenv("MODEL_BASE_URL", "https://open.bigmodel.cn/api/coding/paas/v4"),
        api_key=os.getenv("MODEL_API_KEY"),
    ),
    tools=[YFinanceTools()],
)

批量迁移工作流（推荐）

适用场景

• 目录下有多个文件需要迁移（如 00_quickstart 目录）
• 需要系统化地处理大量文件

完整流程

1. 查找所有需要迁移的文件

使用 Grep 查找目录中所有使用 Gemini 的文件：

# 查找 import 语句
Grep pattern="from agno.models.google import Gemini" path="00_quickstart"

# 查找模型实例化
Grep pattern="model=Gemini" path="00_quickstart"

输出示例：

00_quickstart/03_agent_with_typed_input_output.py
00_quickstart/05_agent_with_memory.py
00_quickstart/06_agent_with_state_management.py
...

2. 逐个文件迁移

对每个文件执行以下步骤：

A. 替换 import 语句

读取文件头部，找到 import 部分并替换：

# 旧代码（多种变体）
from agno.models.google import Gemini

# 或
from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.yfinance import YFinanceTools

# 新代码（统一格式）
import os

from dotenv import load_dotenv

from agno.agent import Agent
from agno.models.openai import OpenAILike
from agno.tools.yfinance import YFinanceTools

load_dotenv()

使用 StrReplace 精确替换，保持其他 import 不变。

B. 替换所有模型配置

一个文件可能有多个 Agent/MemoryManager 使用模型，需要全部替换：

# 单个 Agent 的情况
model=Gemini(id="gemini-3-flash-preview")
# 替换为 ↓
model=OpenAILike(
    id=os.getenv("MODEL_ID", "GLM-4.7"),
    base_url=os.getenv("MODEL_BASE_URL", "https://open.bigmodel.cn/api/paas/v4/"),
    api_key=os.getenv("MODEL_API_KEY"),
)

# 多个 Agent 的情况（Team/Workflow）
# 文件中可能有 2-3 个 Agent，每个都需要替换
bull_agent = Agent(model=Gemini(...))  # 第 1 个
bear_agent = Agent(model=Gemini(...))  # 第 2 个
team = Team(model=Gemini(...))         # 第 3 个

重要： 使用 Grep 定位所有 model=Gemini，逐个替换。

3. 处理特殊情况

多 Agent 文件（Team/Workflow）

文件包含多个 Agent 实例，需要替换所有：

# 示例：11_multi_agent_team.py 有 3 个模型实例
bull_agent = Agent(model=Gemini(...))      # 替换 1
bear_agent = Agent(model=Gemini(...))      # 替换 2
multi_agent_team = Team(model=Gemini(...)) # 替换 3

MemoryManager 模型配置

# 旧代码
memory_manager = MemoryManager(
    model=Gemini(id="gemini-3-flash-preview"),
    db=agent_db,
)

# 新代码
memory_manager = MemoryManager(
    model=OpenAILike(
        id=os.getenv("MODEL_ID", "GLM-4.7"),
        base_url=os.getenv("MODEL_BASE_URL", "https://open.bigmodel.cn/api/paas/v4/"),
        api_key=os.getenv("MODEL_API_KEY"),
    ),
    db=agent_db,
)

4. 批量提交策略

推荐分批提交：

# 第 1 批：基础文件（1-4）
git add 00_quickstart/01_agent_with_tools.py \
        00_quickstart/02_agent_with_structured_output.py \
        00_quickstart/03_agent_with_typed_input_output.py \
        00_quickstart/04_agent_with_storage.py
git commit -m "feat: 迁移基础示例文件到 GLM (01-04)"

# 第 2 批：高级特性（5-9）
git add 00_quickstart/05_agent_with_memory.py \
        00_quickstart/06_agent_with_state_management.py \
        00_quickstart/07_agent_search_over_knowledge.py \
        00_quickstart/08_custom_tool_for_self_learning.py \
        00_quickstart/09_agent_with_guardrails.py
git commit -m "feat: 迁移高级特性文件到 GLM (05-09)"

# 第 3 批：协作场景（10-12）
git add 00_quickstart/10_human_in_the_loop.py \
        00_quickstart/11_multi_agent_team.py \
        00_quickstart/12_sequential_workflow.py
git commit -m "feat: 迁移协作场景文件到 GLM (10-12)"

或一次性提交：

git add 00_quickstart/*.py
git commit -m "feat: 批量迁移 00_quickstart 所有文件到 GLM

- 迁移 01-12 所有示例文件到 OpenAILike + GLM-4.7
- 添加 dotenv 环境变量加载
- 统一模型配置方式
- 涵盖：基础、记忆、状态、知识库、工具、护栏、团队、工作流"

批量迁移实战经验

00_quickstart 目录迁移总结

文件数量： 12 个 Python 文件
涉及模型实例： 约 20+ 个（包括 Agent、Team、Workflow、MemoryManager）
耗时： 约 15-20 分钟

关键发现：

1. import 替换模式一致

   • 所有文件都遵循相同的 import 替换模式
   • 添加 import os 和 load_dotenv() 是固定操作

2. 模型配置位置不同

   • 单 Agent 文件：1 个模型配置
   • Team 文件：2-3 个模型配置（成员 + 领导）
   • Workflow 文件：3 个模型配置（每个步骤）
   • Memory 文件：2 个模型配置（Agent + MemoryManager）

3. 容易遗漏的地方

   • MemoryManager 的模型配置
   • Team 中 members 的模型配置
   • Workflow 中每个 Step 的 Agent 模型配置

4. Grep 是关键工具

   • 用于查找所有 model=Gemini 实例
   • 避免遗漏任何一个配置

最佳实践

迁移前：

# 1. 查找文件列表（按实际使用的模型类选择）
Grep pattern="from agno.models.google import Gemini" path="target_dir"
Grep pattern="from agno.models.openai import OpenAIResponses" path="target_dir"
Grep pattern="from agno.models.openai import OpenAIChat" path="target_dir"

# 2. 统计需要替换的模型实例数量
Grep pattern="model=Gemini" path="target_dir"
Grep pattern="OpenAIResponses\(id=" path="target_dir"
Grep pattern="OpenAIChat\(id=" path="target_dir"

迁移中：

• 按文件顺序逐个处理
• 每个文件先替换 import，再替换模型配置
• 使用 Grep 确认该文件所有模型配置已替换（model=Gemini、OpenAIResponses(id=、OpenAIChat(id= 等）

迁移后：

# 验证没有遗漏（按迁移前使用的模型类检查）
Grep pattern="Gemini\(id=" path="target_dir"
Grep pattern="OpenAIResponses\(id=" path="target_dir"
Grep pattern="OpenAIChat\(id=" path="target_dir"
# 以上均应返回：无结果

# 测试运行（可选）
export MODEL_ID=GLM-4.7 \
       MODEL_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4 \
       MODEL_API_KEY=your-key
uv run target_dir/01_sample.py

处理顺序建议

按复杂度从低到高处理：

1. 简单文件（单 Agent，1 个模型配置）

   • 01_agent_with_tools.py
   • 04_agent_with_storage.py
   • 09_agent_with_guardrails.py

2. 中等文件（Agent + MemoryManager，2 个配置）

   • 05_agent_with_memory.py
   • 08_custom_tool_for_self_learning.py
   • 10_human_in_the_loop.py

3. 复杂文件（多 Agent，3+ 个配置）

   • 11_multi_agent_team.py（3 个：bull + bear + team）
   • 12_sequential_workflow.py（3 个：data + analyst + report）

4. 特殊文件（有额外注意事项）

   • 02_agent_with_structured_output.py（注意：GLM-4.7 不支持 output_schema）
   • 03_agent_with_typed_input_output.py（同上）
   • 06_agent_with_state_management.py（有自定义工具）
   • 07_agent_search_over_knowledge.py（有知识库配置）

02_agents/guardrails 目录迁移总结

文件数量： 5 个 Python 文件
涉及模型类： 混合使用 OpenAIResponses(id="gpt-5.2") 与 OpenAIChat(id="gpt-4o-mini")
涉及模型实例： 共 8 处（单文件内可能 1～2 个 Agent）

关键发现：

1. 同一目录可能混用多种 OpenAI 模型类

   • 需同时 Grep OpenAIResponses 与 OpenAIChat，避免遗漏
   • 替换步骤相同：import 改为 OpenAILike + load_dotenv，模型配置改为环境变量

2. 单文件多实例

   • 如 pii_detection.py、openai_moderation.py 中有 2 个 Agent(model=...)，需全部替换
   • 迁移前用 Grep 统计该文件中 OpenAIChat(id= 或 OpenAIResponses(id= 出现次数，迁移后再次 Grep 确认为 0

3. 护栏/审核示例无额外依赖

   • 仅需 python-dotenv，无需改 Embedder 或向量库
   • 迁移后无新增 linter 报错即可

Grep 示例（针对目录）：

# 一次性找出目录内所有需迁移的模型
Grep pattern="OpenAIResponses\(id=" path="02_agents/guardrails"
Grep pattern="OpenAIChat\(id=" path="02_agents/guardrails"

注意事项

模型兼容性

• GLM-4.7 不支持 output_schema（结构化输出）

  • 如果代码使用了 output_schema=SomeModel，需要移除或改用 glm-4-flash
  • 错误表现：返回 Markdown 而非 JSON，导致解析失败

• 工具调用（Tool Calling）：GLM-4.7 支持，正常工作

• 流式输出（Stream）：支持

• 多轮对话（History）：支持

API 端点

GLM 模型有两个 API 端点：

# 标准端点（推荐）
base_url="https://open.bigmodel.cn/api/paas/v4/"

# Coding 端点（某些场景）
base_url="https://open.bigmodel.cn/api/coding/paas/v4"

根据实际情况选择。

常见依赖

迁移时通常需要安装：

uv add python-dotenv  # 环境变量加载
uv add openai         # OpenAI SDK（OpenAILike 依赖）
uv add sqlalchemy     # 数据库支持
uv add yfinance       # 金融工具（如果使用）

验证迁移

检查清单

• 所有 Gemini 或 OpenAIResponses 的 model 配置已替换为 OpenAILike
• 对应 import 已改为 from agno.models.openai import OpenAILike（并移除/替换 Gemini 或 OpenAIResponses）
• 添加了 dotenv 加载（load_dotenv()）
• 模型配置使用环境变量（MODEL_ID、MODEL_BASE_URL、MODEL_API_KEY）
• .env 文件已创建并配置
• .env 在 .gitignore 中
• 依赖已安装（python-dotenv, openai）
• 测试运行成功

测试命令

# 方式 1：使用 .env 文件
uv run path/to/file.py

# 方式 2：直接 export（测试用）
export MODEL_ID=GLM-4.7 \
       MODEL_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4 \
       MODEL_API_KEY=your-key
uv run path/to/file.py

常见问题

Q: 文件中用的是 OpenAIResponses 而不是 Gemini，怎么迁移？

场景： 如 02_agents/culture/01_create_cultural_knowledge.py 使用 OpenAIResponses(id="gpt-5.2")，未使用 Gemini。

做法： 同样迁到 GLM，按「场景 B：从 OpenAIResponses 迁移」处理即可：

1. Import：from agno.models.openai import OpenAIResponses → from agno.models.openai import OpenAILike（同一模块，只改类名），并加上 import os、load_dotenv、load_dotenv()。
2. 模型配置：model=OpenAIResponses(id="...") → model=OpenAILike(id=os.getenv("MODEL_ID", "GLM-4.7"), base_url=..., api_key=...)。
3. .env：配置 MODEL_ID、MODEL_BASE_URL、MODEL_API_KEY。

无需改 Gemini 相关 import，只做上述替换即可。

Q: 余额不足错误

Error code: 429 - {'error': {'code': '1113', 'message': '余额不足或无可用资源包,请充值。'}}

解决：检查 API key 余额，充值后重试。

排查步骤：

1. 确认 API key 正确配置在 .env 文件中
2. 登录智谱 AI 开放平台检查余额
3. 充值后重新运行

Q: 结构化输出失败

WARNING  Failed to parse cleaned JSON: Expecting value: line 1 column 1 (char 0)
WARNING  Failed to convert response to output_schema

原因：GLM-4.7 不支持 output_schema，会返回 Markdown 格式而非 JSON。

解决方案：

1. 移除 output_schema 参数（推荐）

   agent = Agent(
       model=OpenAILike(...),
       # output_schema=StockAnalysis,  # 删除此行
   )
   

2. 改用文本解析

   response = agent.run("分析英伟达")
   # response.content 是 Markdown 文本，而非结构化对象
   print(response.content)
   

3. 换用支持结构化输出的模型

   • glm-4-flash 可能支持（需测试）
   • 或保留 Gemini 用于结构化输出场景

受影响文件：

• 02_agent_with_structured_output.py
• 03_agent_with_typed_input_output.py

Q: API 认证失败

ERROR    Model authentication error from OpenAI API: OPENAI_API_KEY not set.

原因：.env 文件未正确加载或环境变量未设置。

解决方案：

1. 检查 .env 文件位置

   • 必须在项目根目录
   • 文件名为 .env（不是 env.txt 或其他）

2. 检查 load_dotenv() 调用

   from dotenv import load_dotenv
   load_dotenv()  # 必须在读取环境变量前调用
   

3. 手动 export 测试

   export MODEL_ID=GLM-4.7
   export MODEL_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4
   export MODEL_API_KEY=your-api-key
   uv run file.py
   

4. 检查依赖是否安装

   uv add python-dotenv
   

Q: 文件中有多个模型配置，如何确保全部替换？

问题场景：

• Team 文件有 3 个 Agent（bull + bear + team leader）
• Workflow 文件有 3 个 Step Agent
• Memory 文件有 Agent + MemoryManager

解决方案：

1. 使用 Grep 查找所有实例

   Grep pattern="model=Gemini" path="file.py"
   

2. 逐个替换

   • 不要假设只有 1 个
   • 按照 Grep 结果逐个确认

3. 验证完成

   # 再次 Grep，应该无结果
   Grep pattern="Gemini\(id=" path="file.py"
   

实战示例（11_multi_agent_team.py）：

# 第 1 个：bull_agent
model=Gemini(id="gemini-3-flash-preview")  # 替换

# 第 2 个：bear_agent  
model=Gemini(id="gemini-3-flash-preview")  # 替换

# 第 3 个：team
model=Gemini(id="gemini-3-flash-preview")  # 替换

Q: 运行时提示找不到模块怎么办？

常见缺失依赖：

# ModuleNotFoundError: No module named 'sqlalchemy'
uv add sqlalchemy

# ModuleNotFoundError: No module named 'openai'
uv add openai

# ModuleNotFoundError: No module named 'yfinance'
uv add yfinance

# ModuleNotFoundError: No module named 'dotenv'
uv add python-dotenv

一次性安装所有：

uv add python-dotenv openai sqlalchemy yfinance

Q: 应该使用哪个 API 端点？

两个端点对比：

端点	URL	适用场景
标准端点	https://open.bigmodel.cn/api/paas/v4/	通用场景，推荐使用
Coding 端点	https://open.bigmodel.cn/api/coding/paas/v4	代码生成、编程场景

实战经验：

• 00_quickstart 示例使用 Coding 端点 成功运行
• 两个端点在金融分析场景中表现相近
• 建议根据具体业务场景测试选择

配置方式：

# 标准端点
MODEL_BASE_URL=https://open.bigmodel.cn/api/paas/v4/

# Coding 端点
MODEL_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4

Q: 迁移后性能有变化吗？

实测对比（00_quickstart 示例）：

指标	Gemini 3 Flash	GLM-4.7
响应速度	20-30s	25-35s
工具调用准确性	高	高
中文理解	好	优秀
推理质量	高	高
Token 消耗	中等	中等

关键发现：

• GLM-4.7 在中文场景下表现更自然
• 工具调用（如 YFinanceTools）准确性相当
• 不支持结构化输出是主要限制

Q: 如何处理 MemoryManager 的模型配置？

问题： MemoryManager 需要单独配置模型，容易遗漏。

正确做法：

# 05_agent_with_memory.py 示例

# MemoryManager 的模型配置（容易遗漏）
memory_manager = MemoryManager(
    model=OpenAILike(  # 需要替换
        id=os.getenv("MODEL_ID", "GLM-4.7"),
        base_url=os.getenv("MODEL_BASE_URL", "https://open.bigmodel.cn/api/paas/v4/"),
        api_key=os.getenv("MODEL_API_KEY"),
    ),
    db=agent_db,
)

# Agent 的模型配置
agent = Agent(
    model=OpenAILike(...),  # 也需要替换
    memory_manager=memory_manager,
)

检查方法：

# 查找所有 MemoryManager
Grep pattern="MemoryManager" path="file.py"

# 确认其模型配置也已替换

Q: 知识库（Knowledge）场景如何迁移 Embedder？

问题： 使用知识库的文件需要同时迁移 Embedder 和 Agent 模型。

完整迁移步骤：

1. 替换 Embedder import

   # from agno.knowledge.embedder.google import GeminiEmbedder
   from agno.knowledge.embedder.openai import OpenAIEmbedder
   

2. 替换 Embedder 配置

   embedder=OpenAIEmbedder(
       id=os.getenv("EMBEDDER_MODEL", "embedding-3"),
       api_key=os.getenv("EMBEDDER_API_KEY"),
       base_url=os.getenv("EMBEDDER_BASE_URL"),
   )
   

3. 更新 .env 文件

   # 添加 Embedder 配置
   EMBEDDER_MODEL=embedding-3
   EMBEDDER_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
   EMBEDDER_API_KEY=your-embedder-key
   

4. 完整示例（07_agent_search_over_knowledge.py）：

   knowledge = Knowledge(
       vector_db=ChromaDb(
           embedder=OpenAIEmbedder(
               id=os.getenv("EMBEDDER_MODEL"),
               api_key=os.getenv("EMBEDDER_API_KEY"),
               base_url=os.getenv("EMBEDDER_BASE_URL"),
           ),
       ),
   )
   
   agent = Agent(
       model=OpenAILike(...),  # Agent 模型
       knowledge=knowledge,
   )
   

受影响文件：

• 07_agent_search_over_knowledge.py
• 08_custom_tool_for_self_learning.py
• 10_human_in_the_loop.py

Q: ChromaDB 在 Python 3.14 不兼容怎么办？

错误信息：

pydantic.v1.errors.ConfigError: unable to infer type for attribute "chroma_server_nofile"

原因： ChromaDB 依赖 Pydantic v1，与 Python 3.14 不兼容。

解决方案：

1. 降级 Python 版本（推荐）

   # 使用 Python 3.12 或 3.13
   pyenv install 3.13.0
   pyenv local 3.13.0
   

2. 改用其他向量数据库

   • Qdrant：支持 Python 3.14
   • Weaviate：支持 Python 3.14
   • Milvus：支持 Python 3.14

3. 等待 ChromaDB 更新

   • 关注 ChromaDB GitHub 仓库
   • 等待兼容 Pydantic v2 的版本

临时方案：

• 跳过需要 ChromaDB 的示例文件
• 或在独立的 Python 3.12 环境中运行

Q: Embedder 和 Agent 模型可以用不同的 API Key 吗？

可以。 实际上，这是推荐的做法。

场景 1：使用相同 API Key

MODEL_API_KEY=shared-key
EMBEDDER_API_KEY=shared-key

场景 2：使用不同 API Key（推荐，便于成本跟踪）

MODEL_API_KEY=agent-model-key  # 用于 GLM-4.7 推理
EMBEDDER_API_KEY=embedder-key  # 用于 embedding-3 向量化

优势：

• 分开计费和成本跟踪
• 不同场景配置不同的速率限制
• 提高安全性（最小权限原则）

Q: Embedder 的 base_url 为什么和 Agent 不同？

Agent 模型端点：

https://open.bigmodel.cn/api/coding/paas/v4  # Coding 端点

Embedder 端点：

https://open.bigmodel.cn/api/paas/v4/  # 标准端点

原因：

• Agent 模型（GLM-4.7）在 Coding 端点表现更好
• Embedder 模型（embedding-3）使用标准端点
• 两个端点的 API 规范略有不同

配置示例：

MODEL_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4
EMBEDDER_BASE_URL=https://open.bigmodel.cn/api/paas/v4/

注意： Embedder 的 URL 末尾有斜杠 /。

性能对比

特性	Gemini 3 Flash	GLM-4.7
工具调用	✅	✅
结构化输出	✅	❌
流式输出	✅	✅
多轮对话	✅	✅
响应速度	快	快
中文支持	好	优秀

回滚方案

如果迁移后出现问题，快速回滚：

1. 还原 import

   from agno.models.google import Gemini
   

2. 还原模型配置

   model=Gemini(id="gemini-3-flash-preview")
   

3. 移除 dotenv

   # 删除这两行
   from dotenv import load_dotenv
   load_dotenv()
   

4. 安装 Gemini 依赖

   uv add google-genai