LlamaIndex 与 smolagents:数据索引和行动执行是两条链
解释Document到Query Engine的证据流,以及工具行动、代码行动的执行边界,避免把检索框架当作权限系统。
“查退货规定再给客户答复”包含两件事:组织可检索的数据,以及选择并执行行动。LlamaIndex的主要抽象帮助组织数据和查询;smolagents的Agent围绕多步行动组织执行。可以把检索器包装成Agent工具,但这不会自动解决文档权限、证据正确性或代码沙箱问题。
Document如何变成可引用的Node
Document表示导入的数据及元信息,Node表示进一步拆分或转换后的单元。切块不能只保留文本:文档ID、页码或段落、版本、租户权限、父子关系要跟着走。一个Node即使检索分数很高,若无法定位回原文,也难以形成可核验引用。
Index组织节点,可能服务向量检索等不同查询方式;Retriever根据查询返回相关节点及分数;Query Engine在检索后组织上下文与回答生成,通常还包括合成策略。不要把Index理解为模型已经学会文档,文档删除或权限变化必须作用到存储与检索路径。使用 as_retriever() 和 as_query_engine() 时要明确自己要的是证据集合还是生成后的回答,后者可能额外调用模型并增加成本。
相同查询在不同用户下可能得到不同结果,权限过滤最好在候选召回阶段执行;若先取跨租户文本生成答案,再遮掉引用,泄漏已经发生。缓存键也要含权限范围、索引版本与查询配置。分数不是概率,阈值应根据检索器、领域与验证集校准。
ToolCallingAgent和CodeAgent的差异
smolagents提供工具调用与代码行动两种路径。工具行动通常由模型输出工具名和结构化参数,运行时校验后分派;代码行动让模型生成代码表达变量、循环、组合计算,代码执行器再产生观察结果。代码能把多次数据转换放到一个行动里,但扩大了可表达行为与故障面。
工具参数schema只约束形式,不证明业务操作安全;代码能运行也不证明计算逻辑正确。将 exec(model_text) 放进宿主进程,不构成沙箱。限制导入名只是其中一层:还需隔离文件系统、网络、凭据、CPU、内存、运行时间和进程权限,记录产物及退出原因。容器若挂载宿主敏感目录或高权限socket,同样可能穿透预期边界。
官方安全执行文档区分本地执行器与远程/隔离执行选择。选择执行后端时核对具体版本与支持能力;本文不假定任何后端“绝对安全”。模型生成的代码、工具返回内容和下载依赖都应按不可信输入处理;资源限制不能仅写在系统提示中。
跟做:证据过滤与工具白名单
Python 3.11+保存 data_actions.py 后运行 python data_actions.py。程序只用标准库,刻意不用向量模型,以便逐行观察租户过滤和引用传播。它不是LlamaIndex/smolagents内部实现,也没有执行生成代码。
"""数据引用和行动契约的标准库模型;不是 LlamaIndex/smolagents 实现。"""
from dataclasses import dataclass
@dataclass(frozen=True)
class Node:
id: str
document: str
text: str
tenant: str
NODES = [Node('n1', 'policy-v1', '退货 7天', 'shop-a'),
Node('n2', 'private-v1', '退货 30天', 'shop-b')]
def retrieve(term, tenant):
# 元数据过滤先于评分,不能将其他租户文本送给模型后再遮挡。
return [n for n in NODES if n.tenant == tenant and term in n.text]
def query(term, tenant):
nodes = retrieve(term, tenant)
return {'answer': nodes[0].text if nodes else '无证据',
'citations': [f'{n.document}#{n.id}' for n in nodes]}
def execute_tool(call, tenant):
if set(call) != {'name', 'arguments'} or call['name'] != 'query':
raise ValueError('tool contract')
args = call['arguments']
if set(args) != {'term'} or not isinstance(args['term'], str):
raise ValueError('arguments contract')
return query(args['term'], tenant)
if __name__ == '__main__':
print(execute_tool({'name': 'query', 'arguments': {'term': '退货'}}, 'shop-a'))
print(query('保修', 'shop-a'))
try:
execute_tool({'name': 'exec', 'arguments': {'code': 'print(1)'}}, 'shop-a')
except ValueError as error:
print('rejected:', str(error))实际输出:
{'answer': '退货 7天', 'citations': ['policy-v1#n1']}
{'answer': '无证据', 'citations': []}
rejected: tool contractshop-a只看到policy-v1里的7天规则;shop-b的30天文本不会进入候选结果。查询不存在的词输出无证据;exec不是允许的工具,所以在执行前拒绝。把tenant改为shop-b可以观察引用随证据变化,但实际应用的tenant应来自认证上下文,不能来自模型参数。
接入真实LlamaIndex时,把retrieve函数替换为配置了权限过滤的Retriever,保持返回Node ID与来源的契约;接入smolagents时,把查询封装为受控工具,并对模型返回的行动设预算。真实框架安装、embedding下载、外部模型和沙箱部署均未在本例运行,不能把这份输出当作这些系统的质量测评。
什么时候选择哪一层
主要难点在解析、索引、检索与答案合成,优先围绕数据链设计;主要难点在跨工具多步求解与可执行中间计算,才需要行动控制器。两条链组合时,检索结果属于工具观察而不是可信系统指令。数据里出现“请执行删除”不应改变工具权限。
答案找不到来源先查Node元数据是否在切块和后处理被丢弃;索引更新后仍答旧内容检查缓存和文档版本;代码行动超时检查执行器资源限制;工具行动反复调用检查观察结果是否被追加、停止条件是否可判断。机制和接口依据见 LlamaIndex索引指南 与 smolagents安全执行。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
LlamaIndex与smolagents为何偏向不同抽象?
参考思路与常见误区
前者用Document/Node/Index/Retriever/Query Engine组织数据与回答,后者围绕工具或代码行动推进多步任务;可把检索器作为工具组合。
常见误区:二者只是相同Agent接口的不同名字。
Node为什么需要保留文档版本和位置?
参考思路与常见误区
检索后的片段必须回溯原文并支持引用、更新、权限和错误定位;只有文本会丢失可核验来源。
常见误区:相似度高就无需来源。
权限过滤应该放在回答之后吗?
参考思路与常见误区
应在候选检索或更早的授权边界限制可访问证据;先给模型跨租户文本再遮引用无法消除泄漏。
常见误区:隐藏引用就能保护数据。
代码行动比工具行动增加了什么边界?
参考思路与常见误区
代码可表达循环和组合计算,同时需要隔离文件、网络、凭据、进程与资源;不能直接在宿主exec模型文本。
常见误区:限制import列表就构成完整沙箱。
Query Engine与Retriever如何选择?
参考思路与常见误区
需要证据集合时用检索层,需要合成回答时用查询引擎并关注额外模型成本、引用和拒答;接口输出含义不同。
常见误区:认为查询引擎只返回检索列表。