- 博客(577)
- 收藏
- 关注
RSS订阅原创 LangChain 组件详解：RunnablePassthrough
RunnablePassthrough是LangChain LCEL中的关键组件，主要实现数据透传功能。它有两种核心用途：1）在并行处理中保留原始输入，如RAG场景中同时传递检索结果和原始问题；2）通过.assign()方法增量更新字典数据。该组件在构建复杂数据流时尤为重要，能确保信息完整传递，避免手动处理字典的繁琐操作，是LangChain实现高效数据处理的重要工具。
2026-02-27 21:49:25
275
原创 LangChain 核心机制：RunnableParallel 与隐式转换
本文解释了LCEL中字典语法的底层机制。当在Chain中使用字典时，系统会自动将其转换为RunnableParallel对象，实现并行执行多个任务。这种隐式转换让代码更简洁，同时保持并行处理的特性。通过验证实验证实，字典语法和显式写法性能相同（耗时1秒），证明字典确实被动态转换为并行执行逻辑。该设计简化了高频的并行操作场景，特别是在构建Prompt输入时，能方便地组合多个数据源。理解这一机制有助于读懂复杂的LCEL代码。
2026-02-01 11:12:06
394
原创 LangChain 经典回顾：ConversationBufferMemory 与 ConversationChain
本文深入解析LangChain经典对话组件ConversationBufferMemory与ConversationChain的核心机制。ConversationBufferMemory作为基础记忆组件，完整存储对话历史但存在token爆炸风险；ConversationChain则是预封装的三合一解决方案（LLM+Memory+Prompt），开箱即用但存在实例级状态绑定的并发限制。文章通过代码示例展示了组件使用方法，并对比新旧架构的本质差异：传统方案采用硬编码的有状态实例，而LCEL新方案通过动态注入实现
2026-01-31 23:38:03
639
原创 LangChain 实战：RunnableWithMessageHistory 深度详解
是 LangChain 中优雅管理状态的瑞士军刀。它通过配置化的方式，将繁琐的历史记录读写逻辑从业务逻辑中剥离出来，极大地简化了代码结构。记忆口诀Config定身份 (session_id)。Factory找仓库 (get_session_history)。Keys做映射 (input/history keys)。
2026-01-31 21:41:08
652
原创 LangChain 核心对比：ChatPromptTemplate vs PromptTemplate
摘要： LangChain开发中，PromptTemplate与ChatPromptTemplate分别适配不同模型范式。前者面向传统文本续写模型（如GPT-3），通过字符串插值生成单一文本；后者专为对话模型（如GPT-4）设计，以结构化消息列表（System/User/Assistant）支持角色交互。关键差异包括数据结构、变量处理方式及适用场景。尽管简单任务可用Python原生字符串替代，PromptTemplate仍提供部分填充、输入验证、序列化等工程化优势。随着对话模型成为主流，ChatPrompt
2026-01-31 01:49:27
470
原创 LangChain 进阶：深入解析 MessagesPlaceholder
本文深入解析LangChain中的MessagesPlaceholder组件，它在构建对话式应用时至关重要。现代Chat Model接收结构化消息列表而非单一文本，MessagesPlaceholder作为占位符可将消息对象列表直接嵌入消息队列，保持数据结构完整。文章对比了传统文本拼接与现代结构化消息的差异，并通过代码示例展示其正确用法与常见误区。MessagesPlaceholder主要应用于对话历史管理和Agent推理轨迹场景，必须配合ChatPromptTemplate使用。正确使用该组件可构建结构清
2026-01-31 01:28:40
494
原创 LangChain Agent 架构演进深度解析：从 AgentExecutor 到 LangGraph 与 LCEL
本文深度剖析了LangChain Agent架构从旧范式向新范式的演进。旧范式基于AgentExecutor和create_openai_tools_agent，存在黑盒循环、流式输出困难等缺陷。新范式采用LCEL（LangChain Expression Language）和LangGraph两大技术：LCEL提供原子化组件组合能力，适合简单工具调用；LangGraph通过状态机架构实现完全可控的循环，支持细粒度流式和人工介入。对比显示，新范式在控制流、Prompt设计、调试等方面具有显著优势。迁移建议指
2026-01-28 00:36:26
582
原创 LangChain LCEL 进阶：深入解析 RunnableBranch 与语义路由
本文深入解析了LangChain LCEL中的RunnableBranch与语义路由机制。首先介绍了RunnableBranch的基础原理，它类似于编程中的if-elif-else结构。然后通过两个实战案例：基于关键词的简单路由和基于LLM的语义路由，展示了如何实现智能的任务分发。语义路由通过LLM先识别意图再进行分发，解决了自然语言的模糊性问题。最后将这一模式延伸到多Agent系统架构，说明其在实际企业应用中的价值，如DevOps助手等场景，实现了关注点分离和系统扩展性。掌握语义路由是构建复杂智能系统的关
2026-01-19 02:25:04
428
原创 LangChain LCEL 工具调用实战：从确定性链到动态 Agent
本文介绍了LangChain中三种LLM工具调用模式：确定性显式调用（强制执行固定流程）、半动态绑定（LLM决定单次调用）和高度动态Agent（多步循环）。通过代码示例展示了前两种模式的实现，强调应根据业务确定性选择最简单可行的方案。显式调用最稳定但缺乏灵活性，半动态绑定平衡智能与可控性，复杂场景才需Agent。建议优先考虑简单模式以降低复杂度。
2026-01-19 02:02:39
416
原创 LangChain 核心架构解析：Runnable 协议与编排原语
LangChain 0.1+架构通过引入Runnable协议统一了核心组件的交互方式，使Prompt、LLM等组件能像Unix管道一样组合。其编排层包含三大原语：Runnable（基础协议）、RunnableLambda（函数封装）和RunnableParallel（并行处理）。Runnable协议要求所有组件实现统一的调用方法（如invoke、stream等），RunnableLambda可将任意Python函数转换为可组合单元，而RunnableParallel支持并行执行多个任务并聚合结果。这种架构特
2026-01-19 01:53:20
885
原创 LangChain LCEL 架构设计与实战解析
本文介绍了LangChain Expression Language (LCEL)的核心功能与应用实践。LCEL作为声明式编排协议，通过统一的Runnable接口解决了LLM应用开发中的组件组合、异步处理等痛点。文章首先展示了基础调用范式，包括同步/异步/流式三种调用策略；然后详细解析了结构化输出解析方法，从基础文本到JSON和Pydantic对象的高级处理；最后通过"旅行规划"案例，演示了如何使用RunnableParallel构建并行执行的复杂拓扑结构，实现多步骤LLM任务的自动编排
2026-01-19 00:19:41
625
原创 企业级 LLM 实战：在受限环境中基于 Copilot API 构建 ReAct MCP Agent
本文介绍了在受限金融IT环境中构建LLM智能代理的实战方案。针对企业级Copilot API不支持标准Function Calling的问题，提出基于ReAct模式和Model Context Protocol(MCP)的创新架构。通过时序图展示了包含请求接收、路由思考、工具调用和响应持久化的完整流程，详细说明了McpToolConverter协议适配器、ToolCallableAgent抽象基类和GithubReactAgent领域专家的设计实现。该方案采用手动构建工具Prompt和JSON解析的方式，实
2026-01-17 02:55:02
1012
原创 深入 ReAct Agent 的灵魂拷问：从幻觉到精准执行的调试实录
摘要： 本文记录了一次基于LLM的智能体(Agent)系统生产环境故障排查过程。系统在多轮对话中出现重复提问和幻觉问题，表现为Agent在调用工具前自行编造虚假回复。通过LangSmith Trace分析发现两大根源：1)历史记录重复存储导致LLM输入重复；2)Main Agent过度预测输出工具结果。修复方案包括：1)在ChatService中实现历史记录去重逻辑；2)强化System Prompt明确工具使用规范；3)代码层拦截混合输出，确保仅返回工具执行结果。此次排查突显了可观测性在LLM应用开发中的
2026-01-17 02:29:36
1195
原创 Pytest 异步数据库测试实战：基于 AsyncMock 的无副作用打桩方案
摘要： 本文探讨如何在异步Python后端（FastAPI+SQLAlchemy Async）中利用unittest.mock框架的AsyncMock和patch对数据库层进行高效Mock测试。传统集成测试依赖真实数据库，存在速度慢、环境复杂和脏数据问题。通过显式定义Mock对象并注入到DAO层，可完全隔离数据库依赖，专注验证业务逻辑。文章以聊天历史去重功能为例，演示如何构造Mock数据、替换DAO方法，并断言业务逻辑的正确性，同时强调patch路径的选择关键（需指向消费者模块而非定义模块）。相比Java的
2026-01-17 00:45:15
825
原创 深入分析：Pytest异步测试中的数据库会话事件循环问题
在运行异步数据库测试时，我们遇到了一个典型的 “Event loop is closed” 或 “got Future attached to a different loop” 错误。第一个异步测试用例成功通过第二个及后续异步测试用例立即失败，抛出错误发生在数据库连接尝试建立时，具体在asyncpg协议层将从session改为function每个测试函数获得独立的事件循环避免测试间的事件循环污染符合测试隔离的最佳实践缓存的对象（引擎）与其依赖的资源（事件循环）具有不同的生命周期。
2026-01-16 01:28:18
364
原创 Python 连接 MCP Server 全指南
特性SSE特性SSE底层实现SDK 模块依赖管理SDK 内部管理需外部注入适用性浏览器友好，兼容性高后端服务间通信，性能更优对于大多数 Python 后端服务（如 Agent 平台），提供了更好的控制力（如自定义 Timeout、Proxy 配置），是更为推荐的选择。
2026-01-15 18:43:17
793
原创 从 SSE 到 Streamable HTTP：MCP Server 的现代化改造之旅
本文介绍了将MCP协议从SSE模式迁移到Streamable HTTP模式的架构升级。SSE模式在云原生环境中存在路径依赖和长连接脆弱性问题，而Streamable HTTP采用标准HTTP POST请求，简化了通信流程，更适合无服务器架构。升级过程主要删除FastAPI包装层，直接使用fastmcp原生支持，保留Header鉴权机制。改造后系统代码量减少50%，部署更稳定，兼容性更好，特别适合云环境部署。Streamable HTTP成为MCP Server上云的推荐方案。
2026-01-15 03:23:36
611
原创 构建 Cline 级智能体：LangChain 与 MCP Server 的深度集成实战
本文详细介绍了基于LangChain构建的GithubAgent智能代理，该代理通过连接MCP Server实现了自动工具发现、规则注入和智能工具调用三大核心功能。文章从架构层面解析了GithubAgent的工作流程，包括初始化阶段的握手连接、工具绑定，以及核心的思考-行动-观察(ReAct)循环机制。重点阐述了5个核心方法：工具发现(_fetch_mcp_tools)、智能适配(_convert_mcp_tools)、规则注入(_extract_instructions)、主循环(_agent_loop)
2026-01-12 03:24:50
1297
原创 深入剖析 LangChain 消息系统：BaseMessageChunk 与 AIMessageChunk 的设计哲学
本文深入解析LangChain框架中BaseMessageChunk与AIMessageChunk的设计差异。BaseMessageChunk作为抽象基类，定义了流式传输的核心属性，但不具备具体业务语义；而AIMessageChunk则针对AI回复场景进行了语义封装。文章指出：类型标注时应使用基类保持通用性，实例化时则需使用具体子类确保语义明确。这种"抽象使用、具体创建"的设计模式，体现了面向对象编程的多态性和封装原则，是构建高效、可维护LLM应用的关键所在。
2026-01-11 21:59:23
264
原创 Cloud Run IAP 认证与跨域通信解决方案全指南
这个模式在 GKE 是没问题的，因为前后端虽然部署在不同的 POD，但是可以共同 under 一个 GKE Gateway 之下。但是前端是无法直接通过 IAP 获取用户信息的，必须通过调用另一个同域的同样的 enable IAP 的 API (通常是同域的后端 API)而前后端都部署在 Cloud Run 上会不同了，两个 Cloud Run svc 天然有两个不同的域名。当前端开启 IAP 后，用户打开前端页面就会被重导向到 Google 账号登陆页面，当用户登陆后就会进入前端页面。
2026-01-10 00:49:27
849
原创 Cookie 技术深度剖析与实战指南
本文档旨在深入解析 HTTP Cookie 的工作原理、核心属性、安全机制以及在现代 Web 开发中的最佳实践。
2026-01-09 23:14:09
1191
原创 Quarkus 应用分层架构
在简单的项目中，如果不涉及数据库，我们将采用简化的(API 层): 接收/api/send请求。(业务层): 处理 Token 刷新和 Gmail API 调用。这种结构清晰、解耦，既符合 Java 开发者的习惯，也能充分利用 Quarkus 的特性。
2026-01-05 01:57:59
739
原创 使用 SDKMAN! 轻松管理你的 jdk 版本
SDKMAN!是一个在类 Unix 系统（如 Linux, macOS, WSL）上用于管理多个软件开发工具包（SDK）并行版本的工具。它不仅能管理不同的 JDK 发行版（如 OpenJDK, GraalVM, Amazon Corretto），还能管理 Maven, Gradle, Kotlin, Scala, Quarkus CLI 等数十种 JVM 生态中的常用工具。简单来说，SDKMAN!就是 Java 世界的nvm(Node) 或pyenv(Python)。如果你熟悉 Python 的pyenv。
2026-01-05 00:12:22
1232
原创 通过 Gmail API 发送邮件的完整指南
本文档详细介绍了如何通过编程方式调用 Google Gmail API 来发送电子邮件。整个过程不依赖于 SMTP，而是使用现代的 OAuth 2.0 授权流程和 REST API 调用，这使得它可以在任何网络环境（包括限制了 SMTP 端口的云服务器）下工作。
2026-01-04 23:04:03
1102
原创 GCP 路由奇案：一次 FastMCP 部署的深度复盘
这不只是一篇技术博客，这是一篇战报。它讲述了一个看似简单的部署任务，如何演变成一场长达数小时、穿越 GCP 负载均衡、Envoy、FastAPI 和 MCP 协议层层迷雾的调试之旅。如果你也曾经历过“本地猛如虎，上线死如狗”的服务，那么，泡杯咖啡，这个故事就是为你准备的。
2026-01-04 21:00:37
639
原创 RAG与向量余弦距离：深入理解大语言模型背后的数学原理
摘要：本文探讨了检索增强生成（RAG）技术如何通过向量余弦距离提升大型语言模型的准确性。RAG通过检索外部知识库中的相关信息来增强生成过程，其中向量余弦距离是关键相似度度量方法。文章详细解释了余弦距离的数学原理及其在高维语义匹配中的优势，并与欧几里得距离进行了对比。此外，还介绍了pgvector如何利用IVFFlat、HNSW等近似最近邻算法和SIMD硬件加速来实现高效向量检索。通过3D坐标可视化，直观展示了向量方向相似性与语义关联的关系。
2026-01-04 12:08:39
867
原创 Cline 远程 MCP 鉴权：踩坑与最佳实践
本文介绍了通过HTTP Header和ContextVars实现MCP Server中GitHub Token动态透传的方案。作者发现Cline客户端虽未明说但实际支持Header传输，于是基于FastAPI构建中间层，利用ContextVar安全存储并发请求中的用户Token，实现了团队协作时各自使用个人Token的需求。该方案具有隔离性、兼容性和安全性优势，本地开发仍可使用.env配置，服务端不存储用户数据，解决了团队协作场景下的鉴权难题。
2026-01-04 00:43:36
619
原创 Python ContextVars 详解：并发编程的隐形传参神器
Python异步编程中，contextvars模块提供了Task-Local Storage解决方案，完美解决调用链深处获取请求上下文的问题。它允许在协程中声明全局变量，但每个协程拥有独立副本，实现并发安全。通过ContextVar可以轻松实现中间件传参和依赖注入，避免层层传递Request对象。需注意在线程池中使用时需手动拷贝上下文，且子Task的修改不会影响父Task。contextvars是解耦代码、提升异步编程效率的利器。
2026-01-03 23:46:46
409
原创 疑难杂症：如何让 Cline 乖乖使用 MCP Tool？
摘要： 开发MCP Server时，Cline可能无视Tool的三大原因及解决方案： 缓存问题：修改Tool后需重启Server和Cline（VS Code中Reload Window）； Tool未暴露：确保函数被@mcp.tool装饰并在入口文件导入； LLM惯性：优化Tool描述（如强调官方性）并在Instructions中强制使用MCP工具。 排查顺序：重启服务→清除缓存→检查装饰器→完善文档→强化指令。（149字）
2026-01-03 22:11:00
961
原创 如何使用 curl 命令行测试 FastMCP (SSE 模式)
在开发 FastMCP Server 时，我们经常需要快速验证某个 Tool 或 Resource 是否工作正常。虽然编写 Python 客户端代码是最正规的方式，但有时手边只有命令行。本文将手把手教你如何使用curl征服 MCP over SSE 协议。
2026-01-03 18:10:22
796
原创 FastMCP 开发指南: 5分钟入门
FastMCP 开发指南摘要 FastMCP 是 MCP 协议的 Python 高级封装库，定位为 MCP 领域的 FastAPI，具有人体工程学设计、自动化转换和高性能特点。核心提供三种能力原语：Tool（执行动作）、Resource（读取数据）和 Prompt（预设指令）。开发关键点在于理解指令系统：宏观层级的 Instructions 定义服务器行为准则，微观层级的 Docstrings 描述工具功能。文章通过交互流程图展示了系统提示的生效机制，并区分了 Instructions 与 Prompts
2026-01-03 17:03:08
774
原创 基于 LangChain + Gemini + CloudSQL (pgvector) 的 RAG 实现指南
本文介绍了一个基于LangChain框架、Google Gemini大模型和CloudSQL PostgreSQL（含pgvector插件）构建的RAG系统。系统采用规范化数据库设计，包含主题分类、文档元数据和向量存储表。数据处理流程包括：1)下载PDF文档；2)通过DataProcessingService协调文本加载、分块、向量生成(Gemini API)和存储；3)使用pgvector存储768维向量。核心模块展示了文档下载、分块处理和数据库交互的实现细节，实现了从原始文档到向量化知识库的完整转换流程
2026-01-02 23:53:18
1369
1
原创 Arch Linux + Niri + Xwayland 故障排查与修复指南
本文档记录了在Arch Linux系统中使用Niri（Wayland合成器）时遇到的Xwayland应用启动失败和光标异常问题的解决方案。启动失败是由于Niri未正确处理XAuthority认证，导致微信等X11应用无法连接显示服务器；光标过大则源于Wayland与X11的光标机制差异。通过部署xwayland-satellite管理Xwayland连接并配置xsettingsd同步光标设置，成功解决了这两个问题。关键步骤包括安装相应组件、修改Niri配置文件，并重启会话使更改生效。该方案为在轻量级Wayl
2026-01-02 20:37:20
1057
原创 RAG Agent 响应策略：文档与分析
本文对比了RAG问答系统的两种文档检索展示方案：显式检索(RAG Chain)和工具调用代理(Tool Calling Agent)。显式检索实现简单但缺乏灵活性，而工具调用代理虽复杂但支持智能决策和多步推理。项目最终采用方案2，通过三层架构实现：外层封装处理结果组装，中间层管理工具路由，底层负责推理生成。核心代码解析展示了如何从检索服务获取格式化文档片段，并通过代理执行流程提取答案和来源文档，确保引用准确性同时保留智能特性。该方案有效平衡了系统可信度与灵活性需求。
2026-01-02 03:30:02
1022
原创 故障排查：Pytest Asyncio Event Loop Closed 错误
本文分析了在使用pytest-asyncio运行异步测试时出现的RuntimeError问题。问题根源在于SQLAlchemy的AsyncEngine实例被缓存后绑定到已关闭的事件循环，导致后续测试失败。通过修改db_sessionfixture，在每次获取引擎前清除缓存，确保创建绑定到当前事件循环的新引擎实例。这种方法解决了引擎绑定错误循环的问题，同时提供了替代方案供参考，如调整事件循环作用域或使用全局配置。该修复方案简单有效，保证了测试隔离性和可靠性。
2025-12-31 00:45:03
416
原创 SQLAlchemy 2.0 类型注解指南：`Mapped` 与 `mapped_column`
SQLAlchemy 2.0+引入的Mapped类型注解和mapped_column构造函数改进了ORM声明式映射系统，解决了旧版Column写法在静态类型检查和IDE支持方面的问题。新写法通过显式类型标注（如Mapped[int]）使代码更清晰，自动处理nullable属性（Optional[str]对应nullable=True），并支持复杂类型（UUID、DateTime）和关系映射。相比旧版，新风格提供了更好的类型提示支持，增强了代码的健壮性和可维护性，同时兼容静态分析工具和IDE智能感知功能。
2025-12-29 23:36:02
614
原创 PDFLoader 中的 OCR 文字提取实现详解
本文提出了一种混合PDF文本提取方法，通过结合PyPDFLoader原生文本提取和RapidOCR图像识别技术，有效解决了PDF中嵌入图像文字的提取问题。方法采用pypdf解析PDF页面，使用基于ONNX Runtime的RapidOCR引擎进行高效OCR识别，无需安装系统级组件。核心流程包括：1)提取原生文本层；2)选择性OCR增强处理；3)文本合并。该方法通过延迟加载OCR引擎、就地修改文档内容等技术优化性能，确保既能保留原始文本，又能准确提取图像中的文字内容。
2025-12-28 09:42:10
850
原创 Python 抽象属性 (@property + @abstractmethod) 详解
本文介绍了在Python中使用@property和@abstractmethod组合定义抽象属性的方法。这种模式能够强制子类提供一个只读的数据接口，同时保持实现的灵活性。子类既可以用简单的类属性赋值实现，也可以通过@property方法动态计算属性值。这种设计使接口语义更清晰（表示特征而非动作），调用方式统一（都通过obj.field访问），并兼顾了简单静态配置和复杂动态逻辑两种实现需求。示例展示了静态配置和动态计算两种实现方式，体现了Python在抽象属性设计上的优势。
2025-12-28 07:10:27
380
原创 Python 泛型 (Generics) 详解
本文介绍了Python泛型的使用方法，通过与Java泛型的对比帮助理解两者的差异。主要内容包括： Python泛型基础：通过TypeVar定义类型变量，实现泛型函数和类，支持多类型变量和上界约束。 与Java泛型的核心差异： Java采用类型擦除，运行时无法获取泛型信息 Python泛型是运行时真实对象，但类型检查需依赖外部工具 实际应用示例：展示了泛型在Repository模式中的使用场景。 Python泛型通过类型提示提高代码安全性，同时保持动态语言的灵活性，适合大型项目开发。3.12版本后语法更简洁，
2025-12-28 06:59:46
998
原创 创建自己的云开发环境-GCP Cloud Workstations 配置指南
本文档详细介绍了如何从零开始在 Google Cloud Platform (GCP) 上配置 Cloud Workstations 开发环境。
2025-12-27 23:33:01
715
空空如也
空空如也
TA创建的收藏夹 TA关注的收藏夹
TA关注的人