实用笔记：从信息检索到推理：构建可投入实际应用的智能体系统
《实用笔记》操作指南：从信息检索到推理：构建可用于实际生产的智能体系统——为采用该架构的团队提供合约、校验机制以及可直接插入的代码模块。
可将此文档视为《从检索到推理：利用知识图谱构建可投入生产的智能体AI系统》中理念的面向操作人员的重构版本：它明确了各个阶段、有序的组织了代码模块，并提供了可在交接时使用的恢复说明。 在“概览”阶段，若将其视为可度量的界面来使用效果最佳。在扩大范围之前，先记录一份理想的操作流程、一个故障案例以及回滚说明。 应将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一个位置，这样操作人员无需查看整个知识图谱即可进行审核。
from neo4j import GraphDatabase
import json
def get_grounded_context(user_query: str, entity_extractor, driver) -> str:
# Step 1: Extract entities from the user query
entities = entity_extractor(user_query) # e.g., ["Product X", "Supplier Y"]
# Step 2: Pull a relevant subgraph from Neo4j
with driver.session() as session:
result = session.run(
"""
MATCH (e)-[r]-(connected)
WHERE e.name IN $entities
RETURN e.name AS entity,
type(r) AS relationship,
connected.name AS related_entity,
connected.attributes AS attributes
LIMIT 50
""",
entities=entities
)
subgraph = [record.data() for record in result]
# Step 3: Format subgraph as structured context
context_str = json.dumps(subgraph, indent=2)
grounded_prompt = f"""
You are a reasoning agent. Use ONLY the following structured knowledge to answer.
If the answer isn't derivable from this context, say so explicitly.
KNOWLEDGE GRAPH CONTEXT:
{context_str}
USER QUERY: {user_query}
"""
return grounded_prompt
def plan_with_graph(goal: str, graph_schema: dict, llm) -> list[dict]:
schema_str = json.dumps(graph_schema, indent=2)
planning_prompt = f"""
You are a planning agent. Given the goal below, decompose it into steps.
Each step must reference a valid entity type or relationship from the schema.
Do not invent steps that require knowledge outside this schema.
GRAPH SCHEMA:
{schema_str}
GOAL: {goal}
Return a JSON list of steps. Each step must include:
- "action": what to do
- "graph_query": the Cypher query to retrieve required context
- "depends_on": list of prior step indices this step requires
"""
raw_plan = llm.complete(planning_prompt)
plan = json.loads(raw_plan)
return plan
def execute_with_validation(step: dict, intermediate_result: str, driver, llm) -> dict:
# Extract claims from the intermediate result
claim_extraction_prompt = f"""
Extract all factual claims from this text as a list of (subject, predicate, object) triples.
TEXT: {intermediate_result}
Return as JSON array.
"""
claims = json.loads(llm.complete(claim_extraction_prompt))
validation_results = []
with driver.session() as session:
for claim in claims:
result = session.run(
"""
MATCH (s {name: $subject})-[r]-(o {name: $object})
WHERE type(r) = $predicate OR $predicate IN r.aliases
RETURN count(r) AS match_count
""",
subject=claim["subject"],
predicate=claim["predicate"],
object=claim["object"]
)
record = result.single()
validation_results.append({
"claim": claim,
"validated": record["match_count"] > 0
})
unvalidated = [v for v in validation_results if not v["validated"]]
return {
"result": intermediate_result,
"validated": len(unvalidated) == 0,
"flagged_claims": unvalidated
}
操作检查清单
在处理操作检查清单阶段时，首先需明确相关约定：所需输入、成功标志以及部分故障时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。
在功能结果旁记录处理时间以及令牌或查询成本。提前了解成本情况，可避免在系统从演示环境切换到共享环境时出现意外账单。
缓存稳定的系统指令和工具架构。重复发送相同的前置数据是导致资源浪费的常见原因。
将分块策略与检索策略分开。当质量指标发生变化时，调整其中一项不应强制重新编写另一项。
对于会耗费资金或修改生产数据的操作，需经过人工审批。编译时的配置并不等同于业务上的完整性。
在关注质量的同时也要跟踪成本和延迟。虽然答案稍差一些，但成本只有原来的十分之一，或许才是适合生产环境的最佳选择。
在推广该技术栈之前，应先冻结版本，为关键流程记录标准样本，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如追求扎实的可靠性。
关于7e5e1dbfc22b的批量处理说明：请将提供商密钥移出代码仓库，设定单会话令牌上限，并将样本与评估用配置文件存放在一起，以便后续模型更换时保持可比性。
强化安全性的第0阶段若被视为可测量的目标，效果最佳。在扩大范围之前，应先记录一份标准样本、一个故障案例以及回滚说明。相比庞大的脚本，更应优先使用小型且可测试的单元。当某个步骤出现故障时，故障原因应能指向单一责任点，而非复杂的流程链。
强化措施细节 0/956：为该记录测量运行时间、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在强化措施的第一阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
强化措施细节 1/956：为该记录测量运行时间、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在处理强化措施的第2阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。
同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续才添加的完善措施。
强化措施细节2/956：需测量该环节的耗时、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
将强化措施的第3阶段视为一个可量化的对象来处理效果最佳。在扩大范围之前，先记录一份理想的操作日志、一个故障案例以及回滚说明。
要把这一阶段视为输入参数与验证后输出结果之间的契约。为相关文档命名，明确成功判定标准，杜绝无声的半完成状态。
强化措施细节 3/956：为该记录测量运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在强化措施的第4阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。配置应置于应用程序代码之外，环境文件、密钥存储以及功能标志应集中存放于一个操作人员可以审核的位置，无需查看整个系统结构。
强化措施细节 4/956：为该记录测量运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在处理强化措施的第5阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。 相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障应能指向单一的责任模块，而非复杂的流程链。
强化措施细节5/956：需测量该步骤的运行时间、错误类型以及代币消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该修改。
将强化措施的第6阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的运行示例、一个失败案例以及回滚说明。 在功能结果旁同时记录时间消耗及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外支出。
强化措施细节6/956：为该记录测量运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个别案例来决定是否保留该变更。
对于强化措施的第7阶段，在修改代码之前需明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏状态。同时需将正常流程与故障恢复流程一并记录下来。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续需要补充的内容。
强化措施细节7/956：为该记录测量运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个别案例来决定是否保留该变更。
在处理强化措施的第8阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合约定。 将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝默许的部分完成情况。
强化措施细节8/956：需测量该步骤的耗时、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
将强化措施的第9阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份标准操作示例、一个失败案例以及回滚说明。 应将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一处，以便操作人员无需查看全部代码结构即可进行审计。
强化措施细节 9/956：测量该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在强化措施的第10阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比复杂的脚本，更应采用小型且可测试的单元。当某一步骤失败时，故障原因应能指向单一责任方，而非混乱的整个流程。
强化措施细节 10/956：测量该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在处理强化措施第11阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。
在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在系统从演示环境过渡到共享环境时出现意外费用。
强化措施细节11/956：需测量该阶段的实际执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该修改。
将强化措施第12阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一个理想运行案例、一个失败案例以及回滚说明。
应同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续需要补充的内容。
强化措施细节 12/956：测量该记录的耗时、错误类型以及令牌消耗情况，然后依据固定的问题集而非个别案例来决定是否保留该变更。