第 11 章 · 知识库 Knowledge Sources

本章目标：掌握 knowledge_sources 的挂载方式（字符串/文本/PDF 等来源），理解 agent 级与 crew 级知识的初始化与存储差异，能正确配置 embedder，并能清晰辨析知识、工具、记忆三种机制的边界。

11.1 知识库是什么

Knowledge 给 agent 一间"参考资料室"：你把领域文档（字符串、txt、PDF、CSV、Excel、JSON，甚至网页）交给框架，它在任务执行时检索相关片段注入上下文，让回答有据可依，而不是靠模型的参数记忆"猜"。

与第 10 章记忆的区别一句话概括：记忆是运行中攒出来的经验，知识是上线前就准备好的教材。

11.2 快速上手：字符串知识源

python

import os

from crewai import Agent, Crew, Process, Task, LLM
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource

llm = LLM(
    model="openai/deepseek-chat",
    base_url="https://api.deepseek.com/v1",
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    temperature=0,          # 知识问答建议低温，减少自由发挥
)

# 1. 创建知识源：这里用一段关于用户画像的文本
content = "用户姓名是张伟。他 32 岁，住在杭州，是一名后端工程师，偏好 Python 技术内容。"
string_source = StringKnowledgeSource(content=content)

agent = Agent(
    role="用户助理",
    goal="基于已知资料准确回答关于用户的问题",
    backstory="严谨的私人助理，绝不编造资料里没有的信息。",
    llm=llm,
    allow_delegation=False,
    verbose=True,
)

task = Task(
    description="回答关于该用户的问题：{question}",
    expected_output="一句准确的中文回答。",
    agent=agent,
)

crew = Crew(
    agents=[agent],
    tasks=[task],
    process=Process.sequential,
    knowledge_sources=[string_source],   # 2. 在 crew 级挂载知识源
    verbose=True,
)

result = crew.kickoff(inputs={"question": "张伟住在哪个城市？他喜欢什么内容？"})
print(result.raw)

11.3 文件类知识源与目录约定

文件类知识源统一从项目的 knowledge/ 目录读取（相对路径）：

python

from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource
from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource
from crewai.knowledge.source.csv_knowledge_source import CSVKnowledgeSource

# 项目结构：
# your_project/
# ├── knowledge/
# │   ├── handbook.txt
# │   ├── policy.pdf
# │   └── sales.csv
# └── main.py

text_source = TextFileKnowledgeSource(file_paths=["handbook.txt"])
pdf_source = PDFKnowledgeSource(file_paths=["policy.pdf"])      # 注意是 pdf 不是 txt
csv_source = CSVKnowledgeSource(file_paths=["sales.csv"])

crew = Crew(
    ...,
    knowledge_sources=[text_source, pdf_source, csv_source],   # 可混合多个来源
)

路径约定

官方文档明确：文件类知识源的 file_paths 是相对 knowledge/ 目录的相对路径，写绝对路径或把文件放错位置是知识检索为空的最常见原因。网页内容可用 CrewDoclingSource（需安装 docling 包）。

11.4 Agent 级 vs Crew 级知识

知识可以挂在两层，它们的初始化时机和存储互相独立：

python

from crewai import Agent, Crew, Task
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource

# Agent 级：只有这个 agent 能检索到，独立存储（集合名 = agent 的 role）
private_knowledge = StringKnowledgeSource(
    content="内部机密：Q4 促销活动的折扣上限是 30%。"
)
specialist = Agent(
    role="促销策划师",
    goal="在折扣政策内设计方案",
    backstory="熟悉公司促销政策的资深策划。",
    knowledge_sources=[private_knowledge],   # agent 私有知识
    embedder={                               # agent 也可以有自己的 embedder
        "provider": "openai",
        "config": {"model_name": "text-embedding-3-small"},
    },
)

# Crew 级：全体成员共享（存储在名为 "crew" 的集合）
shared_knowledge = StringKnowledgeSource(content="公司产品线包括 A/B/C 三个系列。")

crew = Crew(
    agents=[specialist],
    tasks=[Task(description="设计双十一促销方案", expected_output="方案要点", agent=specialist)],
    knowledge_sources=[shared_knowledge],    # crew 共享知识
)

官方文档披露的初始化机制值得了解：kickoff() 时框架会给每个 agent 设置 crew 引用并调用 set_knowledge(crew_embedder=...) 初始化知识；agent 知识与 crew 知识存放在同一个 ChromaDB 实例的不同集合中（本地路径约 ~/.local/share/CrewAI/{project}/knowledge/），因此两层知识可以独立存在、互不污染。

11.5 embedder 配置

与记忆系统相同，知识检索默认使用 OpenAI embedding。三方兼容端点或本地模型的配置方式与第 10 章完全一致：

python

crew = Crew(
    agents=[agent],
    tasks=[task],
    knowledge_sources=[string_source],
    embedder={                                   # crew 级 embedder
        "provider": "openai",
        "config": {
            "model_name": "text-embedding-3-small",
            "api_key": os.getenv("DEEPSEEK_API_KEY"),
        },
    },
)
# 本地方案：provider 改为 "ollama"，config 加 url 指向本机 embeddings 接口

换模型 = 重建索引

更换 embedding 模型导致维度变化后，旧知识索引无法复用。处理方式与记忆一致：crewai reset-memories --knowledge（清 crew 知识）或 --agent-knowledge（清 agent 知识）后重新构建。

11.6 辨析：知识 vs 工具 vs 记忆

三者都"给模型补充信息"，但时机和确定性完全不同：

维度	Knowledge	工具（Tools）	记忆（Memory）
内容来源	上线前准备好的静态资料	运行时调用外部系统获取	运行中自动积累的经验
注入方式	框架在任务时检索注入，确定性高	模型自主决定是否调用	框架自动提取与召回
适合放什么	产品手册、政策、FAQ、领域事实	实时数据、写操作、计算	用户偏好、历史结论
更新频率	低（改资料需重建索引）	高（每次都是新值）	持续增长

选型口诀：稳定的查知识、动态的用工具、经历的靠记忆。把"今天天气"放进知识库、或指望 agent 每次都主动调 RAG 工具查手册，都是典型误用。

本章小结

knowledge_sources 支持 String/Text/PDF/CSV/Excel/JSON 等来源，文件统一放 knowledge/ 目录用相对路径；
agent 级与 crew 级知识独立初始化、分集合存储（本地 ChromaDB），互不干扰；
embedder 配置与记忆系统同构，可接三方 OpenAI 兼容端点或本地 Ollama；
更换 embedding 模型需用 crewai reset-memories --knowledge / --agent-knowledge 重建；
知识=静态教材（确定注入），工具=动态能力（模型自主调用），记忆=经验积累（自动沉淀）。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 使用 TextFileKnowledgeSource 时，官方对文件路径的约定是？

2. 关于 agent 级与 crew 级知识，下列说法正确的是？

3. 产品说明书（半年更新一次）最适合用哪种机制提供给 agent？

4. 更换了 embedding 模型后知识检索报错，正确的处理是？

🛠️ 动手实践

把一份你熟悉的 PDF 手册挂载为 crew 级知识源，设计 10 个问题测试检索准确性，记录答错案例并分析原因（检索未命中 vs 模型自由发挥）。
构造"agent 私有 + crew 共享"两层知识：让策划师能访问机密折扣政策而其他 agent 不能，验证两层隔离。
分别用"知识库"和"RAG 工具"（第 7 章 PDFSearchTool）实现同一个问答场景，对比两者被调用的确定性与回答稳定性，写出选型结论。

下一章解决"如何让 crew 的产出直接变成程序可用的数据"：第 12 章 · 输出处理。

第 11 章 · 知识库 Knowledge Sources ​

11.1 知识库是什么 ​

11.2 快速上手：字符串知识源 ​

11.3 文件类知识源与目录约定 ​

11.4 Agent 级 vs Crew 级知识 ​

11.5 embedder 配置 ​

11.6 辨析：知识 vs 工具 vs 记忆 ​

本章小结 ​

🧪 随堂测验

🛠️ 动手实践 ​

第 11 章 · 知识库 Knowledge Sources

11.1 知识库是什么

11.2 快速上手：字符串知识源

11.3 文件类知识源与目录约定

11.4 Agent 级 vs Crew 级知识

11.5 embedder 配置

11.6 辨析：知识 vs 工具 vs 记忆

本章小结

🛠️ 动手实践