大模型应用-进阶核心技能【14课：第二阶段项目实战与总结】

第14课：第二阶段项目实战与总结

⚠️ 版本兼容说明：本课脚本（14_full_system_demo.py）基于 langchain 1.x，使用 langchain_classic 兼容包提供 schema/text_splitter/chains/memory/tools/agents/prompts 等旧 API。新项目推荐使用 langchain_core + langgraph 重写 Agent 部分。

依赖：pip install langchain langchain-openai langchain-community langchain-classic chromadb sentence-transformers

学习目标

• 全面回顾第二阶段所学的核心技能
• 理解自研RAG与LangChain框架的关系和差异
• 通过综合实战项目整合所有知识
• 明确第三阶段的学习方向

1. 第二阶段技能全景

1.1 学习路线回顾

第二阶段围绕从原理到框架这条主线，完成了四大模块：

模块一：Embedding与向量化（第01课）

• 文本如何变成向量、余弦相似度原理、Embedding API调用
• 理解了"语义"如何被数学化表达

模块二：文档处理（第02-03课）

• 多种文档格式加载（PDF/TXT/CSV）
• 文本分块策略（固定长度、递归分割、语义分割）
• 理解了分块质量直接影响检索质量

模块三：向量数据库与RAG（第04-05课）

• Chroma/FAISS操作、完整的检索增强生成流程
• 独立搭建了第一个可用的RAG问答系统

模块四：LangChain与工程化（第11-13课）

• LangChain七大抽象、Agent开发、项目工程化部署
• 将自研系统升级为框架化、可部署的产品

1.2 技能清单

2. 自研RAG vs LangChain：深度对比

2.1 架构对比图

┌──────────────────────────────────────────────────────┐
│               自研RAG（第01-05课）                     │
│                                                      │
│  文档 → 手工读取 → 手工分块 → 调API向量化 → Chroma存储  │
│  查询 → 调API向量化 → Chroma检索 → 拼Prompt → 调LLM    │
│                                                      │
│  优点：理解每个环节的原理，调试时心中有数               │
│  缺点：扩展性差，新增格式/策略需改代码                  │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│             LangChain RAG（第11课）                    │
│                                                      │
│  文档 → Loader → Splitter → Embeddings → VectorStore  │
│  查询 → Retriever → Chain(含Memory) → LLM             │
│                                                      │
│  优点：组件可替换，生态丰富，社区支持                   │
│  缺点：抽象层多，调试时需要理解底层原理                 │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│           Agent增强（第12课）                          │
│                                                      │
│  查询 → Agent(LLM决策) → 工具调用(知识/设备/工单/库存)  │
│                                                      │
│  优点：能处理复杂多步骤任务，不只是问答                 │
│  缺点：调用链长，成本和延迟较高，行为不完全可控        │
└──────────────────────────────────────────────────────┘

2.2 代码量对比

LangChain将常见操作封装为高级抽象，大幅减少代码量。但自研版本帮助你理解了每个环节的原理，这在调试和优化时非常重要。

2.3 何时用哪种方式

3. 综合实战：MaintenanceAssistant

本课的脚本实现了一个完整的MaintenanceAssistant类，集成了：

• RAG知识库：20+条设备维修专业知识
• Agent工具：5个设备维修操作工具
• 对话记忆：多轮对话上下文自动管理
• 使用统计：记录各功能的调用次数和耗时

四个核心方法：

assistant = MaintenanceAssistant()

# 1. 知识问答 - 基于RAG检索
assistant.ask("液压泵过热怎么办？")

# 2. 故障诊断 - Agent多工具协作
assistant.diagnose("DEV-001", "液压泵异响")

# 3. 设备报告 - 结合设备信息和知识库
assistant.generate_report("DEV-002")

# 4. 多轮对话 - 带记忆的自然对话
assistant.chat("上次说的那个备件还有吗？")

4. 常见问题与排错指南

5. 实战经验总结

5.1 从自研到框架的思维转变

在第一阶段自研RAG时，我们关注的是"如何实现每个步骤"——如何读取文件、如何分块、如何调用Embedding API。这种实现思维帮助我们理解了底层原理。

进入LangChain框架后，思维需要转变为"如何组合组件"——选择合适的Loader、配置Splitter参数、编排Chain流程。框架的价值在于：你已经不需要关心"如何实现"，而是关注"如何组合"。

关键领悟：

• 自研阶段让你理解了每个环节的trade-off（分块大小的影响、检索top_k的选择等）
• 框架阶段让你专注于系统设计和用户体验
• 两者结合：用框架做脚手架，在关键环节（如检索策略、prompt设计）深入优化

5.2 Agent开发的三个认知升级

1. 工具docstring就是Agent的"眼睛"：Agent只能通过docstring了解工具，写得不好Agent就用错
2. 不要预设执行路径：Agent的魅力在于它自主规划，你只需提供工具和目标
3. verbose是最好的老师：每次调试都打开verbose，观察Agent的思考过程

5.3 工程化不是可选项

很多开发者习惯"写完脚本就交付"。但在AI应用开发中：

• 没有配置管理 → API Key泄露、环境不一致
• 没有日志 → 出了问题无法排查
• 没有容器化 → “在我电脑上能跑”
• 没有接口规范 → 前后端对接困难

第13课的项目脚手架不是过度设计，而是生产环境的最低要求。

5.4 性能与成本的平衡

6. 第二阶段知识图谱

                    ┌─ 01-Embedding向量化 ─┐
                    │                      │
    基础层 ──────── │  02-文档加载          │
                    │  03-文本分块          │── 理解原理
                    │  04-向量数据库        │
                    └──────────────────────┘
                              │
                              ▼
                    ┌─ 05-自研RAG系统 ─────┐
    实践层 ──────── │                      │── 动手能力
                    └──────────────────────┘
                              │
                              ▼
                    ┌─ 11-LangChain RAG ───┐
                    │  12-Agent开发         │── 框架应用
    框架层 ──────── │  13-工程化部署        │
                    └──────────────────────┘
                              │
                              ▼
                    ┌─ 14-综合实战 ─────────┐
    整合层 ──────── │   MaintenanceAssistant│── 系统集成
                    └──────────────────────┘

7. 第三阶段预告

第三阶段将聚焦评估、优化与微调：

8. 自我评估清单

请逐项打分（1-5分），低于3分的项建议回顾对应课程：

理论知识

• 能解释文本向量化的原理和余弦相似度的含义
• 能说明不同分块策略的适用场景和优缺点
• 能描述向量数据库的索引与检索原理
• 能解释RAG的完整工作流程（从输入到输出）
• 能区分Chain和Agent的核心区别

实践能力

• 能独立搭建一个RAG问答系统（从零开始）
• 能用LangChain的七大抽象重构自研系统
• 能定义@tool工具并构建多工具Agent
• 能搭建标准的项目目录结构
• 能编写Dockerfile进行容器化部署

工程素养

• 理解环境变量配置的重要性和最佳实践
• 能设计合理的日志记录策略
• 知道CI/CD的基本流程和各环节工具
• 能进行基本的性能调优（分块大小、top_k等）

综合应用

• 能设计一个完整的设备维修AI系统架构
• 能评估RAG系统的检索和回答质量
• 能根据场景选择合适的技术方案

恭喜你完成第二阶段！你已经掌握了从原理到框架的核心技能。
你已经可以搭建一个具备知识问答、故障诊断、工单管理的
设备维修AI系统。接下来将进入评估优化和高级技巧的学习，
让你的系统从"能用"变成"好用"。加油！

code

# -*- coding: utf-8 -*-
"""
第14课：设备维修AI助手 - 完整系统演示
集成 RAG + Agent + Tools + Memory + 使用统计
依赖: pip install langchain langchain-openai langchain-community langchain-classic chromadb sentence-transformers
注: langchain 1.x 将 schema/text_splitter/chains/memory/tools/agents/prompts
    迁至 langchain_classic 兼容包, 新项目推荐使用 langgraph 重写 Agent 部分。
"""
import os
import time
import json
from datetime import datetime
from collections import defaultdict

os.environ.setdefault("OPENAI_API_KEY", "sk-your-key")
os.environ.setdefault("OPENAI_BASE_URL", "https://api.deepseek.com")

from langchain_classic.schema import Document
from langchain_classic.text_splitter import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import Chroma
from langchain_classic.chains import ConversationalRetrievalChain
from langchain_classic.memory import ConversationBufferMemory
from langchain_classic.tools import tool
from langchain_classic.agents import create_openai_tools_agent, AgentExecutor
from langchain_classic.prompts import ChatPromptTemplate, MessagesPlaceholder

# === 设备维修知识库（20+条专业知识） ===
KNOWLEDGE_ENTRIES = [
    # 液压系统 (5条)
    "液压系统日常检查：油位2/3以上、油温40-60℃、无渗漏、无异响。每项需记录在巡检表中。",
    "液压油更换周期：正常工作每2000小时更换，高温环境每1500小时更换。使用46号抗磨液压油。",
    "液压泵异响诊断：首先检查油位是否充足，其次检查滤芯是否堵塞，最后检查泵内部磨损情况。",
    "液压缸密封件更换标准：发现渗漏、活塞杆拉伤、密封件硬化或变形时必须更换。更换后需做压力测试。",
    "液压系统常见故障代码：E01油压低、E02油温高、E03滤芯堵塞、E04液位低。对应处理见维修手册第3章。",
    # 电机系统 (5条)
    "电机日常维护清单：轴承润滑(每200小时)、绝缘检测(每月)、散热检查(每周)、接线紧固(每季度)。",
    "电机过热三大原因：1.超载运行 2.散热不良 3.轴承磨损。排查顺序从简单到复杂。",
    "电机轴承更换流程：断电→拆卸端盖→取出旧轴承→清洗轴承座→安装新轴承→加注润滑脂→装回测试。",
    "电机绝缘电阻标准：额定电压380V的电机，绝缘电阻不低于5MΩ。低于此值需进行干燥处理。",
    "变频电机维护要点：散热风扇需独立供电检查、滤波器定期清洁、电缆屏蔽层接地良好。",
    # 传动系统 (4条)
    "齿轮箱润滑规范：使用GL-5级齿轮油，每季度检查油位和油质，每年更换。加油量见设备铭牌。",
    "皮带传动维护：每月检查张紧度(按压下沉10-15mm为宜)，发现裂纹、磨损、老化立即更换。",
    "链条传动保养：每周润滑链条油，每月检查伸长量(超过3%需更换)，链轮磨损需成对更换。",
    "联轴器检查要点：弹性元件无裂纹、螺栓紧固力矩达标、对中偏差不超过0.05mm。",
    # 通用维护 (4条)
    "设备润滑五定原则：定点(确定润滑部位)、定质(选对润滑剂)、定量(按量加注)、定期(按周期)、定人(专人负责)。",
    "设备故障排查标准流程：收集信息→现场观察→初步判断→仪器检测→确认故障→制定方案→实施维修→验收测试。",
    "设备保养等级：一级保养(日常，操作员)、二级保养(定期，维修工)、三级保养(年度，专业团队)。",
    "维修安全规范：维修前断电挂牌、使用绝缘工具、穿戴防护用品、两人以上作业、维修后清理现场。",
    # 备件管理 (3条)
    "备件库存管理原则：安全库存=月均消耗×1.5，经济订货量考虑采购周期和存储成本。",
    "关键备件清单：液压油滤芯(15个)、电机轴承(8套)、密封件套装(20套)、传动皮带(3根)、齿轮油(50升)。",
    "备件领用流程：填写领用单→主管审批→仓库领取→使用记录→余料退回。每月汇总分析消耗趋势。",
]

# === 设备数据 ===
DEVICES = {
    "DEV-001": {"name": "1号液压冲压机", "model": "HP-200T", "status": "运行中",
                "run_hours": 12580, "last_maintenance": "2024-01-15", "location": "A车间",
                "next_maintenance": "2024-04-15", "fault_count": 3},
    "DEV-002": {"name": "2号传送电机", "model": "MT-55KW", "status": "待维修",
                "run_hours": 8920, "last_maintenance": "2023-12-20", "location": "B车间",
                "next_maintenance": "2024-02-20", "fault_count": 5},
    "DEV-003": {"name": "3号齿轮箱", "model": "GB-300", "status": "运行中",
                "run_hours": 5600, "last_maintenance": "2024-02-01", "location": "A车间",
                "next_maintenance": "2025-02-01", "fault_count": 1},
    "DEV-004": {"name": "4号液压机", "model": "HP-150T", "status": "停机",
                "run_hours": 18200, "last_maintenance": "2023-11-10", "location": "C车间",
                "next_maintenance": "2024-01-10", "fault_count": 8},
}

INVENTORY = {
    "液压油滤芯": {"stock": 15, "unit": "个", "price": 85},
    "电机轴承6208": {"stock": 8, "unit": "套", "price": 120},
    "密封件套装": {"stock": 20, "unit": "套", "price": 45},
    "齿轮油GL-5": {"stock": 50, "unit": "升", "price": 38},
    "传动皮带B型": {"stock": 3, "unit": "根", "price": 65},
    "联轴器弹性垫": {"stock": 12, "unit": "组", "price": 35},
}

WORK_ORDERS = []


# === 工具定义 ===
# 使用函数属性存储vectorstore引用，避免全局变量问题

@tool
def search_knowledge(query: str) -> str:
    """搜索设备维修知识库，返回维修方法、故障原因、保养规范等专业知识"""
    fn = getattr(search_knowledge, "_search_fn", None)
    if fn:
        return fn(query)
    return "知识库未初始化"


@tool
def get_device_info(device_id: str) -> str:
    """根据设备编号(如DEV-001/DEV-002/DEV-003/DEV-004)查询设备档案信息"""
    info = DEVICES.get(device_id)
    if not info:
        return f"未找到设备{device_id}，可用编号：{list(DEVICES.keys())}"
    return json.dumps(info, ensure_ascii=False)


@tool
def create_work_order(device_id: str, fault_desc: str, priority: str = "普通") -> str:
    """创建维修工单。参数：device_id设备编号，fault_desc故障描述，priority优先级(紧急/普通/低)"""
    oid = f"WO-{len(WORK_ORDERS)+1:04d}"
    order = {"order_id": oid, "device_id": device_id, "fault": fault_desc,
             "priority": priority, "created": datetime.now().strftime("%Y-%m-%d %H:%M"),
             "status": "待派工"}
    WORK_ORDERS.append(order)
    return f"工单已创建：{json.dumps(order, ensure_ascii=False)}"


@tool
def check_inventory(part_name: str) -> str:
    """查询备件库存，如液压油滤芯、电机轴承6208、齿轮油GL-5等"""
    for name, info in INVENTORY.items():
        if part_name in name or name in part_name:
            return f"{name}：库存{info['stock']}{info['unit']}，单价{info['price']}元"
    return f"未找到备件「{part_name}」，可用备件：{list(INVENTORY.keys())}"


@tool
def get_repair_cost(fault_type: str) -> str:
    """估算维修费用。故障类型如：液压泵、电机、齿轮箱、皮带、密封件、轴承等"""
    costs = {"液压泵": "2000-5000元", "电机": "500-1500元", "齿轮箱": "800-3000元",
             "皮带": "200-500元", "密封件": "100-300元", "轴承": "300-800元"}
    for k, v in costs.items():
        if k in fault_type:
            return f"{k}维修预估费用：{v}"
    return "预估费用500-2000元（需现场检查确定）"


class MaintenanceAssistant:
    """设备维修AI助手 - 集成RAG+Agent+Memory+统计"""

    def __init__(self):
        self.stats = defaultdict(int)
        self.stats["start_time"] = time.time()
        self._init_llm()
        self._init_knowledge()
        self._init_rag_chain()
        self._init_agent()
        print("✅ MaintenanceAssistant 初始化完成\n")

    def _init_llm(self):
        """初始化LLM"""
        self.llm = ChatOpenAI(
            model="deepseek-chat",
            openai_api_key=os.getenv("OPENAI_API_KEY"),
            openai_api_base=os.getenv("OPENAI_BASE_URL"),
            temperature=0
        )

    def _init_knowledge(self):
        """初始化知识库"""
        print("📚 初始化知识库...")
        docs = [Document(page_content=text, metadata={"source": f"knowledge_{i}"})
                for i, text in enumerate(KNOWLEDGE_ENTRIES)]
        splitter = RecursiveCharacterTextSplitter(chunk_size=300, chunk_overlap=30)
        chunks = splitter.split_documents(docs)

        self.embeddings = OpenAIEmbeddings(
            model="text-embedding-3-small",
            openai_api_key=os.getenv("OPENAI_API_KEY"),
            openai_api_base=os.getenv("OPENAI_BASE_URL"),
        )
        self.vectorstore = Chroma.from_documents(
            chunks, self.embeddings, collection_name="full_maintenance_kb"
        )

        # 将检索函数绑定到工具
        def _search(query):
            results = self.vectorstore.similarity_search(query, k=3)
            if results:
                return "\n---\n".join([d.page_content for d in results])
            return "未找到相关知识"

        search_knowledge._search_fn = _search
        print(f"   知识库就绪：{len(KNOWLEDGE_ENTRIES)}条知识，{len(chunks)}个向量块")

    def _init_rag_chain(self):
        """初始化RAG问答链"""
        print("🔗 初始化RAG链...")
        self.memory = ConversationBufferMemory(
            memory_key="chat_history", return_messages=True, output_key="answer"
        )
        self.qa_chain = ConversationalRetrievalChain.from_llm(
            llm=self.llm,
            retriever=self.vectorstore.as_retriever(search_kwargs={"k": 3}),
            memory=self.memory,
            return_source_documents=True,
        )
        print("   RAG链就绪")

    def _init_agent(self):
        """初始化Agent"""
        print("🤖 初始化Agent...")
        tools = [search_knowledge, get_device_info, create_work_order,
                 check_inventory, get_repair_cost]
        prompt = ChatPromptTemplate.from_messages([
            ("system", """你是设备维修诊断专家。请使用工具帮助用户：
search_knowledge-搜索维修知识, get_device_info-查设备信息,
create_work_order-创建工单, check_inventory-查库存, get_repair_cost-估费用。
请综合分析后给出专业建议。"""),
            ("human", "{input}"),
            MessagesPlaceholder(variable_name="agent_scratchpad"),
        ])
        agent = create_openai_tools_agent(self.llm, tools, prompt)
        self.agent_executor = AgentExecutor(
            agent=agent, tools=tools, verbose=False,
            max_iterations=5, handle_parsing_errors=True
        )
        print("   Agent就绪\n")

    def ask(self, question: str) -> str:
        """RAG知识问答"""
        self.stats["ask_calls"] += 1
        start = time.time()
        try:
            result = self.qa_chain({"question": question})
            answer = result["answer"]
            sources = [d.metadata.get("source", "") for d in result.get("source_documents", [])]
            self.stats["ask_time"] += time.time() - start
            return f"{answer}\n\n[来源: {', '.join(set(sources))}]"
        except Exception as e:
            return f"问答出错：{e}"

    def diagnose(self, device_id: str, fault: str) -> str:
        """Agent故障诊断"""
        self.stats["diagnose_calls"] += 1
        start = time.time()
        try:
            result = self.agent_executor.invoke({
                "input": f"请诊断设备{device_id}的故障：{fault}，"
                         f"需要查设备信息、搜索相关知识、检查备件库存、估算费用，并创建维修工单"
            })
            self.stats["diagnose_time"] += time.time() - start
            return result["output"]
        except Exception as e:
            return f"诊断出错：{e}"

    def generate_report(self, device_id: str) -> str:
        """生成设备报告"""
        self.stats["report_calls"] += 1
        info = DEVICES.get(device_id)
        if not info:
            return f"设备{device_id}不存在"
        results = self.vectorstore.similarity_search(f"{info['name']}维护保养", k=3)
        knowledge = "\n".join([d.page_content for d in results])
        prompt_text = f"""根据以下设备信息和维护知识，生成一份简洁的设备状态报告：

设备信息：{json.dumps(info, ensure_ascii=False)}

相关维护知识：
{knowledge}

请输出：1.设备概况 2.当前状态评估 3.维护建议 4.风险提示"""
        try:
            resp = self.llm.invoke(prompt_text)
            return resp.content
        except Exception as e:
            return f"报告生成出错：{e}"

    def chat(self, message: str) -> str:
        """多轮对话"""
        self.stats["chat_calls"] += 1
        start = time.time()
        try:
            result = self.qa_chain({"question": message})
            self.stats["chat_time"] += time.time() - start
            return result["answer"]
        except Exception as e:
            return f"对话出错：{e}"

    def print_stats(self):
        """输出使用统计"""
        total_time = time.time() - self.stats["start_time"]
        print("\n" + "=" * 50)
        print("📊 使用统计")
        print("=" * 50)
        print(f"   知识问答(ask)：{self.stats['ask_calls']} 次，"
              f"平均 {self.stats['ask_time']/max(self.stats['ask_calls'],1):.1f}s")
        print(f"   故障诊断(diagnose)：{self.stats['diagnose_calls']} 次，"
              f"平均 {self.stats['diagnose_time']/max(self.stats['diagnose_calls'],1):.1f}s")
        print(f"   设备报告(report)：{self.stats['report_calls']} 次")
        print(f"   多轮对话(chat)：{self.stats['chat_calls']} 次，"
              f"平均 {self.stats['chat_time']/max(self.stats['chat_calls'],1):.1f}s")
        print(f"   工单创建：{len(WORK_ORDERS)} 个")
        print(f"   会话时长：{total_time:.1f}s")
        print(f"   知识库：{len(KNOWLEDGE_ENTRIES)} 条知识")
        print("=" * 50)


def run_demo():
    """完整演示会话"""
    print("🏭 第14课：设备维修AI助手 - 完整系统演示")
    print("=" * 60)

    assistant = MaintenanceAssistant()

    # --- 1. RAG知识问答 ---
    print("\n" + "=" * 50)
    print("📖 场景1：RAG知识问答")
    print("=" * 50)
    questions = [
        "液压系统日常需要检查哪些项目？",
        "电机轴承更换的具体步骤是什么？",
        "设备润滑的五定原则是什么？",
    ]
    for q in questions:
        print(f"\n❓ {q}")
        answer = assistant.ask(q)
        print(f"💡 {answer[:200]}")

    # --- 2. Agent故障诊断 ---
    print("\n" + "=" * 50)
    print("🔧 场景2：Agent故障诊断")
    print("=" * 50)
    diagnoses = [
        ("DEV-001", "液压泵有异响，油温偏高"),
        ("DEV-002", "电机过热停机，负载正常"),
    ]
    for dev_id, fault in diagnoses:
        print(f"\n🔍 诊断 {dev_id}: {fault}")
        result = assistant.diagnose(dev_id, fault)
        print(f"📋 {result[:300]}")

    # --- 3. 设备报告 ---
    print("\n" + "=" * 50)
    print("📊 场景3：设备报告生成")
    print("=" * 50)
    for dev_id in ["DEV-001", "DEV-004"]:
        print(f"\n📄 {dev_id} 设备报告：")
        report = assistant.generate_report(dev_id)
        print(report[:300])

    # --- 4. 多轮对话 ---
    print("\n" + "=" * 50)
    print("💬 场景4：多轮对话")
    print("=" * 50)
    conversations = [
        "齿轮箱多久换一次油？",
        "那DEV-003上次是什么时候保养的？",
        "它需要更换什么备件吗？帮我查下库存",
    ]
    for msg in conversations:
        print(f"\n👤 {msg}")
        reply = assistant.chat(msg)
        print(f"🤖 {reply[:200]}")

    # --- 统计 ---
    assistant.print_stats()

    if WORK_ORDERS:
        print("\n📝 创建的工单：")
        for wo in WORK_ORDERS:
            print(f"   {wo['order_id']}: {wo['device_id']} - {wo['fault']} [{wo['priority']}]")

    print("\n✅ 完整演示结束！")


if __name__ == "__main__":
    run_demo()