在 RAG 知识库项目中排查文档同步任务全部标记 failed 的静默故障，以下是完整排查过程。
重构一个公共方法改了参数签名，但漏改了一个调用方。调用方按旧契约传参抛 TypeError，而这个调用被包在 try/except 里，异常被悄悄吞进 failed 计数——服务不崩溃、日志没有 ERROR，只有计数字段悄悄上涨。这类「静默故障」是最难查的 bug。两个解法：重构签名后 grep 所有调用方同步；except 块必须记日志或重抛，绝不静默吞掉。
在为客户构建 AI Agent 系统时，我们发现不同任务对模型能力和成本的需求差异很大：图像分析用视觉模型、文本补全用轻量模型、内部数据查询用本地模型。MCP（Model Context Protocol）让每个能力变成独立的工具，AI 客户端按需调用。
用 Python FastMCP 30 分钟搭建自定义 MCP Server，按场景和成本接入任意 OpenAI 兼容 API。本文以豆包视觉模型为例演示完整流程，并提供文本生成、图像生成、语音合成等场景的扩展模板。
在为客户构建 AI Agent 平台时遇到此问题：需要支持多个搜索提供商（Tavily、Serper、Brave、Bing），同时确保工具调用失败时不会中断 Agent 对话流程。
SearchProvider 抽象基类 + SearchResult 数据模型，统一接口和输出格式search() 方法，内部做响应字段映射SearchResult 对象，而非抛异常在构建多服务协作的 SaaS 系统时遇到此问题，记录根因与解法。
httpx.AsyncClient 不要用 async with client.post() 模式，应该先创建 client 再调用方法：response = await client.post()。
Pydantic v2 不再支持 class Config，需要用 model_config = ConfigDict(from_attributes=True)。如果你的模型有 model_config 字段，必须重命名避免与保留字冲突。
在 RAG 知识库项目中调试查询结果返回格式问题，以下是完整排查过程。
RAG /query 接口返回的 sources 字段只包含 metadata，没有每条来源的 similarity 分数。解决方案：在组装响应时，将 metadatas 和 distances 合并，计算 similarity = 1 - distance。
在 RAG 知识库项目中调试混合检索评分问题，以下是完整排查过程。
Milvus 混合搜索（Dense + Sparse）有四个常见坑：空稀疏向量报错、Collection 未加载、sparse 格式错误、阈值过高。本文给出每个问题的最小修复代码。