- 博客(584)
- 收藏
- 关注
RSS订阅原创 架构师视角：彻底搞懂 AI Gateway 与 Agent Router 的本质区别
Router 决定了“这个活儿该派给谁干”，而 Gateway 保障了“干活的底层通道安全、便宜且永不宕机”。理清这一架构边界，是构建高可用、可扩展的企业级 Multi-Agent 系统的第一步。
2026-04-19 21:41:35
180
原创 深入解析 LCEL 架构：`RunnableParallel` vs `RunnablePassthrough.assign` 的核心抉择
本文对比了LangChain管道中RunnableParallel和RunnablePassthrough.assign()的核心差异。RunnableParallel适用于数据重构，可丢弃冗余信息并支持非字典输入转换；而.assign()适合在管道中游增量补充数据，保留原有上下文但需注意链式调用会导致串行执行。架构选型建议：入口层用RunnableParallel结构化输入，业务层用.assign()增量补充，模型前置层再用RunnableParallel清洗数据。RunnableParallel在Lan
2026-04-19 20:51:20
97
原创 深度解析 LangChain 0.1+ `astream_events`：从“物理延迟”到“UX 优化”的工程进阶
本文深入解析LangChain的astream_eventsAPI如何优化LLM应用的用户体验。传统.stream()方法在复杂链路（如RAG系统）中会因阻塞性操作导致首字响应时间过长，造成前端"死寂"等待。astream_events通过流式化中间状态，将管道各节点生命周期作为事件流推送，显著降低感知等待时间。文章对比了手动yield方案的三大缺陷：破坏声明式语法、并发管理复杂和标准化不足，并提供了实战代码演示如何利用astream_events截获和渲染中间状态，实现从"检
2026-04-19 20:05:31
89
原创 深度解析 JWT：分布式架构下的鉴权博弈与防伪逻辑
《JWT在分布式架构中的设计权衡》摘要： 本文剖析JWT在微服务架构中的核心机制与工程实践。通过解码JWT三段式结构，揭示其客户端透明但防篡改的特性；对比对称(HS256)与非对称(RS256)加密方案的适用场景，指出密钥管理在微服务矩阵中的关键差异；结合Mermaid时序图展示端到端鉴权流程，强调公钥验签的架构优势；最后批判性讨论Token Introspection机制的性能退化问题，提出坚持短时效JWT配合Refresh Token才是平衡安全与性能的最优解。全文贯穿密码学原理与架构哲学的深度思考。
2026-04-05 02:01:40
348
原创 模型评估体系架构解析
本文提出一个基于分类树结构的模型评估架构，将系统分为传统机器学习（ML Models）和检索增强生成代理（RAG Agent）两大评估赛道。ML Models部分详细介绍了简单过滤模型的精确率、召回率和F1 Score评估指标，以及黑盒模型的可解释性方法LIME和SHAP。RAG Agent部分则聚焦于评估知识检索与文本生成的综合性能。该架构为不同场景下的系统评估提供了量化基准和实用工具集，覆盖从传统统计学习到现代生成式AI的全谱系评估需求。
2026-04-03 00:26:33
383
原创 GCP 无服务器事件驱动实战：使用 Terraform 构建 Pub/Sub 推送至 Cloud Run 的微型调度中心
本文介绍了如何利用GCP服务构建事件驱动的数据湖架构，解决传统流式处理方案中的资源浪费和DAG爆炸问题。通过将架构重构为"微型事件调度+轻量级批处理"模式，采用Cloud Run作为接收端和调度器，配合Pub/Sub Push Subscription实现自动缩容至零的机制。文章详细演示了使用Python FastAPI开发微服务接收端，以及通过Terraform编排基础设施，包括创建专用Service Account、配置OIDC Token鉴权等安全措施。测试验证表明，该架构能有效隔
2026-03-27 00:22:31
418
原创 OpenClaw 无缝接入 Slack 全图文实战指南
摘要： 本文提供OpenClaw AI助手无缝集成Slack的完整指南。通过Socket Mode实现无需公网IP的双向通讯，包含7个关键步骤：1)创建Slack应用；2)开启Socket Mode获取App-Level Token；3)配置必要权限(如chat:write、files:write)；4)订阅消息事件；5)安装应用获取Bot Token；6)邀请机器人进频道；7)配置OpenClaw网关参数。特别强调权限配置避坑点，解决常见的missing_scope错误。完成配置后，可通过Slack直接与
2026-03-18 00:07:37
517
原创 LangChain 组件详解：RunnablePassthrough
RunnablePassthrough是LangChain LCEL中的关键组件，主要实现数据透传功能。它有两种核心用途：1）在并行处理中保留原始输入，如RAG场景中同时传递检索结果和原始问题；2）通过.assign()方法增量更新字典数据。该组件在构建复杂数据流时尤为重要，能确保信息完整传递，避免手动处理字典的繁琐操作，是LangChain实现高效数据处理的重要工具。
2026-02-27 21:49:25
400
原创 LangChain 核心机制：RunnableParallel 与隐式转换
本文解释了LCEL中字典语法的底层机制。当在Chain中使用字典时，系统会自动将其转换为RunnableParallel对象，实现并行执行多个任务。这种隐式转换让代码更简洁，同时保持并行处理的特性。通过验证实验证实，字典语法和显式写法性能相同（耗时1秒），证明字典确实被动态转换为并行执行逻辑。该设计简化了高频的并行操作场景，特别是在构建Prompt输入时，能方便地组合多个数据源。理解这一机制有助于读懂复杂的LCEL代码。
2026-02-01 11:12:06
416
原创 LangChain 经典回顾：ConversationBufferMemory 与 ConversationChain
本文深入解析LangChain经典对话组件ConversationBufferMemory与ConversationChain的核心机制。ConversationBufferMemory作为基础记忆组件，完整存储对话历史但存在token爆炸风险；ConversationChain则是预封装的三合一解决方案（LLM+Memory+Prompt），开箱即用但存在实例级状态绑定的并发限制。文章通过代码示例展示了组件使用方法，并对比新旧架构的本质差异：传统方案采用硬编码的有状态实例，而LCEL新方案通过动态注入实现
2026-01-31 23:38:03
732
原创 LangChain 实战：RunnableWithMessageHistory 深度详解
是 LangChain 中优雅管理状态的瑞士军刀。它通过配置化的方式，将繁琐的历史记录读写逻辑从业务逻辑中剥离出来，极大地简化了代码结构。记忆口诀Config定身份 (session_id)。Factory找仓库 (get_session_history)。Keys做映射 (input/history keys)。
2026-01-31 21:41:08
748
原创 LangChain 核心对比：ChatPromptTemplate vs PromptTemplate
摘要： LangChain开发中，PromptTemplate与ChatPromptTemplate分别适配不同模型范式。前者面向传统文本续写模型（如GPT-3），通过字符串插值生成单一文本；后者专为对话模型（如GPT-4）设计，以结构化消息列表（System/User/Assistant）支持角色交互。关键差异包括数据结构、变量处理方式及适用场景。尽管简单任务可用Python原生字符串替代，PromptTemplate仍提供部分填充、输入验证、序列化等工程化优势。随着对话模型成为主流，ChatPrompt
2026-01-31 01:49:27
504
原创 LangChain 进阶：深入解析 MessagesPlaceholder
本文深入解析LangChain中的MessagesPlaceholder组件，它在构建对话式应用时至关重要。现代Chat Model接收结构化消息列表而非单一文本，MessagesPlaceholder作为占位符可将消息对象列表直接嵌入消息队列，保持数据结构完整。文章对比了传统文本拼接与现代结构化消息的差异，并通过代码示例展示其正确用法与常见误区。MessagesPlaceholder主要应用于对话历史管理和Agent推理轨迹场景，必须配合ChatPromptTemplate使用。正确使用该组件可构建结构清
2026-01-31 01:28:40
549
原创 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
681
原创 LangChain LCEL 进阶：深入解析 RunnableBranch 与语义路由
本文深入解析了LangChain LCEL中的RunnableBranch与语义路由机制。首先介绍了RunnableBranch的基础原理，它类似于编程中的if-elif-else结构。然后通过两个实战案例：基于关键词的简单路由和基于LLM的语义路由，展示了如何实现智能的任务分发。语义路由通过LLM先识别意图再进行分发，解决了自然语言的模糊性问题。最后将这一模式延伸到多Agent系统架构，说明其在实际企业应用中的价值，如DevOps助手等场景，实现了关注点分离和系统扩展性。掌握语义路由是构建复杂智能系统的关
2026-01-19 02:25:04
449
原创 LangChain LCEL 工具调用实战：从确定性链到动态 Agent
本文介绍了LangChain中三种LLM工具调用模式：确定性显式调用（强制执行固定流程）、半动态绑定（LLM决定单次调用）和高度动态Agent（多步循环）。通过代码示例展示了前两种模式的实现，强调应根据业务确定性选择最简单可行的方案。显式调用最稳定但缺乏灵活性，半动态绑定平衡智能与可控性，复杂场景才需Agent。建议优先考虑简单模式以降低复杂度。
2026-01-19 02:02:39
438
原创 LangChain 核心架构解析：Runnable 协议与编排原语
LangChain 0.1+架构通过引入Runnable协议统一了核心组件的交互方式，使Prompt、LLM等组件能像Unix管道一样组合。其编排层包含三大原语：Runnable（基础协议）、RunnableLambda（函数封装）和RunnableParallel（并行处理）。Runnable协议要求所有组件实现统一的调用方法（如invoke、stream等），RunnableLambda可将任意Python函数转换为可组合单元，而RunnableParallel支持并行执行多个任务并聚合结果。这种架构特
2026-01-19 01:53:20
959
原创 LangChain LCEL 架构设计与实战解析
本文介绍了LangChain Expression Language (LCEL)的核心功能与应用实践。LCEL作为声明式编排协议，通过统一的Runnable接口解决了LLM应用开发中的组件组合、异步处理等痛点。文章首先展示了基础调用范式，包括同步/异步/流式三种调用策略；然后详细解析了结构化输出解析方法，从基础文本到JSON和Pydantic对象的高级处理；最后通过"旅行规划"案例，演示了如何使用RunnableParallel构建并行执行的复杂拓扑结构，实现多步骤LLM任务的自动编排
2026-01-19 00:19:41
653
原创 企业级 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
1108
原创 深入 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
1214
原创 Pytest 异步数据库测试实战：基于 AsyncMock 的无副作用打桩方案
摘要： 本文探讨如何在异步Python后端（FastAPI+SQLAlchemy Async）中利用unittest.mock框架的AsyncMock和patch对数据库层进行高效Mock测试。传统集成测试依赖真实数据库，存在速度慢、环境复杂和脏数据问题。通过显式定义Mock对象并注入到DAO层，可完全隔离数据库依赖，专注验证业务逻辑。文章以聊天历史去重功能为例，演示如何构造Mock数据、替换DAO方法，并断言业务逻辑的正确性，同时强调patch路径的选择关键（需指向消费者模块而非定义模块）。相比Java的
2026-01-17 00:45:15
844
原创 深入分析：Pytest异步测试中的数据库会话事件循环问题
在运行异步数据库测试时，我们遇到了一个典型的 “Event loop is closed” 或 “got Future attached to a different loop” 错误。第一个异步测试用例成功通过第二个及后续异步测试用例立即失败，抛出错误发生在数据库连接尝试建立时，具体在asyncpg协议层将从session改为function每个测试函数获得独立的事件循环避免测试间的事件循环污染符合测试隔离的最佳实践缓存的对象（引擎）与其依赖的资源（事件循环）具有不同的生命周期。
2026-01-16 01:28:18
383
原创 Python 连接 MCP Server 全指南
特性SSE特性SSE底层实现SDK 模块依赖管理SDK 内部管理需外部注入适用性浏览器友好，兼容性高后端服务间通信，性能更优对于大多数 Python 后端服务（如 Agent 平台），提供了更好的控制力（如自定义 Timeout、Proxy 配置），是更为推荐的选择。
2026-01-15 18:43:17
947
原创 从 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
659
原创 构建 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
1395
原创 深入剖析 LangChain 消息系统：BaseMessageChunk 与 AIMessageChunk 的设计哲学
本文深入解析LangChain框架中BaseMessageChunk与AIMessageChunk的设计差异。BaseMessageChunk作为抽象基类，定义了流式传输的核心属性，但不具备具体业务语义；而AIMessageChunk则针对AI回复场景进行了语义封装。文章指出：类型标注时应使用基类保持通用性，实例化时则需使用具体子类确保语义明确。这种"抽象使用、具体创建"的设计模式，体现了面向对象编程的多态性和封装原则，是构建高效、可维护LLM应用的关键所在。
2026-01-11 21:59:23
281
原创 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
864
原创 Cookie 技术深度剖析与实战指南
本文档旨在深入解析 HTTP Cookie 的工作原理、核心属性、安全机制以及在现代 Web 开发中的最佳实践。
2026-01-09 23:14:09
1217
原创 Quarkus 应用分层架构
在简单的项目中，如果不涉及数据库，我们将采用简化的(API 层): 接收/api/send请求。(业务层): 处理 Token 刷新和 Gmail API 调用。这种结构清晰、解耦，既符合 Java 开发者的习惯，也能充分利用 Quarkus 的特性。
2026-01-05 01:57:59
766
原创 使用 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
1321
原创 通过 Gmail API 发送邮件的完整指南
本文档详细介绍了如何通过编程方式调用 Google Gmail API 来发送电子邮件。整个过程不依赖于 SMTP，而是使用现代的 OAuth 2.0 授权流程和 REST API 调用，这使得它可以在任何网络环境（包括限制了 SMTP 端口的云服务器）下工作。
2026-01-04 23:04:03
1194
原创 GCP 路由奇案：一次 FastMCP 部署的深度复盘
这不只是一篇技术博客，这是一篇战报。它讲述了一个看似简单的部署任务，如何演变成一场长达数小时、穿越 GCP 负载均衡、Envoy、FastAPI 和 MCP 协议层层迷雾的调试之旅。如果你也曾经历过“本地猛如虎，上线死如狗”的服务，那么，泡杯咖啡，这个故事就是为你准备的。
2026-01-04 21:00:37
661
原创 RAG与向量余弦距离：深入理解大语言模型背后的数学原理
摘要：本文探讨了检索增强生成（RAG）技术如何通过向量余弦距离提升大型语言模型的准确性。RAG通过检索外部知识库中的相关信息来增强生成过程，其中向量余弦距离是关键相似度度量方法。文章详细解释了余弦距离的数学原理及其在高维语义匹配中的优势，并与欧几里得距离进行了对比。此外，还介绍了pgvector如何利用IVFFlat、HNSW等近似最近邻算法和SIMD硬件加速来实现高效向量检索。通过3D坐标可视化，直观展示了向量方向相似性与语义关联的关系。
2026-01-04 12:08:39
895
原创 Cline 远程 MCP 鉴权：踩坑与最佳实践
本文介绍了通过HTTP Header和ContextVars实现MCP Server中GitHub Token动态透传的方案。作者发现Cline客户端虽未明说但实际支持Header传输，于是基于FastAPI构建中间层，利用ContextVar安全存储并发请求中的用户Token，实现了团队协作时各自使用个人Token的需求。该方案具有隔离性、兼容性和安全性优势，本地开发仍可使用.env配置，服务端不存储用户数据，解决了团队协作场景下的鉴权难题。
2026-01-04 00:43:36
672
原创 Python ContextVars 详解：并发编程的隐形传参神器
Python异步编程中，contextvars模块提供了Task-Local Storage解决方案，完美解决调用链深处获取请求上下文的问题。它允许在协程中声明全局变量，但每个协程拥有独立副本，实现并发安全。通过ContextVar可以轻松实现中间件传参和依赖注入，避免层层传递Request对象。需注意在线程池中使用时需手动拷贝上下文，且子Task的修改不会影响父Task。contextvars是解耦代码、提升异步编程效率的利器。
2026-01-03 23:46:46
441
原创 疑难杂症：如何让 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
1006
原创 如何使用 curl 命令行测试 FastMCP (SSE 模式)
在开发 FastMCP Server 时，我们经常需要快速验证某个 Tool 或 Resource 是否工作正常。虽然编写 Python 客户端代码是最正规的方式，但有时手边只有命令行。本文将手把手教你如何使用curl征服 MCP over SSE 协议。
2026-01-03 18:10:22
941
原创 FastMCP 开发指南: 5分钟入门
FastMCP 开发指南摘要 FastMCP 是 MCP 协议的 Python 高级封装库，定位为 MCP 领域的 FastAPI，具有人体工程学设计、自动化转换和高性能特点。核心提供三种能力原语：Tool（执行动作）、Resource（读取数据）和 Prompt（预设指令）。开发关键点在于理解指令系统：宏观层级的 Instructions 定义服务器行为准则，微观层级的 Docstrings 描述工具功能。文章通过交互流程图展示了系统提示的生效机制，并区分了 Instructions 与 Prompts
2026-01-03 17:03:08
899
原创 基于 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
1425
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
1292
空空如也
空空如也
TA创建的收藏夹 TA关注的收藏夹
TA关注的人