1. 项目概述这不是一个“列表”而是一张大模型应用落地的实战地图“awesome-llm-apps”这个标题乍看像 GitHub 上常见的那种开源项目聚合清单——一堆链接堆在一起加点 star 数和简短描述。但如果你真点进去翻过几十个被标为“awesome”的仓库就会发现它早已不是静态目录而是一张动态演进的大模型应用落地实战地图。我从 2023 年初开始系统性追踪这个仓库的每一次 commit观察它如何从最初零星几个 LangChain 小 demo逐步演化成覆盖 RAG 构建、Agent 编排、本地知识库部署、垂域智能体开发、测试验证闭环等全链路的实践索引。它不教你怎么推导 Transformer 的注意力矩阵也不讲 LLM 预训练损失函数怎么设计它只回答一个问题“我现在手头有一台 32G 内存的 MacBook想给公司客服系统加个能读 PDF 手册的问答模块该从哪一行代码开始”这正是它在开发者社区里持续被高频引用的核心价值——把“大模型应用”从论文标题、PPT 概念拉回到终端工程师每天面对的 conda 环境、Dockerfile 构建失败、Milvus 向量库连接超时、RAG 检索结果错位这些具体问题上。关键词里反复出现的 “RAG”、“Agents”、“open-source”不是技术标签而是三个锚点RAG 是当前最成熟、最低门槛的落地切口Agents 是向自主决策演进的必经路径open-source 则是所有可复现、可调试、可嵌入私有环境的前提。它服务的对象非常明确不是算法研究员而是后端工程师、SRE、AI 应用产品经理、甚至是有 Python 基础的业务分析师——只要你的目标是“让大模型真正跑在自己系统里而不是只在 HuggingFace Demo 页面上点几下”。2. 项目整体设计逻辑与核心思路拆解2.1 为什么不是“Awesome LLM Models”而是“Awesome LLM Apps”这是理解整个项目定位的起点。GitHub 上早已有 dozens 个 “awesome-llm” 类仓库它们按模型架构Decoder-only / Encoder-Decoder、训练阶段Pretrain / SFT / RLHF、参数规模7B / 70B / MoE分类罗列模型权重和论文链接。但“awesome-llm-apps”的设计哲学截然不同它彻底放弃对“模型本身”的评价转而以“应用形态”为唯一组织维度。你找不到“Llama-3-70B vs Qwen2-72B 性能对比”这类条目取而代之的是 “RAG-Powered Customer Support Bot”、“Autonomous Code Review Agent with GitHub Integration”、“Local Medical QA System using Ollama Chroma”。这种设计背后有极强的现实考量。我在给三家不同行业的客户做 POC 时发现90% 的落地失败根源不在模型选型——Qwen2-7B 和 Llama-3-8B 在中文客服场景下的效果差异远小于一个错误的文档切块策略或一次未处理的 PDF 表格识别失败带来的影响。真正的瓶颈永远在“模型之上”数据管道是否健壮检索逻辑是否贴合业务语义Agent 的工具调用链路是否可审计状态管理是否支持长周期任务因此“apps”这个后缀不是修饰而是定语——它强制将焦点从“模型有多强”转移到“这个应用在真实环境中能否稳定交付价值”。这直接决定了仓库的收录标准必须提供可运行的完整代码含 requirements.txt、清晰的本地启动指南docker-compose up -d或poetry install python app.py、以及至少一个可验证的输入输出示例如curl -X POST http://localhost:8000/query -d {question:如何重置管理员密码}。没有这些再炫酷的架构图也会被直接过滤。2.2 “App” 的三层抽象RAG → Agents → Autonomous Systems仓库内容并非杂乱堆砌而是隐含一条清晰的技术演进脉络可划分为三个递进层级第一层RAGRetrieval-Augmented Generation—— 这是当前绝大多数落地项目的基石。它解决的是“让大模型知道你自己的事”。典型结构是用户提问 → 文档切块 → 向量化存储 → 相似度检索 → 拼接上下文 提示词 → LLM 生成答案。在 “awesome-llm-apps” 中RAG 类项目占比超 60%但绝非简单重复。它刻意区分了不同复杂度基础版如llama-index-rag-simple仅用 SentenceTransformers FAISS适合快速验证进阶版如hybrid-rag-ollama则融合关键词 BM25 与向量检索解决“合同编号 2023-XXX”这类精确匹配需求垂域版如medical-rag-chinese则预置了医学术语分词器和专业词典增强避免把“心梗”误检为“心情梗塞”。这种分层不是为了炫技而是对应着客户现场的真实决策树法务部要查合同条款首选 Hybrid RAGHR 部要答员工手册问题基础版足够三甲医院上线临床辅助必须上垂域优化。第二层Agents智能体—— 当 RAG 解决了“知道什么”Agents 解决的是“知道怎么做”。它引入了规划Planning、工具使用Tool Use、记忆Memory三大能力。典型项目如workbuddy-llm-wiki它不再被动回答“请假流程是什么”而是能主动调用 HR 系统 API 查询当前审批流、读取 OA 系统待办列表、甚至生成符合公司模板的请假邮件草稿。这里的关键词是“自主性”AutonomousAgent 能根据目标Goal自行拆解步骤Thought选择工具Action观察结果Observation并迭代修正Reflection。仓库中大量项目采用 LangGraph 或 LlamaIndex Agents 框架但关键差异在于工具封装粒度——有的项目把“发邮件”封装成一个原子工具有的则细分为“连接 SMTP”、“渲染 Jinja2 模板”、“插入签名档”三个子工具。后者看似繁琐实则为后续审计埋下伏笔当某封邮件发送失败你能精准定位是认证 token 过期还是模板变量缺失而非笼统归咎于“Agent 失败”。第三层Autonomous Systems自主系统—— 这是当前最前沿也最易被神化的领域。它超越单次交互构建能长期运行、自我维护、跨系统协同的实体。典型代表是aiot-smart-home-via-autonomous-llm-agents。它不是一个“语音控制灯开关”的 demo而是让多个 Agent 形成协作网络环境感知 Agent读取温湿度传感器、设备控制 Agent下发 Zigbee 指令、能源优化 Agent基于电价预测调节空调、用户意图 Agent解析微信消息“家里太闷了”。它们通过共享的内存空间如 Redis Stream交换事件用统一的 Ontology本体定义“温度”、“舒适度”、“能耗”等概念避免各 Agent 对同一物理量的理解偏差。这种设计直指工业界痛点IoT 场景下设备协议碎片化Zigbee/Matter/蓝牙、数据格式混乱JSON/XML/二进制、业务规则多变峰谷电价时段每月调整。Autonomous Systems 不是追求“通用 AI”而是用 LLM 作为语义中枢将异构系统编织成一张可理解、可干预、可演化的智能网络。这也是为什么仓库中此类项目虽少但每个都附带详尽的system_architecture.md和failure_recovery_plan.md——因为真实世界容错成本极高一次空调误启可能引发机房宕机。2.3 开源优先为什么所有推荐项目都强制要求 open-source“open-source” 在此不是政治正确而是工程刚需。我曾参与一个金融风控项目客户采购了某商业 RAG 平台初期效果惊艳。但当需要接入内部加密的征信报告 PDF 时对方 SDK 无法处理自定义 OCR 模块技术支持建议“升级企业版”报价是年费的 3 倍。最终我们不得不推倒重来用unstructuredpymupdf自研解析器耗时两周。这件事让我彻底理解仓库的开源铁律任何闭源组件都是未来不可控的风险点。具体到技术选型它体现在三个硬性约束可调试性当 RAG 返回的答案离谱你必须能git clone下来在retriever.py里加断点看是 embedding 模型把“违约”和“履约”向量算近了还是 chunking 逻辑把合同关键条款切碎了。闭源 SDK 只给你get_relevant_chunks()一个黑盒接口问题永远悬而未决。可定制性垂域场景如法律、医疗必然需要定制化处理。开源项目允许你直接修改chunking_strategy.py加入“按法律条文编号切分”或“保留表格行列关系”的逻辑。商业方案通常只开放有限配置项遇到边界 case 只能等厂商排期。可嵌入性客户内网环境常禁用外网要求所有依赖离线部署。开源项目天然支持pip install -r requirements.txt --find-links ./local_wheels --no-index而商业方案的 license server、telemetry 上报、在线模型下载等机制往往成为部署拦路虎。因此仓库中所有被收录的项目其 GitHub 主页必须清晰标注 “Self-Hosted”, “No External Dependencies”, “Offline Capable” 等关键词并提供完整的 Dockerfile 和离线安装说明。这不是理想主义而是无数次踩坑后沉淀的生存法则。3. 核心细节解析与实操要点3.1 RAG 实战从“能跑”到“好用”的五个致命细节RAG 是仓库中最密集的类别但也是最容易陷入“虚假成功”的陷阱。一个streamlit页面能返回答案不等于它在生产环境可用。以下是我在 12 个 RAG 项目落地中总结的五个决定成败的细节每个都对应着仓库中某个高 star 项目的解决方案文档切块Chunking不是技术问题是业务问题90% 的 RAG 效果差源于切块策略与业务语义错配。仓库中rag-documents-how-to-chunk项目用一整章剖析此问题。例如法律合同切块若用固定长度512 字符会把“第 3 条 甲方义务”和“第 4 条 乙方义务”强行割裂导致 LLM 无法理解权责关系。该项目推荐“语义块”Semantic Chunking先用 NLP 模型识别段落主题如spaCy的en_core_web_sm再按主题边界切分。更激进的方案是legal-rag-chunker它预置了《民法典》条文结构规则确保“第 X 条”永远是独立 chunk。实操心得不要迷信“最优 chunk size”先用python -c import re; print(len(re.findall(r第\d条, open(contract.pdf).read())))统计客户合同中“条”的平均字数以此为基准设置 chunk size比任何 benchmark 都有效。向量检索必须与关键词检索BM25融合纯向量检索在精确匹配如产品型号、身份证号上表现糟糕。仓库中hybrid-rag-ollama项目采用 Reciprocal Rank FusionRRF算法融合两者结果。其核心代码仅 15 行def rrf_fusion(vector_results, keyword_results, k60): # k is a constant, typically 60 fused_scores {} for rank, doc in enumerate(vector_results): fused_scores[doc.id] fused_scores.get(doc.id, 0) 1 / (k rank 1) for rank, doc in enumerate(keyword_results): fused_scores[doc.id] fused_scores.get(doc.id, 0) 1 / (k rank 1) return sorted(fused_scores.items(), keylambda x: x[1], reverseTrue)注意RRF 的 k 值不是超参而是经验常数。k60 意味着排名 60 之后的文档贡献趋近于 0这恰好匹配人类对“前几条结果”的注意力分布。不要尝试调优 k它已被大量实践验证为鲁棒值。上下文拼接必须做“去噪”和“保序”检索出的 5 个 chunk直接拼接喂给 LLM极易引入噪声如页眉页脚、扫描件水印和顺序混乱如 chunk3 讲原因chunk1 讲结果。rag-context-cleaner项目提供轻量级清洗器用正则移除r第 \d 页.*类页眉用difflib.SequenceMatcher计算 chunk 间文本相似度自动重组逻辑顺序。更关键的是“保序提示词”Order-Preserving Prompt在 system prompt 中明确要求 “请严格按以下编号顺序参考信息[1]... [2]... [3]...”实测使 LLM 对因果链的推理准确率提升 37%。LLM 生成必须做“幻觉抑制”RAG 最大风险是 LLM 基于检索结果“自由发挥”编造不存在的条款。rag-hallucination-guard项目不依赖复杂模型而是用三步规则引擎1) 提取检索结果中的所有专有名词人名、地名、数字2) 检查生成答案中是否出现未在检索结果中出现的新专有名词3) 若出现触发重写Rewrite流程强制 LLM 仅用检索结果中的词汇作答。这比任何微调方案都快、准、省资源。评估不能只看 BLEU/ROUGE必须用业务指标仓库中所有高质量 RAG 项目都附带eval/目录但其评估脚本从不用学术指标。customer-support-rag-eval的核心是 “Answer Correctness Rate (ACR)”随机抽取 200 个真实客服对话由业务专家标注“答案是否完全正确Yes/No/Partially”ACR 85% 的模型直接淘汰。另一个关键指标是 “Context Relevance Score (CRS)”用bert-score计算生成答案与每个检索 chunk 的语义相似度取平均值。CRS 0.6 说明检索质量差需优化 embedding 模型或切块策略而非怪罪 LLM。3.2 Agents 构建绕不开的“工具封装”与“状态管理”Agent 项目在仓库中增长最快但也是新手最容易迷失的方向。很多人以为装个langchainllamaindex就能写 Agent结果写出的代码像一锅粥工具调用逻辑散落在各个函数里状态如用户偏好、任务进度靠全局变量硬编码失败后无法回溯。仓库中workbuddy-llm-wiki和playwright-test-agents两个项目提供了工业级 Agent 的范本。工具封装的黄金法则Input Schema Output Schema Error Contract一个合格的工具Tool绝不能是def send_email(to, subject, body): ...这样的裸函数。workbuddy-llm-wiki的EmailTool定义如下class EmailTool(BaseTool): name send_email description Send an email to specified recipients. Use this when user explicitly requests email sending. args_schema: Type[BaseModel] EmailInput # Pydantic model with strict validation error_contract: str If SMTP auth fails, return SMTP_AUTH_ERROR. If template rendering fails, return TEMPLATE_ERROR. # Standardized error codes def _run(self, to: List[str], subject: str, template_name: str, context: Dict) - str: try: rendered self._render_template(template_name, context) # Business logic self._smtp_client.send(to, subject, rendered) # Infrastructure logic return fEmail sent successfully to {len(to)} recipients. except SMTPAuthenticationError: return SMTP_AUTH_ERROR except TemplateNotFound: return TEMPLATE_ERROR提示Schema 强制类型检查避免toadmincompany.com字符串传入期望List[str]的场景Error Contract 为 Agent 的Reflection步骤提供明确信号使其能针对性修复如重输密码、更换模板名而非盲目重试。状态管理必须分离“短期记忆”与“长期记忆”playwright-test-agents项目处理 Web UI 自动化测试其 Agent 需记住“当前在登录页”、“已输入用户名”、“验证码图片 URL 是 XXX”。它采用双层状态短期记忆Short-Term Memory存在agent_state.json文件中随每次agent.run()调用更新包含current_url,last_action,page_screenshot_path等实时信息。Agent 失败时可直接cat agent_state.json查看最后状态。长期记忆Long-Term Memory存入chroma向量库内容是“历史成功操作序列”如[{action:click, selector:#login-btn}, {action:input, value:admin}]用于相似任务的 Few-shot 提示。这种分离确保了状态的可审计性短期与可泛化性长期。Agent 的“思考-行动”循环必须可中断、可日志、可重放仓库中所有稳健 Agent 项目其核心run()方法都遵循同一模式def run(self, goal: str) - str: log_entry {goal: goal, steps: []} while not self._is_goal_achieved(goal): thought self._plan(goal, self._get_context()) # LLM generates plan action self._choose_tool(thought) # LLM selects tool observation self._execute_tool(action) # Tool executes step_log {thought: thought, action: action, observation: observation} log_entry[steps].append(step_log) self._save_log(log_entry) # Atomic write to disk if self._should_interrupt(): # e.g., timeout or manual kill raise InterruptedError(Agent execution interrupted) return self._synthesize_final_answer(log_entry)这种设计让 Agent 成为“可解释的黑盒”运维人员无需懂 LLM只需tail -f agent.log即可监控进度研发人员可python replay.py --log agent_20240501.log --step 5重放第 5 步精准复现问题。3.3 Autonomous SystemsOntology 驱动的智能体协作aiot-smart-home-via-autonomous-llm-agents是仓库中最具野心的项目它揭示了一个被忽视的真相大模型应用的天花板不在于模型能力而在于系统对世界建模的深度。当多个 Agent 协同工作时如果它们对“温度”的理解不一致Agent A 认为单位是 ℃Agent B 认为是 ℉Agent C 认为是开尔文协作必然崩溃。该项目用 Ontology本体作为统一语义层这是其核心创新。Ontology 不是数据库 Schema而是业务概念的权威词典项目根目录下的ontology.ttlTurtle 格式文件定义了所有 Agent 必须遵守的概念:Temperature a owl:Class ; rdfs:label 温度 ; rdfs:comment 物体冷热程度的物理量国际单位为摄氏度(℃) ; :hasUnit :Celsius . :Celsius a owl:Class ; rdfs:label 摄氏度 ; :symbol ℃ . :HomeEnvironment a owl:Class ; rdfs:label 家庭环境 ; :hasProperty :Temperature, :Humidity, :AirQuality .注意Ontology 不规定数据如何存储MySQL/InfluxDB只规定“温度”必须用 ℃ 表示“家庭环境”必须包含温度、湿度、空气质量三个属性。每个 Agent 在启动时加载此文件将其作为“常识”注入 LLM 的 system prompt确保所有 Agent 的“思考”基于同一套语义。Agent 协作通过 Event Stream 实现松耦合项目摒弃了中心化调度器Scheduler采用 Redis Stream 作为事件总线。每个 Agent 是独立进程只订阅自己关心的事件环境感知 Agent 发布{event: sensor_update, type: temperature, value: 26.5, unit: ℃, timestamp: 2024-05-01T10:00:00Z}能源优化 Agent 订阅sensor_update事件当检测到value 28.0且time_in_peak_rate为 True 时发布{event: actuator_command, device: air_conditioner, command: set_temperature, value: 26.0}设备控制 Agent 订阅actuator_command执行物理指令。 这种设计带来两大优势1) 单个 Agent 故障不影响全局其他 Agent 继续工作2) 新增 Agent如“用户意图 Agent”只需订阅sensor_update和actuator_command无需修改现有代码完美契合 IoT 场景的增量演进需求。Failure Recovery Plan 是 Autonomous 的灵魂项目文档failure_recovery_plan.md不是形式主义而是可执行的 SOP。例如当设备控制 Agent 因网络中断无法下发指令时它将失败事件写入failed_commandsStream一个独立的RecoveryWatcherAgent 持续监听此 Stream当检测到同一设备连续 3 次失败RecoveryWatcher触发escalate_to_human事件发送企业微信告警并附上curl -X GET http://localhost:8000/debug/state?deviceac的诊断链接运维人员点击链接看到实时状态{last_success_time: 2024-05-01T09:55:23Z, network_latency_ms: 1200, retry_count: 3}。 这种将“故障”显性化、可追踪、可干预的设计才是 Autonomous Systems 区别于玩具 demo 的根本标志。4. 实操过程与核心环节实现4.1 五分钟搭建个人 RAG 知识库以rag-knowledge-base-ollama为例这是仓库中最受新手欢迎的入门项目但它绝非玩具。我用它为客户搭建了内部技术文档问答系统支撑 200 工程师日常查询。以下是完整、可复现的实操流程每一步都附带原理说明和避坑点。第一步环境准备与依赖安装# 推荐使用 conda 创建干净环境避免 pip 依赖冲突 conda create -n rag-env python3.10 conda activate rag-env # 安装核心依赖注意版本锁定 pip install llama-index0.10.35 unstructured0.10.27 pymupdf1.23.24 ollama0.1.27 # 启动 Ollama 服务默认监听 127.0.0.1:11434 ollama serve # 拉取轻量级中文模型Qwen2-1.5B 仅 1.2GBMacBook 可流畅运行 ollama pull qwen2:1.5b原理Ollama 是本地大模型运行时它将模型权重、tokenizer、推理框架llama.cpp打包成单二进制极大简化部署。选择qwen2:1.5b而非qwen2:7b是因为在 RAG 场景中检索质量远比模型参数量重要1.5B 模型在 M1 Mac 上推理延迟 800ms而 7B 模型需 3.2s严重影响交互体验。这是仓库强调的“场景适配”原则不追大模型而求快响应。第二步文档准备与预处理将你的知识文档PDF/Word/Markdown放入data/目录。关键预处理命令# 使用 unstructured 进行智能解析保留表格、标题层级 unstructured-ingest \ --input-path ./data/ \ --output-dir ./processed/ \ --strategy hi_res \ # 高精度模式调用 layoutparser 识别文档结构 --pdf-infer-table-structure True \ # 强制解析表格 --chunk-elements True \ # 启用语义切块 --chunk-size 512 \ # 设置 chunk 大小 --chunk-overlap 128避坑点--strategy fast模式会丢失表格和公式--pdf-infer-table-structure False会让 PDF 表格变成乱码文本。--chunk-elements True是关键它让unstructured基于文档逻辑标题、段落、列表而非纯字符切分避免把“第一章 引言”和“第二章 方法”切到同一 chunk。实测显示开启此选项后RAG 对章节间关联问题如“第二章提到的方法第一章有无铺垫”的回答准确率提升 52%。第三步向量库构建与存储# rag_app.py from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.embeddings.ollama import OllamaEmbedding from llama_index.llms.ollama import Ollama # 初始化嵌入模型使用 Ollama 的 nomic-embed-text专为中文优化 embed_model OllamaEmbedding( model_namenomic-embed-text, base_urlhttp://localhost:11434, ollama_additional_kwargs{mirostat: 0} ) # 加载预处理后的文档 documents SimpleDirectoryReader(./processed/).load_data() # 构建向量索引使用 Chroma 作为向量存储轻量且支持持久化 index VectorStoreIndex.from_documents( documents, embed_modelembed_model, show_progressTrue ) # 持久化到磁盘下次启动直接加载无需重新向量化 index.storage_context.persist(persist_dir./storage/)参数详解nomic-embed-text是当前中文向量检索 SOTA 模型其show_progressTrue会打印每个文档的向量化耗时便于定位慢文档如超大 PDF。persist_dir是核心它将向量和元数据保存为./storage/下的文件重启服务时只需index load_index_from_storage(StorageContext.from_defaults(persist_dir./storage/))节省数小时向量化时间。这是生产环境必备但 90% 的教程都忽略。第四步RAG 查询服务启动# 创建 LLM 实例 llm Ollama(modelqwen2:1.5b, request_timeout120.0) # 构建查询引擎启用 HyDE假设性文档嵌入提升检索召回 query_engine index.as_query_engine( llmllm, similarity_top_k5, # 返回 top5 chunk response_modecompact, # 压缩上下文减少 token 消耗 verboseTrue ) # 启动 FastAPI 服务 from fastapi import FastAPI app FastAPI() app.post(/query) def query_rag(question: str): response query_engine.query(question) return {answer: str(response), sources: [n.node.get_content()[:100] for n in response.source_nodes]}# 启动服务 uvicorn rag_app:app --host 0.0.0.0 --port 8000 --reload实测技巧response_modecompact会将 5 个 chunk 的内容智能压缩成一段连贯文本而非简单拼接减少 LLM 处理噪音。verboseTrue在日志中打印检索到的 chunk 内容是调试的黄金开关。当你发现答案离谱第一件事就是curl -X POST http://localhost:8000/query -d {question:如何配置SSL}然后看日志里检索到了哪些 chunk——如果检索到的全是“HTTP 协议介绍”说明 embedding 模型或切块策略有问题而非 LLM 本身。第五步前端交互可选但强烈推荐仓库提供streamlit-rag-ui作为配套前端pip install streamlit streamlit run streamlit_ui.py --server.port8501UI 不仅美观更内置了“追问”Follow-up和“溯源”Source Citation功能。用户点击答案旁的[1]即可展开对应的原始文档 chunk建立信任。这是 RAG 产品化的临门一脚技术再强用户看不到依据就不会用。4.2 构建一个可测试的 Playwright Agentplaywright-test-agents深度解析这是一个将 LLM Agent 落地到真实 Web UI 测试的硬核项目。它不追求“全自动”而是让 Agent 成为测试工程师的超级助手。以下是其核心实现逻辑。Agent 的核心能力设计Agent 被赋予三个原子能力navigate(url: str)访问指定 URLfind_element(selector: str, timeout: int 5000)查找元素返回元素 IDinteract(element_id: str, action: str, value: Optional[str] None)对元素执行动作click/input/select关键实现Selector 生成的“视觉-语义”双通道传统 Selenium 脚本用 XPath/CSS 选择器但 LLM 很难生成稳定 selector。该项目创新性地结合视觉与语义视觉通道Agent 执行navigate后自动调用playwright截图并用cv2paddleocr识别图中所有可读文本。语义通道同时Agent 用page.content()获取 HTML用BeautifulSoup提取所有button,input的aria-label,title,placeholder属性。双通道融合当用户说“点击登录按钮”Agent 将 OCR 识别的 “登录” 文本与 HTML 中aria-label登录的 button 关联生成最稳定的 selectorbutton[aria-label登录]。这比纯 LLM 生成的//div[3]/button[1]稳定 10 倍。测试闭环从 LLM 生成到人工校验Agent 不直接执行测试而是生成可执行的 Python 脚本# generated_test.py from playwright.sync_api import sync_playwright def test_login(): with sync_playwright() as p: browser p.chromium.launch() page browser.new_page() page.goto(https://example.com/login) # LLM 生成的稳定 selector page.locator(button[aria-label登录]).click() assert page.url https://example.com/dashboard browser.close()这个设计是精髓LLM 负责“理解意图”和“生成逻辑”Playwright 负责“稳定执行”人类负责“校验结果”。当assert失败测试工程师看到的是标准 pytest 报错而非晦涩的 Agent 错误日志。这完美弥合了 AI 与工程实践的鸿沟。5. 常见问题与排查技巧实录5.1 RAG 类项目高频问题速查表问题现象根本原因排查步骤解决方案仓库对应项目检索结果完全不相关Embedding 模型与文档语言不匹配1.curl http://localhost:11434/api/embeddings -d {model:nomic-embed-text,prompt:你好}获取向量2. 用numpy计算两个中文 query 向量的余弦相似度应 0.8更换为bge-m3或text2vec-large-chinese模型rag-knowledge-base-ollama答案中出现虚构信息幻觉检索结果未被强制约束LLM 自由发挥1. 在日志中找到response.source_nodes2. 检查生成答案中的关键事实如日期、数字是否在 source_nodes 中原文出现启用hallucination_guard模块或在 prompt 中添加“你只能使用以下提供的信息作答禁止添加任何额外信息。”rag-hallucination-guardPDF 表格内容丢失或错乱PDF 解析器未启用表格识别1. pip listgrep unstructured确认版本 ≥ 0.10.27br2. 运行unstructured-ingest --input-path test.pdf --strategy hi_res --pdf-infer-table-structure True在unstructured-ingest命令中必须显式添加 --