罗罗编程学习记录
本页内容 展开查看

05.6.11.4 Python 后端 FastAPI 与 Django 集成

所属:全栈开发面试题库 / 05 数据库与存储 / 05.6 向量数据库与语义检索 / 05.6.11 向量检索工程化与生态集成

覆盖范围

  • 异步向量库客户端与事件循环约束、同步 SDK 的阻塞隔离
  • 依赖注入管理客户端生命周期、连接池与并发上限
  • 后台任务与批处理入库、Embedding 调用与向量写入顺序
  • Django ORM 与原生 SQL 分工、迁移中维护向量索引
  • DRF 接口设计、流式返回、限流与超时、重试与幂等
  • 错误处理与降级、日志指标 trace、压测方法、常见接入坑

集成链路主线

启动期:构造 / 复用向量库客户端与 Embedding 客户端(连接池)
在线请求:参数校验 → 检索(filter / topK / 超时)→ 组装上下文 → 返回
离线入库:文档读取 → 切块 → 批量 Embedding → 幂等写入向量库 → 对账

高频题速览

编号 题目 难度 频率
05.6.11.4-002 异步客户端与事件循环约束 进阶 ★★★★★
05.6.11.4-004 依赖注入管理客户端生命周期 进阶 ★★★★★
05.6.11.4-005 连接池配置与并发上限 高级 ★★★★☆
05.6.11.4-007 批处理入库节奏与失败重试 高级 ★★★★☆
05.6.11.4-010 迁移文件里维护向量索引的注意事项 高级 ★★★☆☆
05.6.11.4-014 限流:按接口 / 租户限速 进阶 ★★★★☆
05.6.11.4-017 Embedding 与向量写入的顺序与补偿 高级 ★★★★★
05.6.11.4-023 链路追踪 trace 透传 高级 ★★★☆☆
05.6.11.4-024 压测方法与指标口径 高级 ★★★★☆
05.6.11.4-048 一套 FastAPI / Django RAG 后端接入清单 高级 ★★★★★

05.6.11.4-001 FastAPI 接入向量库的整体链路是什么?

频率 ★★★☆☆ | 难度 基础

一句话结论

FastAPI 后端在请求链路中调用向量库客户端完成检索,在线只做查询与组装,入库与重建走离线 / 异步任务;客户端与配置在应用启动期初始化复用。

概念解释

  • 在线链路:参数校验 → 向量检索 → 结果组装 → 响应。
  • 离线链路:读取文档 → 切块 → 批量向量化 → 写入向量库。
  • 生命周期:客户端进程内复用,不在请求级反复创建。

原理流程

启动初始化客户端 → 请求进入 → 检索调用(带超时与过滤)→ 组装返回
   → 后台 / 任务队列完成入库与对账

代码 / 命令

# 面试表达:先分在线检索与离线入库两条链路,再讲客户端复用与超时兜底
# 不展开 FastAPI 路由基础,落点在向量库接入与生命周期

常见误区

  • 误区:请求期实时切块向量化入库。正解:入库应离线完成,在线只检索已建好的索引。
  • 误区:每个请求新建向量库客户端。正解:客户端与连接池应复用,避免连接耗尽。

追问

  • 问:新文档如何被检索到?答:经离线 / 异步入库流程写入向量库并对账确认后,在线才可命中。
  • 问:在线链路能调用 Embedding 吗?答:查询向量化是检索必需环节,批量入库向量化不应放在在线请求里。

05.6.11.4-002 异步向量库客户端与事件循环有什么约束?

频率 ★★★★★ | 难度 进阶

一句话结论

异步客户端在事件循环内以非阻塞方式等待 IO,协程内不能混入阻塞调用;客户端实例、循环绑定与并发任务数量都要按异步模型管理。

概念解释

  • 非阻塞:IO 等待让出事件循环,其他协程继续执行。
  • 约束:同步阻塞 SDK、CPU 密集计算不能裸写在协程里。
  • 并发:通过异步任务并发控制,而非无限开协程。

原理流程

异步路由 → await 异步客户端检索 → IO 等待让出循环 → 结果返回
   → 并发任务用信号量 / 队列限制数量

代码 / 命令

# 检查点:调用是否为异步方法;客户端是否在循环内正确初始化
# 待确认:所用向量库 Python SDK 是否提供异步接口,以官方仓库为准

常见误区

  • 误区:async 路由里所有调用自动异步。正解:只有非阻塞客户端不占事件循环。
  • 误区:异步客户端可以在多个循环间随意复用。正解:客户端与事件循环的绑定关系需按 SDK 说明核对。

追问

  • 问:没有异步客户端怎么办?答:阻塞调用放到线程池执行,避免卡住事件循环,并控制池大小。
  • 问:异步并发怎么防失控?答:信号量限并发 + 超时 + 退避重试 + 下游配额核对。

05.6.11.4-003 同步 SDK 在异步路由中阻塞事件循环怎么识别与处理?

频率 ★★★★☆ | 难度 高级

一句话结论

协程内直接调用同步 SDK 会阻塞事件循环,表现为接口整体抖动、并发上不去;识别后用线程池隔离阻塞调用或更换异步客户端。

概念解释

  • 信号:事件循环线程占满、无关请求同时变慢、IO 等待分布异常。
  • 根因:阻塞调用占住循环线程。
  • 解法:线程池隔离,或使用底层支持的异步客户端。

原理流程

延迟抖动 → 排查协程内调用 → 确认同步 SDK 阻塞 → 线程池隔离 / 换异步客户端 → 压测回归

代码 / 命令

# 检查:异步函数内是否出现同步 SDK 调用、同步 Embedding 调用
# 处置:阻塞操作走独立线程池并限并发,优先评估官方异步集成

常见误区

  • 误区:加 await 包装同步方法就是异步。正解:底层阻塞仍占循环线程。
  • 误区:线程池越大越好。正解:下游连接与配额有限,过大并发触发限流与超时。

追问

  • 问:怎么确认是事件循环阻塞?答:看循环线程占用与请求排队时长,区分下游慢与循环被卡住。
  • 问:线程池并发怎么定?答:按下游连接数与速率配额反推,不让线程数超过承载能力。

05.6.11.4-004 依赖注入如何管理客户端生命周期?

频率 ★★★★★ | 难度 进阶

一句话结论

通过依赖注入在应用启动期构造客户端并注册为复用实例,请求级获取同一实例,关闭时统一释放连接;避免请求级创建销毁。

概念解释

  • 初始化:连接配置、Embedding 客户端、向量库客户端一次性构造。
  • 复用:进程内单例,共享连接池。
  • 释放:应用关闭时关闭客户端连接,避免连接泄漏。

原理流程

启动 → 读取配置 → 构造客户端并注册 → 请求注入复用 → 关闭时释放资源

代码 / 命令

# 生命周期要点:启动初始化、单例复用、优雅关闭
# 多环境:按配置构造对应实例,避免测试实例被生产请求误使用

常见误区

  • 误区:依赖注入每次调用新建客户端。正解:应配置为复用作用域,共享连接池。
  • 误区:客户端无状态可随意复制。正解:内部持有连接池,复用才有意义。

追问

  • 问:初始化失败怎么处理?答:启动期快速失败并告警,不带病进入请求阶段。
  • 问:多套配置并存怎么办?答:按环境 / 业务域注册命名实例,显式取用而非默认注入。

05.6.11.4-005 连接池配置与并发上限如何确定?

频率 ★★★★☆ | 难度 高级

一句话结论

连接池大小按下游最大连接数、单请求耗时与目标并发反推,配合客户端超时与队列限制;池过大耗尽下游,过小排队等待。

概念解释

  • 依据:下游连接上限、请求耗时、目标 QPS。
  • 组成:最大连接、空闲保留、获取超时、等待队列。
  • 观测:池活跃数、等待队列、获取连接耗时。

原理流程

估算目标并发 → 核对下游连接配额 → 设定池大小与等待队列 → 压测观察水位 → 微调上限

代码 / 命令

# 核对:池上限不超过下游连接配额;等待队列有界;获取连接有超时
# 待确认:具体池参数名与默认值以所用 SDK 文档为准

常见误区

  • 误区:连接池越大性能越好。正解:下游连接与内存有限,过大并发压垮服务端。
  • 误区:池参数照搬示例值。正解:必须按自身 QPS、耗时与下游配额压测确定。

追问

  • 问:连接获取超时怎么表现?答:请求排队后获取连接超时,应计入检索失败指标并降级。
  • 问:长连接空闲被服务端断开怎么办?答:配置空闲校验 / 重连机制,按 SDK 说明核对。

05.6.11.4-006 后台任务如何承接异步入库?

频率 ★★★★☆ | 难度 进阶

一句话结论

后台任务承接切块、向量化与写入等耗时操作,不阻塞在线响应;任务需可追踪状态、可重试、可对账,避免请求结束后任务丢失。

概念解释

  • 适用:单条 / 小批量文档入库、索引刷新。
  • 约束:后台任务生命周期与请求解绑,失败要可观测。
  • 演进:大批量或需要持久化队列时改用任务队列系统。

原理流程

请求提交入库任务 → 后台异步执行 → 记录任务状态与批次 → 成功 / 失败可追踪 → 对账补写

代码 / 命令

# 记录:任务标识、文档 id、状态、失败原因、重试次数
# 注意:进程内后台任务随进程重启可能丢失,关键入库走持久化队列

常见误区

  • 误区:后台任务失败无需记录。正解:失败不可见会表现为线上检索缺文档,必须留痕。
  • 误区:所有入库都用请求内后台任务。正解:大批量应走独立任务队列与离线窗口。

追问

  • 问:后台任务与请求生命周期怎么隔离?答:任务提交后不依赖请求对象存活,状态落库或队列。
  • 问:任务重复提交怎么防重?答:按文档 id 幂等处理,重复执行不产生重复向量。

05.6.11.4-007 批处理入库:分批、节奏与失败重试怎么做?

频率 ★★★★☆ | 难度 进阶

一句话结论

批量入库按 Embedding 上限、向量库写入上限分批,控制并发与间隔,失败批次隔离后按幂等键重试,成功批次登记水位。

概念解释

  • 分批依据:模型单次输入、底层批量接口、内存承受。
  • 节奏:批大小、并发度、批间隔按下游承载设定。
  • 重试:区分可重试与不可重试错误,退避重试,失败条目隔离。

原理流程

文档列表 → 切块 → 分批向量化 → 批量写入 → 成功登记水位 / 失败记录原因
   → 退避重试 / 隔离队列 → 对账补写

代码 / 命令

# 批次台账:批次号、条数、状态、失败原因、重试次数、时间
# 幂等:按 doc_id 覆盖,重复重试不产生重复向量

常见误区

  • 误区:整批失败就整批重跑。正解:定位失败条目小批重试,避免放大重复写入。
  • 误区:失败批次无人跟踪。正解:失败积压表现为线上检索缺失,必须有对账与告警。

追问

  • 问:入库速率怎么定?答:压测 Embedding 与向量库两侧上限,取较小值并留余量。
  • 问:历史大批量数据怎么导?答:离线分批、断点续跑、错峰执行,不挤占在线检索资源。

05.6.11.4-008 Django 接入向量库的分层怎么划分?

频率 ★★★☆☆ | 难度 基础

一句话结论

Django 侧按视图 / 服务层 / 客户端封装分层:视图处理请求与响应,服务层编排检索与业务规则,客户端封装向量库调用与配置。

概念解释

  • 视图:参数校验、响应结构、权限入口。
  • 服务:检索编排、过滤条件组装、结果兜底。
  • 客户端:连接配置、SDK 调用、超时重试封装。
  • 原则:向量库细节不外泄到视图层。

原理流程

视图接收请求 → 服务层组装检索条件 → 客户端调用向量库 → 结果回传服务组装 → 视图响应

代码 / 命令

# 分层核对:SDK 调用集中在客户端封装;业务规则在服务层;视图不直接持有 SDK
# 不展开 Django 视图与 ORM 基础教学

常见误区

  • 误区:视图里直接写向量库 SDK 调用。正解:封装到客户端 / 服务层,便于替换与测试。
  • 误区:检索规则散落在多个视图。正解:公共检索逻辑沉淀到服务层,避免重复与不一致。

追问

  • 问:服务层与客户端怎么分工?答:客户端只管连接与原生调用,服务层负责条件、兜底与编排。
  • 问:如何便于单元测试?答:客户端抽象为接口,测试中替换为假实现,隔离向量库依赖。

05.6.11.4-009 Django ORM 与原生 SQL 在向量字段上如何分工?

频率 ★★★☆☆ | 难度 进阶

一句话结论

业务元数据与状态走 ORM 持久化,向量近邻检索在专用向量库完成;确需在关系库内做向量查询时才写原生 SQL,两者通过文档 id 关联。

概念解释

  • ORM 负责:业务记录、元数据、状态、关联 id。
  • 向量库负责:片段向量、近邻检索、标量过滤。
  • 原生 SQL:关系库内向量字段查询等 ORM 不便表达的场景。

原理流程

ORM 写业务记录 → 取文档 id → 向量库写入片段与向量
   → 向量检索命中 id → 回 ORM 补全业务信息

代码 / 命令

# 关联键:业务主键 / 文档 id 写入向量 metadata
# 原生 SQL 场景:关系库向量列的近邻查询、复杂聚合;其余走 ORM

常见误区

  • 误区:把大段向量存 ORM 模型字段。正解:向量放专用存储,ORM 只留关联 id 与版本。
  • 误区:ORM 事务内同步写向量库。正解:跨库一致性靠提交后补偿,不用本地事务。

追问

  • 问:检索结果如何补全业务信息?答:按命中文档 id 批量查 ORM,避免逐条查询。
  • 问:原生 SQL 怎么防注入?答:参数化查询,不拼接用户输入进 SQL 字符串。

05.6.11.4-010 迁移文件里维护向量索引有哪些注意事项?

频率 ★★★☆☆ | 难度 进阶

一句话结论

关系库迁移只维护业务表与向量关联字段,专用向量库的集合 / 索引创建不走 Django 迁移;需区分两类 schema 变更,避免模型与实际索引漂移。

概念解释

  • ORM 迁移:业务表、字段、普通索引与关联键。
  • 向量库 schema:集合、标量字段、向量索引,由向量库侧工具或入库流程管理。
  • 漂移风险:ORM 模型与向量 metadata 字段不一致导致过滤失效。

原理流程

业务字段变更 → ORM 迁移 → 向量 metadata 字段同步评估 → 向量库 schema 变更
   → 两侧对账字段一致性

代码 / 命令

# 检查:迁移只包含业务表结构;向量集合 / 索引变更有独立脚本或流程
# 待确认:所用向量库是否提供迁移 / 建集合工具,以官方文档为准

常见误区

  • 误区:Django 迁移能自动建向量库集合。正解:迁移只管关系库,向量库 schema 需单独管理。
  • 误区:模型加字段就自动同步到向量 metadata。正解:两侧需显式同步并对账。

追问

  • 问:metadata 字段变更怎么落地?答:先改向量库 schema,再清洗存量数据,最后调整写入代码。
  • 问:迁移怎么避免破坏线上?答:先在预发验证迁移与回滚,大表变更分批执行。

05.6.11.4-011 ORM 模型字段与向量库 metadata 如何映射?

频率 ★★★☆☆ | 难度 进阶

一句话结论

ORM 模型中的可过滤、可回溯字段同步到向量 metadata,字段类型与命名保持一致;敏感与大字段不进入 metadata,映射关系在服务层显式维护。

概念解释

  • 映射范围:文档 id、租户、来源、状态、时间等标量字段。
  • 类型一致:同字段在两侧类型统一,避免过滤不命中。
  • 排除项:长正文、敏感信息、嵌套对象不直接写入 metadata。

原理流程

ORM 记录 → 服务层选取映射字段 → 构造 Document.metadata → 写入向量库
   → 检索回填 → 与 ORM 记录核对一致

代码 / 命令

# 映射示例:id → doc_id;tenant → tenant;source → source;updated_at → updated_at
# 校验:写入前字段类型与向量库 schema 一致

常见误区

  • 误区:把 ORM 整行序列化进 metadata。正解:只映射检索与回溯所需轻量字段。
  • 误区:字段改名后两侧自动跟随。正解:映射需同步修改并回归过滤查询。

追问

  • 问:关联对象怎么映射?答:拆成标量冗余字段或存关联 id,不存嵌套对象。
  • 问:存量映射不一致怎么修?答:按目标 schema 清洗重建,抽样核对过滤命中。

05.6.11.4-012 DRF 检索接口的请求参数与返回结构怎么设计?

频率 ★★★★☆ | 难度 进阶

一句话结论

接口显式定义查询文本、topK、过滤条件与可选分数返回,响应结构化包含命中文档、metadata、分数与兜底标识;参数做类型与范围校验。

概念解释

  • 请求:query、topK、filter 字段、可选阈值。
  • 响应:文档片段、来源 metadata、相关度分数、命中状态。
  • 校验:topK 上限、filter 白名单字段、文本长度限制。

原理流程

接收请求 → 校验参数与权限 → 调用检索服务 → 结构化组装响应 → 错误 / 兜底状态返回

代码 / 命令

# 响应字段:doc_id、title、content、metadata、score、hit_status
# 约束:topK 设上限;filter 字段走白名单;不返回敏感 metadata

常见误区

  • 误区:接口直接透传向量库原始返回。正解:应做结构封装与字段裁剪,隔离底层变更。
  • 误区:不限制 topK 与文本长度。正解:防止超大请求拖垮检索与上下文。

追问

  • 问:过滤条件怎么防注入?答:字段白名单 + 值类型校验,条件结构由服务层构造。
  • 问:空结果怎么返回?答:明确空状态标识与提示,不返回伪造上下文。

05.6.11.4-013 流式返回与检索结果逐步下发的边界是什么?

频率 ★★★☆☆ | 难度 基础

一句话结论

流式通常用于生成阶段逐步输出;检索结果一般先取回再组装,需要流式下发时按候选批次推送,并控制断开与异常处理。

概念解释

  • 检索阶段:候选需经排序 / 过滤,整体取回更可控。
  • 生成阶段:模型输出可逐段流式返回。
  • 边界:流式响应要处理客户端断开、下游超时与部分结果一致性。

原理流程

检索取回候选 → 组装 Prompt → 生成流式输出 → 逐段下发
   → 异常 / 断开时终止流并记录

代码 / 命令

# 注意:流式响应超时、断开清理与错误帧要有定义
# 待确认:所用框架流式响应实现方式以官方文档为准

常见误区

  • 误区:检索也必须逐条流式推送。正解:候选排序需要完整集合,逐条推送难以保证质量。
  • 误区:流式响应无需处理客户端断开。正解:断开后要停止下游调用并释放资源。

追问

  • 问:流式中途下游失败怎么办?答:返回错误帧或收尾提示,记录失败环节,不留下半残连接。
  • 问:流式如何保留来源标注?答:在首段或结束帧附带引用来源,与生成正文区分。

05.6.11.4-014 限流:按接口与租户的限速方案怎么设计?

频率 ★★★★☆ | 难度 进阶

一句话结论

限流按接口与租户维度配置配额,超出限制拒绝或排队,保护向量库与 Embedding 不被突发流量打穿;限流阈值与下游承载匹配。

概念解释

  • 维度:接口、租户 / 用户、模型调用。
  • 算法:固定窗口 / 滑动窗口 / 令牌桶,按业务选择。
  • 配合:客户端超时、重试退避、降级开关。

原理流程

请求进入 → 识别身份与接口 → 配额计数 → 未超限放行 → 超限拒绝 / 排队
   → 限流事件记录监控

代码 / 命令

# 配额核对:检索 QPS、Embedding 调用量与下游上限匹配
# 记录:被限流请求、租户、接口、时间

常见误区

  • 误区:只在网关限流,服务内不限。正解:服务内也要兜底限流,防止内部调用突发。
  • 误区:限流阈值越高越好。正解:阈值超过下游承载会把压力传导到向量库。

追问

  • 问:Embedding 限流怎么单独控?答:按模型 / 租户设独立配额,与检索配额分开统计。
  • 问:被限流后客户端怎么表现?答:返回明确限流状态,客户端退避重试,不立即重打。

05.6.11.4-015 超时设置:客户端超时与接口超时如何配合?

频率 ★★★★☆ | 难度 基础

一句话结论

超时分层设置:客户端连接 / 请求超时小于接口总超时,检索环节预留组装与生成时间;超时立即释放资源,不无限等待下游。

概念解释

  • 层级:连接超时、检索请求超时、接口总超时逐级收紧。
  • 预留:检索之外的组装、生成时间要计入接口预算。
  • 释放:超时后取消等待,归还连接与任务槽。

原理流程

接口总预算 → 分配检索超时 → 客户端超时小于检索超时 → 超时取消调用 → 走降级

代码 / 命令

# 配置:连接超时、请求超时、接口总时长分开设置
# 记录:超时环节、下游耗时、错误类型

常见误区

  • 误区:客户端超时设长就不会超时。正解:过长堆积请求拖垮下游与线程池。
  • 误区:只设接口超时不管客户端。正解:客户端不超时会挂住连接资源。

追问

  • 问:检索慢但接口预算够怎么办?答:先看慢在连接、召回还是下游排序,再决定调参或扩容。
  • 问:超时后重试吗?答:可重试错误按策略退避重试,接口层避免叠加长等待。

05.6.11.4-016 重试策略:幂等键与退避如何设计?

频率 ★★★☆☆ | 难度 基础

一句话结论

重试只针对可重试错误,带次数上限与指数退避;写入与检索按幂等键处理,重复执行不产生重复向量或错误结果。

概念解释

  • 可重试:网络抖动、临时限流、瞬时超时。
  • 不可重试:参数错误、权限失败、数据校验失败。
  • 幂等:写入按文档 id 覆盖;检索本身天然幂等。

原理流程

调用失败 → 错误分类 → 可重试则退避等待 → 限次重试 → 仍失败隔离 / 降级

代码 / 命令

# 配置:最大重试次数、退避间隔、抖动、错误白名单
# 幂等键:doc_id;重复写入走覆盖 / upsert 语义

常见误区

  • 误区:所有错误都重试三次。正解:不可重试错误反复重试只会放大压力。
  • 误区:重试不需要退避。正解:固定间隔重打会加剧下游抖动。

追问

  • 问:重试如何避免重复 Embedding 写入?答:Embedding 结果按文本哈希缓存,写入按 id 幂等覆盖。
  • 问:重试风暴怎么识别?答:错误率与下游负载同时上升,需收紧重试与限流。

05.6.11.4-017 Embedding 调用与向量库写入的顺序与失败补偿是什么?

频率 ★★★★★ | 难度 高级

一句话结论

先批量计算 Embedding 再写入向量库,两步都要记录状态;Embedding 失败不写入,写入失败可凭已算向量或文本重试,避免半批脏数据。

概念解释

  • 顺序:文本校验 → 批量向量化 → 维度校验 → 写入。
  • 失败点:模型限流 / 超时、向量库写入失败。
  • 补偿:失败条目隔离重试,已算向量可缓存复用。

原理流程

文本清洗 → 批量 Embedding → 校验向量非空与维度 → 批量写入
   → 失败记录原因 → 退避重试 / 隔离队列

代码 / 命令

# 记录:批次、文本标识、向量状态、写入状态、失败原因
# 校验:空文本过滤;向量长度与集合维度一致

常见误区

  • 误区:Embedding 与写入混在一步失败后整批丢弃。正解:区分两步状态,定位失败环节分别补偿。
  • 误区:部分向量写入成功即可。正解:需按返回 id 对账,缺失条目补写,避免残缺批次。

追问

  • 问:模型 429 限流怎么处理?答:退避降速、缩小批大小,Embedding 结果缓存后再重试写入。
  • 问:怎么防止脏向量入库?答:写入前非空与维度校验,失败隔离不进集合。

05.6.11.4-018 先写业务库还是先写向量库:一致性取舍怎么定?

频率 ★★★☆☆ | 难度 高级

一句话结论

业务库作为权威数据源先落库,向量库作为派生索引在提交后同步写入;一致性靠幂等、重试与对账补偿,按业务容忍窗口选择同步或异步。

概念解释

  • 权威源:业务库保存完整记录与状态。
  • 派生索引:向量库可从业务库重建。
  • 窗口:同步写入缩短可见延迟,异步写入降低在线耦合。

原理流程

写业务库提交 → 触发向量写入(同步等待 / 异步事件)→ 幂等写入
   → 记录同步状态 → 对账发现差异补偿

代码 / 命令

# 顺序原则:业务库先提交,向量库后写入
# 对账:业务有效文档集合与向量标识集合求差集,补偿缺失与残留

常见误区

  • 误区:先写向量库再写业务库。正解:会留下无主向量,下线清理困难。
  • 误区:跨库可以用本地事务保证。正解:两系统无统一事务,只能最终一致。

追问

  • 问:要求写后立即可搜怎么办?答:提交后同步等待向量写入确认,仍不纳入业务事务。
  • 问:异步同步失败怎么兜底?答:重试队列 + 定时对账 + 差异补偿,监控同步延迟。

05.6.11.4-019 错误处理与异常分类怎么做?

频率 ★★★☆☆ | 难度 基础

一句话结论

异常按连接、参数、写入、检索、下游限流分类,分别映射对外响应与内部处置;对外返回安全提示,细节进内部日志与指标。

概念解释

  • 类别:连接失败、参数校验、权限、写入失败、检索超时、限流。
  • 处置:可重试隔离、不可重试拒绝、降级兜底。
  • 输出:对外不暴露堆栈与内部地址。

原理流程

捕获异常 → 归类 → 映射错误码 / 兜底响应 → 记录日志指标 → 触发对应处置

代码 / 命令

# 分类记录:错误类型、环节、请求标识、下游错误码
# 对外:通用提示 + 错误标识;内部日志保留细节

常见误区

  • 误区:所有异常返回 500。正解:参数与权限类错误应返回对应客户端错误状态。
  • 误区:异常信息直接抛给前端。正解:避免泄露内部实现、地址与堆栈。

追问

  • 问:连接失败怎么快速验证?答:运行环境直连端点做小请求,区分网络、凭据与服务端问题。
  • 问:部分写入失败怎么对账?答:按返回 id 与入参比对,缺失条目进补写批次。

05.6.11.4-020 降级:检索失败时的兜底策略是什么?

频率 ★★★☆☆ | 难度 进阶

一句话结论

检索不可用时逐级降级:放宽参数、关闭重排、返回缓存或热门内容、明确无依据提示,保证主链路不被拖垮并记录降级事件。

概念解释

  • 层级:缩小候选、跳过重排、缓存兜底、静态内容、转人工 / 工单。
  • 保护目标:避免下游雪崩,保留基本可用。
  • 开关:降级策略可配置并定期演练。

原理流程

压力 / 故障触发 → 降级开关生效 → 逐级降级 → 恢复后逐级放开 → 记录降级事件

代码 / 命令

# 客户端配合:超时 + 熔断 + 退避重试
# 兜底结果:缓存答案、热门文档、无依据提示、工单入口

常见误区

  • 误区:检索失败就让模型自由回答。正解:无检索依据的回答无法溯源,风险高。
  • 误区:只在服务端限流。正解:客户端重试不节制会放大压力,需两侧配合。

追问

  • 问:降级开关怎么验证有效?答:定期故障演练,确认降级路径真实生效。
  • 问:结果低分 / 空结果是否降级?答:先走兜底提示,不强行喂噪声上下文。

05.6.11.4-021 日志:请求 id、耗时与召回数记录什么?

频率 ★★★☆☆ | 难度 进阶

一句话结论

日志按请求贯穿检索链路,记录请求标识、各环节耗时、召回条数、分数分布与错误分类;查询原文做摘要脱敏,敏感字段不落盘。

概念解释

  • 字段:trace / 请求标识、环节、耗时、候选数、分数区间、错误类型。
  • 标签:场景、租户、模型版本、集合。
  • 脱敏:摘要化 query,不记录敏感 metadata。

原理流程

请求进入生成标识 → 各环节打点 → 检索结果记录条数与分数 → 异常记录分类 → 汇总日志

代码 / 命令

# 日志字段:request_id、stage、latency、hit_count、score 分布、error、tenant
# 禁止:凭据、原文敏感内容、内部完整地址

常见误区

  • 误区:日志只记成功失败。正解:空结果与低分结果是质量信号,需单独记录。
  • 误区:完整 query 与 metadata 全量落盘。正解:存在泄露与合规风险,需脱敏摘要。

追问

  • 问:怎么串起一次问答全链路?答:统一请求标识贯穿入库、检索、生成各环节日志。
  • 问:慢请求怎么复盘?答:保留摘要样本与各环节耗时,定位连接、召回或组装瓶颈。

05.6.11.4-022 指标:QPS、P99、错误率与队列水位怎么采?

频率 ★★★☆☆ | 难度 进阶

一句话结论

指标覆盖检索 QPS、延迟分布(P50/P99)、错误率、空结果率、连接池与任务队列水位,按场景与租户拆分上报。

概念解释

  • 流量指标:QPS、并发数、请求量。
  • 质量指标:召回条数、空结果率、低分占比。
  • 资源指标:连接池活跃 / 等待、队列水位、线程 / 协程数。

原理流程

链路打点 → 采集计数 / 耗时 / 水位 → 聚合到指标系统 → 看板与告警阈值

代码 / 命令

# 指标清单:检索 QPS、P99、错误率、空结果率、池水位、队列积压、Embedding 失败率
# 告警:延迟、错误率、队列积压超阈值触发通知

常见误区

  • 误区:只看平均延迟。正解:P99 反映尾部体验,需单独监控。
  • 误区:队列积压不需要告警。正解:积压是入库滞后与检索缺文档的前兆。

追问

  • 问:指标按什么维度拆?答:至少按接口、租户、集合拆分,避免平均掩盖个别问题。
  • 问:入库延迟怎么度量?答:记录文档产生时间与可检索时间差,监控同步窗口。

05.6.11.4-023 链路追踪 trace 如何透传?

频率 ★★★☆☆ | 难度 高级

一句话结论

trace 标识在请求入口生成,贯穿检索、重排、生成与后台入库任务,跨客户端调用时透传上下文,便于串联各环节定位慢与错。

概念解释

  • 透传:标识与上下文随请求 / 任务传递到下游客户端。
  • 分段:检索、组装、生成各环节作为独立跨度记录。
  • 关联:在线请求与触发的异步入库任务通过标识关联。

原理流程

入口生成 trace 标识 → 注入客户端调用上下文 → 各环节记录跨度
   → 异步任务继承标识 → 追踪系统汇总链路

代码 / 命令

# 检查:客户端调用是否携带 trace 上下文;异步任务是否继承标识
# 待确认:所用 SDK 与观测库的 trace 接入方式以官方文档为准

常见误区

  • 误区:后台任务不需要 trace。正解:入库失败难追溯,必须关联来源请求与文档标识。
  • 误区:日志有请求号就等于有 trace。正解:还需下游跨度串联,才能看各环节耗时。

追问

  • 问:跨进程调用怎么透传?答:标识放入请求头 / 消息属性,下游继续延续跨度。
  • 问:trace 采样怎么配?答:错误与慢请求全量保留,正常流量按比例采样。

05.6.11.4-024 压测方法:数据集、并发阶梯与指标口径怎么做?

频率 ★★★★☆ | 难度 高级

一句话结论

压测使用贴近真实分布的数据集,按并发阶梯加压,记录 P50/P99、错误率、资源水位与下游配额,找到容量瓶颈与安全水位。

概念解释

  • 数据集:规模、维度、查询分布与真实语料一致。
  • 阶梯:并发从低到高逐级加压,观察拐点。
  • 口径:延迟分位、错误率、召回质量、资源占用统一记录。

原理流程

构造数据集 → 阶梯并发 → 采集延迟 / 错误 / 资源 → 定位瓶颈 → 调参回归 → 定容量基线

代码 / 命令

# 观测:检索 P99、错误率、连接池 / 队列水位、CPU 内存、下游限流计数
# 标准:目标 QPS 下 P99 达标、资源有余量、无错误率上升

常见误区

  • 误区:用随机向量或固定几条查询压测。正解:分布不符则结论不可靠。
  • 误区:压测只看吞吐。正解:吞吐上升伴随 P99 恶化时,已超出安全水位。

追问

  • 问:入库链路怎么压测?答:批量导入速率、Embedding 吞吐与写入失败率分开压,错峰验证。
  • 问:瓶颈怎么定位?答:拆分客户端等待、向量库召回、应用组装各段耗时,对照资源指标。

05.6.11.4-025 向量库客户端在 Django 启动期如何初始化?

频率 ★★★☆☆ | 难度 进阶

一句话结论

客户端在应用启动钩子中按配置初始化并注册复用实例,启动期校验连通性与必填配置,关闭时释放连接;不在请求视图内新建。

概念解释

  • 初始化:配置加载、客户端构造、连接池建立。
  • 校验:必填项、端点、模型与维度一致性。
  • 释放:关闭钩子中关闭客户端,避免连接泄漏。

原理流程

应用启动 → 读取配置 → 构造客户端并注册 → 校验连通 → 请求复用 → 关闭释放

代码 / 命令

# 检查:初始化失败是否阻断启动;客户端是否全局复用;关闭是否释放资源
# 待确认:Django 启动钩子与客户端生命周期写法以官方文档为准

常见误区

  • 误区:首次请求时懒加载客户端。正解:启动期初始化可提前暴露配置与连接问题。
  • 误区:每个请求构造新客户端。正解:连接池无法复用,快速耗尽连接。

追问

  • 问:多进程部署客户端怎么管理?答:每个进程独立初始化客户端与连接池,按进程数核对下游总连接。
  • 问:初始化慢会不会影响启动?答:可轻量探测连通,完整建连按客户端配置处理。

05.6.11.4-026 Django 队列任务如何做离线入库?

频率 ★★★☆☆ | 难度 进阶

一句话结论

离线入库交给任务队列异步执行,任务带文档标识与状态,支持重试与对账;在线请求只提交任务,不等待批量向量化完成。

概念解释

  • 队列职责:切块、Embedding、批量写入、状态更新。
  • 状态:待处理、处理中、成功、失败,可追踪。
  • 对账:定时扫描失败与缺失文档补偿。

原理流程

业务记录变更 → 提交入库任务到队列 → Worker 执行切块 / 向量化 / 写入
   → 更新状态 → 对账任务补偿差异

代码 / 命令

# 任务记录:文档 id、版本、状态、重试次数、失败原因
# 待确认:队列选型与任务接口以所用任务系统官方文档为准

常见误区

  • 误区:请求内同步等待大批量入库。正解:阻塞在线响应,应走队列异步处理。
  • 误区:任务失败无重试无记录。正解:需状态留痕与对账兜底。

追问

  • 问:重复入队怎么防重?答:按文档 id 幂等,处理中加锁 / 状态判断,避免并发重复写入。
  • 问:Worker 并发怎么控?答:按 Embedding 与向量库配额设并发,队列积压时扩容或限速。

05.6.11.4-027 检索结果缓存的取舍是什么?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

热门重复问题可缓存检索结果降低重复开销,但要按查询与过滤条件组键,设置 TTL 并在文档更新后失效,避免返回陈旧上下文。

概念解释

  • 收益:减少重复 Embedding 与检索调用,缩短延迟。
  • 风险:文档变更后缓存陈旧;多租户结果不可混存。
  • 要点:缓存键包含查询、过滤、租户与模型 / 集合标识。

原理流程

组合缓存键 → 命中返回 → 未命中检索后写入 → 文档更新失效相关条目 → TTL 兜底

代码 / 命令

# 缓存键:查询归一化 + filter + 租户 + 模型 / 集合标识
# 失效:文档更新删除相关条目;热点键互斥重建防击穿

常见误区

  • 误区:缓存只按问题文本。正解:过滤与租户不同结果不同,必须纳入键。
  • 误区:缓存永久有效。正解:语料变更后陈旧缓存污染回答。

追问

  • 问:缓存粒度怎么选?答:热门重复问题命中缓存,长尾问题直接检索。
  • 问:缓存与最新一致性冲突时怎么办?答:高一致场景缩短 TTL 或写后主动失效。

05.6.11.4-028 metadata 过滤参数如何校验?

频率 ★★☆☆☆ | 难度 基础

一句话结论

过滤字段走白名单,值按类型校验,条件结构由服务层构造;不接受任意字段名与原生表达式,防止越权过滤与注入。

概念解释

  • 白名单:允许过滤的字段清单。
  • 类型:字段值类型与 schema 一致。
  • 强制:租户等权限条件由服务层注入,不接受客户端传入覆盖。

原理流程

接收过滤参数 → 字段白名单校验 → 值类型校验 → 服务层合并强制条件 → 调用检索

代码 / 命令

# 校验:字段在白名单内;值类型匹配;权限条件服务端注入
# 拒绝:未知字段、类型不符、原生表达式拼接

常见误区

  • 误区:客户端传什么字段就过滤什么。正解:非白名单字段拒绝,避免暴露内部 schema。
  • 误区:租户条件由前端传入。正解:权限范围必须服务端按身份注入。

追问

  • 问:范围 / 包含条件怎么校验?答:操作符白名单 + 边界值类型校验,参数化传入底层。
  • 问:过滤字段变更怎么同步?答:白名单与底层 schema 一起更新并回归用例。

05.6.11.4-029 敏感信息与凭据如何管理?

频率 ★★★☆☆ | 难度 基础

一句话结论

凭据从环境变量或配置中心注入,不写进代码与仓库;分环境最小权限,日志与错误信息中不泄露密钥。

概念解释

  • 管理项:api key、令牌、连接密码。
  • 原则:最小权限、分环境、可轮换。
  • 防护:异常日志只记连接标识,不打印凭据。

原理流程

凭据注入运行环境 → 客户端构造读取 → 运行期使用 → 轮换更新配置

代码 / 命令

# 禁止入库:密钥、令牌、内部地址
# 检查:错误堆栈与日志不输出鉴权信息

常见误区

  • 误区:代码留默认密钥兜底。正解:缺失配置应启动失败,不提供硬编码默认密钥。
  • 误区:测试配置复制生产 key。正解:凭据混用扩大泄露面。

追问

  • 问:密钥轮换怎么衔接?答:客户端支持刷新或滚动重启更新,兼容窗口按 SDK 说明确认。
  • 问:疑似泄露如何止损?答:立即轮换、排查使用范围、审计访问记录。

05.6.11.4-030 多环境配置如何区分?

频率 ★★☆☆☆ | 难度 基础

一句话结论

环境差异通过配置模板与环境变量注入解决,代码保持中性;开发、预发、生产使用独立集合与凭据,测试数据不复制到生产。

概念解释

  • 隔离项:端点、集合名、凭据、超时与批参数。
  • 原则:代码不写环境特定值,配置可渲染。
  • 数据:生产数据不进测试环境,样本脱敏。

原理流程

配置模板 → 各环境渲染 → 独立装配 → 独立监控配额 → 变更走评审

代码 / 命令

# 检查:生产凭据不出现在测试配置;集合命名带环境标识避免误连

常见误区

  • 误区:共用配置只改集合名。正解:凭据、网络与配额也需隔离。
  • 误区:本地配置指向生产便于调试。正解:存在误写误删风险,应本地隔离。

追问

  • 问:如何防止误连生产?答:网络隔离 + 凭据分离 + 启动期环境标识校验。
  • 问:配置变更怎么回滚?答:配置版本化管理,保留上一可用版本。

05.6.11.4-031 常见坑:事件循环里跑阻塞 Embedding 调用怎么识别?

频率 ★★★☆☆ | 难度 高级

一句话结论

协程内同步调用 Embedding 模型会阻塞事件循环,表现为多个无关请求同时变慢;识别后改异步调用或移入线程池,并控制并发。

概念解释

  • 信号:循环线程占满、请求排队、Embedding 等待期间其他请求停滞。
  • 根因:同步阻塞调用占住循环。
  • 解法:异步客户端或线程池隔离。

原理流程

延迟抖动 → 定位 Embedding 调用是否阻塞 → 切换异步 / 线程池 → 压测回归

代码 / 命令

# 检查:异步函数内同步模型调用、同步 HTTP 客户端
# 处置:阻塞计算隔离执行,Embedding 批量走受控并发

常见误区

  • 误区:Embedding 调用很快不需要关注。正解:模型远程调用耗时可观,阻塞影响全循环。
  • 误区:在线请求里批量向量化大段文本。正解:批量入库向量化应离线异步完成。

追问

  • 问:查询向量化必须在线做吗?答:查询文本需要实时向量化,但其调用要非阻塞或受控隔离。
  • 问:线程池跑模型调用有什么风险?答:受模型配额与并发限制,需限流与退避配合。

05.6.11.4-032 常见坑:请求结束关闭连接池导致后续失败怎么避免?

频率 ★★☆☆☆ | 难度 基础

一句话结论

连接池随客户端生命周期复用,请求结束只释放借用的连接而不关闭池;误在请求级关闭会导致后续请求拿不到连接。

概念解释

  • 正确生命周期:启动建池,进程关闭才销毁。
  • 请求级:获取连接 → 使用 → 归还,不关闭池。
  • 风险:重复建池 / 关池耗尽连接与文件描述符。

原理流程

启动建池注册 → 请求借用连接 → 使用后归还 → 后续请求复用 → 关闭时销毁池

代码 / 命令

# 检查:关闭逻辑是否挂在应用关闭钩子,而非请求结束
# 核对:客户端是否被复用为同一实例

常见误区

  • 误区:响应结束就关闭客户端释放资源。正解:关闭池会影响后续所有请求。
  • 误区:连接归还等于关闭连接。正解:归还由池管理复用,不等于销毁。

追问

  • 问:连接泄漏怎么排查?答:看池活跃数只增不减,定位未归还的调用路径。
  • 问:多进程部署池怎么算总量?答:进程数 × 每进程池大小,不超过下游连接配额。

05.6.11.4-033 常见坑:批量入库一条失败导致整批回滚怎么办?

频率 ★★★☆☆ | 难度 进阶

一句话结论

批量写入应支持部分成功:按返回 id 对账,失败条目隔离重试,避免单条问题拖垮整批;写入按幂等键覆盖,重试不产生重复。

概念解释

  • 部分成功:底层批量接口可能部分条目写入成功。
  • 对账:返回 id 与入参比对,定位缺失条目。
  • 重试:小批 / 单条重试,记录失败原因。

原理流程

批量提交 → 收集返回 id → 比对入参 → 成功登记 / 失败隔离 → 退避重试 → 对账复核

代码 / 命令

# 台账:批次条目、成功 id、失败标识、失败原因、重试次数
# 幂等:doc_id 覆盖写入,重复重试安全

常见误区

  • 误区:整批要么全成功要么全丢弃。正解:应保留成功部分,只补偿失败条目。
  • 误区:失败后整批重跑。正解:造成重复写入与 Embedding 浪费,应精准补偿。

追问

  • 问:哪些失败不可重试?答:维度不符、字段类型错误等数据问题,需修复数据后再写入。
  • 问:怎么监控批量成功率?答:按批次统计成功 / 失败条数,失败率超阈值告警。

05.6.11.4-034 常见坑:迁移手工建索引与 ORM 模型漂移怎么发现?

频率 ★★★☆☆ | 难度 高级

一句话结论

手工维护的向量索引 / 字段与 ORM 模型逐渐漂移,表现为过滤字段缺失、类型不符;需对账两侧 schema 并将变更纳入版本化流程。

概念解释

  • 漂移来源:手工改库、模型变更未同步、多环境不一致。
  • 发现:抽样过滤查询失效、字段类型报错、模型与库结构对比差异。
  • 治理:schema 变更流程化,两侧字段映射有清单。

原理流程

模型变更 → 检查向量 metadata 映射 → 同步向量库 schema → 对账字段
   → 校验过滤查询命中 → 记录版本

代码 / 命令

# 对账:ORM 字段清单 vs 向量库 metadata 字段清单,比对类型与可过滤性
# 变更:先改 schema 再改代码,避免新字段写入无映射

常见误区

  • 误区:上线后人工补索引即可。正解:无流程约束容易再次漂移,需版本化与对账。
  • 误区:过滤失效是向量质量问题。正解:先排除 schema 漂移与字段类型问题。

追问

  • 问:存量数据类型不一致怎么清洗?答:按目标 schema 转换,必要时重建集合与索引。
  • 问:多环境怎么保证一致?答:schema 变更脚本纳入版本管理,预发先验证再推广。

05.6.11.4-035 常见坑:DRF 返回大段文本未做长度限制有什么问题?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

返回片段长度与结果条数不限制会放大响应体积、拖慢序列化与传输;接口应对单块长度、topK 与上下文总长度设上限并裁剪。

概念解释

  • 风险:大响应占用带宽与内存,客户端解析变慢。
  • 限制:topK 上限、单片段长度、返回总字符 / token 预算。
  • 裁剪:超长片段按规则截断并标注,不破坏关键信息。

原理流程

检索候选 → 条数与长度校验 → 超长裁剪 / 摘要 → 结构化响应 → 体积监控

代码 / 命令

# 限制:topK 上限、单 content 长度、响应总预算
# 记录:响应体积分布,异常大响应告警

常见误区

  • 误区:原文多长就返回多长。正解:接口应限制返回体量,展示层按需取完整原文。
  • 误区:截断不需要标注。正解:截断内容应标识,避免误认为完整片段。

追问

  • 问:需要完整原文怎么办?答:列表返回摘要与来源,详情按 doc_id 二次获取。
  • 问:响应体积怎么观测?答:记录响应大小分布,定位大文档与异常查询。

05.6.11.4-036 常见坑:无限重试放大故障怎么避免?

频率 ★★★☆☆ | 难度 高级

一句话结论

重试必须有次数上限、退避间隔与错误白名单,配合限流与熔断;下游故障时无节制重试会形成重试风暴,进一步压垮服务端。

概念解释

  • 上限:最大重试次数,超过进入隔离 / 降级。
  • 退避:指数间隔加抖动,避免同步重打。
  • 熔断:连续失败时短期停止重试,直接降级。

原理流程

失败分类 → 可重试错误 → 限次退避重试 → 熔断打开 → 降级返回 → 半开探测恢复

代码 / 命令

# 配置:重试次数、退避基数、抖动、熔断阈值、错误白名单
# 监控:重试次数占比、熔断状态、下游错误率

常见误区

  • 误区:重试次数越多越可靠。正解:故障期重试放大流量,应快速失败降级。
  • 误区:所有客户端各自重试无全局控制。正解:需在服务端限流与客户端退避之间配合。

追问

  • 问:怎么识别重试风暴?答:下游错误率未降而请求量激增,重试占比升高。
  • 问:检索重试返回旧候选怎么办?答:接受结果不确定性,超时走降级而非反复等待。

05.6.11.4-037 常见坑:Embedding 模型限流未识别导致 429 雪崩怎么处理?

频率 ★★★☆☆ | 难度 高级

一句话结论

Embedding 调用受模型配额限制,未识别 429 会持续重打放大故障;应按 429 退避降速、缩小批大小、隔离批量任务并监控配额。

概念解释

  • 信号:429 / 限流错误码、Embedding 失败率上升、批量任务积压。
  • 处置:退避重试、降并发、减批大小,在线与离线配额分开。
  • 预防:压测确认配额上限,入库任务限速错峰。

原理流程

收到限流错误 → 退避等待 → 降低并发 / 批大小 → 隔离批量任务
   → 监控配额恢复 → 逐步放开

代码 / 命令

# 配置:Embedding 并发上限、批大小、429 退避策略
# 记录:限流次数、配额余量、积压任务数

常见误区

  • 误区:429 当作普通失败立即重试。正解:限流需按响应头 / 策略退避,不能立刻重打。
  • 误区:在线检索与离线入库共用 Embedding 配额。正解:应分开配额,离线任务不得挤占在线。

追问

  • 问:配额不足怎么扩容?答:评估模型服务配额提升或拆分调用,离线任务错峰执行。
  • 问:Embedding 缓存怎么缓解?答:按文本哈希缓存向量,重复文本不重复调用模型。

05.6.11.4-038 常见坑:Django 同步视图混用异步客户端怎么处理?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

同步视图中不能直接 await 异步客户端;要么使用同步 SDK 客户端,要么在异步视图中调用异步客户端,混用会导致事件循环错误或阻塞。

概念解释

  • 匹配原则:同步视图配同步客户端,异步视图配异步客户端。
  • 常见错误:循环未运行、事件循环冲突、协程未等待。
  • 隔离:同步 SDK 在同步环境运行,不强行包装协程。

原理流程

确定视图类型 → 选择对应客户端 → 同步环境用同步调用 / 异步环境 await
   → 避免循环混用 → 测试覆盖两种链路

代码 / 命令

# 检查:同步函数内是否出现 await;异步函数内是否调用阻塞同步 SDK
# 待确认:所用向量库 SDK 的同步 / 异步接口以官方仓库为准

常见误区

  • 误区:同步视图里新建事件循环跑异步客户端。正解:嵌套循环易出问题,应换同步客户端。
  • 误区:异步客户端返回的协程不等待。正解:未 await 的协程不会执行并产生告警。

追问

  • 问:老项目同步视图想接入异步 SDK 怎么办?答:评估迁移到异步视图,或保持同步客户端,不做半吊子混用。
  • 问:怎么测试两种环境?答:同步与异步链路各跑检索用例,覆盖正常与超时路径。

05.6.11.4-039 常见坑:检索结果未做分数阈值过滤有什么问题?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

不过滤低相关候选会把噪声上下文送入生成,拉低回答质量;应按度量方向设置阈值,用样本分布标定并记录被过滤比例。

概念解释

  • 方向:相似度取下限,距离取上限,先确认度量类型。
  • 标定:正例 / 负例样本确定阈值区间。
  • 监控:被过滤条数与空结果率定期复核。

原理流程

检索带分数候选 → 按度量方向比较阈值 → 保留达标候选 → 不足走兜底 → 记录分布

代码 / 命令

# 先确认度量类型与归一化口径,再设阈值
# 记录:候选数、达标数、过滤比例、分数分布

常见误区

  • 误区:所有分数口径一致可套用阈值。正解:模型 / 库变化后分布重排,阈值需重新标定。
  • 误区:阈值越高越好。正解:过严导致空结果率上升,可用信息被误杀。

追问

  • 问:阈值过滤后为空怎么办?答:降级放宽阈值或返回无依据提示,不硬塞低分块。
  • 问:分数分布异常集中怎么排查?答:检查向量归一化、模型一致性与查询文档分布。

05.6.11.4-040 常见坑:后台任务失败不可见、无重试记录怎么补救?

频率 ★★★☆☆ | 难度 进阶

一句话结论

入库后台任务必须持久化状态与失败原因,支持重试次数追踪;不可见的失败表现为线上缺文档,需补状态台账与对账补偿。

概念解释

  • 状态:待处理、处理中、成功、失败、隔离。
  • 记录:失败原因、重试次数、发生时间、文档标识。
  • 补偿:对账任务扫描失败与缺失,重新入队。

原理流程

任务执行 → 状态落库 → 失败记录原因与次数 → 重试队列再处理
   → 对账扫描差异 → 补偿入库

代码 / 命令

# 台账字段:task_id、doc_id、status、retry_count、error、updated_at
# 告警:失败任务积压、长期未成功文档

常见误区

  • 误区:进程内任务丢了无所谓。正解:关键入库需持久化队列与状态,重启不丢失。
  • 误区:失败只打一条日志。正解:无状态台账则无法补偿与统计失败率。

追问

  • 问:任务卡住怎么发现?答:处理中超时未完成的任务标记超时,重新入队并加并发控制。
  • 问:如何保证最终一致?答:定时对账业务库与向量库差异,补偿遗漏与残留。

05.6.11.4-041 多租户在接口层如何强制过滤?

频率 ★★★☆☆ | 难度 高级

一句话结论

租户范围由服务端按身份注入检索条件,不接受前端传入;跨租户数据在检索层隔离,权限校验先于向量检索执行。

概念解释

  • 强制条件:租户标识作为必填 filter 注入。
  • 隔离层级:独立集合 / 命名空间或共享集合加租户过滤。
  • 校验:路由前确认用户对目标租户的访问权。

原理流程

身份解析 → 校验租户访问权 → 服务端注入租户 filter → 检索 → 结果不含跨租户候选

代码 / 命令

# 禁止:客户端传 tenant 直接作为过滤条件
# 记录:检索使用的租户范围与权限校验结果

常见误区

  • 误区:结果返回前剔除跨租户数据即可。正解:检索层不带条件会先召回其他租户候选,存在泄露面。
  • 误区:共享集合靠前端隐藏入口隔离。正解:必须服务端强制过滤。

追问

  • 问:大租户怎么隔离?答:独立集合 / 后端实例,单独配额与监控。
  • 问:租户数据迁移怎么做?答:按租户维度导出重建,双写对账后切流。

05.6.11.4-042 灰度切流:新旧向量库双写怎么做?

频率 ★★★☆☆ | 难度 高级

一句话结论

灰度期间新旧两套存储双写,按租户或比例路由检索,影子读对比召回结果,验证达标后逐步切流,旧数据保留至稳定再清理。

概念解释

  • 双写:新文档同时写新旧存储,按文档标识幂等。
  • 路由:在线检索按规则走新 / 旧 / 影子对比。
  • 回滚:旧存储与配置保留观察周期。

原理流程

新库建集合 → 增量双写 / 历史重建 → 影子读对比 → 按比例切流
   → 指标观察 → 全量切换 → 清理旧库

代码 / 命令

# 记录:写入实例、读取实例、版本标识、对比指标
# 对账:新旧两侧文档数量与版本一致

常见误区

  • 误区:双写只写增量不迁历史。正解:旧存量需重建到新库,否则切流后召回缺失。
  • 误区:只看成功率判断灰度。正解:检索质量差异不一定报错,需对比召回与排序。

追问

  • 问:双写不一致怎么发现?答:对账两侧标识集合与版本 hash,差异告警补偿。
  • 问:切流指标看什么?答:召回命中、排序质量、P99 延迟、错误率与 Embedding 成本。

05.6.11.4-043 与对象存储、文件解析服务如何衔接?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

文件先入对象存储留存原件,解析服务提取文本与结构,再进入切块与向量化链路;各环节记录来源标识,支持回溯与重新解析。

概念解释

  • 存储:原件保留在对象存储,向量库存片段与向量。
  • 解析:文档转文本,保留标题、段落等结构信息。
  • 回溯:命中结果可凭来源标识取原件与章节。

原理流程

文件上传对象存储 → 解析提取文本结构 → 切块向量化入库
   → 检索命中 → 凭来源标识回溯原件 / 章节

代码 / 命令

# metadata 记录:文件标识、对象路径、章节位置、解析版本
# 重解析:解析器升级后可按文件标识重新切块入库

常见误区

  • 误区:解析文本丢弃原件。正解:原件留存便于回溯、重解析与审计。
  • 误区:解析失败不记录。正解:失败文件应进入重试队列,避免静默缺失。

追问

  • 问:解析版本升级怎么重建?答:按解析版本标识识别旧文档,批量重新解析入库。
  • 问:大文件怎么处理?答:流式解析分批切块,避免一次性加载全文到内存。

05.6.11.4-044 文档删除在向量库如何级联清理?

频率 ★★★☆☆ | 难度 基础

一句话结论

文档下线后按业务标识删除其全部向量片段,更新业务状态;对账复核残留命中,避免已下线内容继续被检索到。

概念解释

  • 定位:按 doc_id 查出关联片段 id。
  • 删除:调用向量库删除接口清理旧片段与映射。
  • 复核:对账扫描残留标识,补偿遗漏删除。

原理流程

业务标记下线 → 按 doc_id 查片段 → 删除向量与映射 → 更新状态
   → 对账扫描残留 → 补偿清理

代码 / 命令

# 删除记录:doc_id、删除时间、清理片段数
# 对账:业务已下线文档在向量库不应命中

常见误区

  • 误区:只删业务记录不删向量。正解:残留向量仍可被检索召回,造成内容泄露。
  • 误区:删除单片段就代表文档下线。正解:需清理该文档全部片段。

追问

  • 问:删除失败怎么补偿?答:记录失败文档进重试队列,对账任务二次发现残留并清理。
  • 问:软删除怎么处理?答:状态写入 metadata 过滤条件,检索排除未发布 / 已下线文档。

05.6.11.4-045 接口版本与检索参数兼容如何管理?

频率 ★★☆☆☆ | 难度 基础

一句话结论

接口与检索参数版本化演进,新增字段向后兼容,废弃参数保留过渡;参数变更与向量库 / 模型配置分开管理,避免老客户端被破坏。

概念解释

  • 兼容:新增参数给默认值,不改变老请求行为。
  • 废弃:参数标注过渡周期,响应中提示迁移。
  • 映射:外部参数到内部检索条件的转换集中在服务层。

原理流程

参数演进 → 兼容默认值 → 服务层映射内部条件 → 版本标识区分 → 老客户端过渡

代码 / 命令

# 检查:老版本请求在新接口下行为不变;废弃参数有迁移说明
# 记录:参数版本、默认值、变更时间

常见误区

  • 误区:直接改参数含义不做兼容。正解:老客户端可能依赖旧行为,需过渡方案。
  • 误区:外部参数直接透传底层库。正解:服务层做映射隔离,底层变更不影响接口。

追问

  • 问:检索条件下线怎么通知?答:响应或文档标注废弃,保留过渡期后移除。
  • 问:多版本并存怎么维护?答:接口层做参数适配,内部检索逻辑统一演进。

05.6.11.4-046 安全:输入注入与过滤条件转义如何防护?

频率 ★★★☆☆ | 难度 高级

一句话结论

查询文本与过滤参数做类型校验与白名单约束,条件结构由服务层构造,参数化传入底层库;不拼接原生查询表达式,防止条件注入与越权。

概念解释

  • 文本:长度与字符限制,模型侧提示注入另行评估。
  • 条件:字段白名单、操作符白名单、值类型校验。
  • 传参:使用 SDK 参数化接口,不拼接字符串表达式。

原理流程

接收输入 → 字段 / 操作符 / 类型校验 → 服务层构造条件结构 → 参数化调用底层库
   → 结果裁剪敏感字段

代码 / 命令

# 禁止:用户输入拼接进过滤表达式 / SQL 字符串
# 校验:filter 字段白名单、值类型、租户条件服务端注入

常见误区

  • 误区:底层库会自己转义。正解:拼接表达式仍可能绕过白名单,应结构化传参。
  • 误区:查询文本安全无需关注。正解:提示注入风险需在 Prompt 约束与输出校验中处理。

追问

  • 问:metadata 返回怎么防泄露?答:裁剪敏感字段,只返回展示与回溯所需信息。
  • 问:越权访问怎么测试?答:用不同身份账号交叉测试过滤结果与权限边界。

05.6.11.4-047 资源隔离:检索接口与入库任务的线程 / 连接配额如何划分?

频率 ★★★☆☆ | 难度 高级

一句话结论

在线检索与离线入库使用独立线程 / 协程池与连接配额,批量任务限速错峰,避免入库突发挤占在线请求资源。

概念解释

  • 隔离对象:检索调用、批量写入、Embedding 计算。
  • 配额:连接池、并发数、模型调用量分别核算。
  • 调度:离线任务错峰执行,队列积压时限速。

原理流程

划分在线 / 离线资源池 → 分别配连接与并发上限 → 离线任务限速排队
   → 监控两侧水位 → 超限降级保护在线

代码 / 命令

# 隔离项:线程 / 协程池、连接池、Embedding 配额、任务队列
# 观测:在线 P99 与离线水位分别监控

常见误区

  • 误区:在线与入库共用公共线程池。正解:批量任务会挤占在线请求线程。
  • 误区:离线任务可以无限速跑。正解:突发批量打满连接与模型配额,影响 SLA。

追问

  • 问:在线增量更新怎么兼顾?答:小批量增量走受控队列,大批量重建放离线窗口。
  • 问:资源紧张时优先保谁?答:优先保障在线检索配额,离线任务排队降级。

05.6.11.4-048 一套 FastAPI / Django RAG 后端接入清单是什么?

频率 ★★★★★ | 难度 高级

一句话结论

按「客户端生命周期与配置 → 在线检索链路 → 离线入库与对账 → 超时限流重试 → 观测评估 → 灰度兜底」推进,每步有验证指标与回滚路径。

概念解释

  • 输入:语料规模、语种、过滤与权限维度、QPS 与 SLA。
  • 关键决策:Embedding 模型、向量库、切块策略、检索参数、部署形态。
  • 交付物:客户端封装、检索接口、入库队列、对账任务、观测看板、降级与回滚方案。

原理流程

1) 梳理语料与 SLA   2) 初始化客户端与配置校验   3) 离线切块 / 向量化 / 批量入库
4) 在线检索接口:过滤、topK、超时限流   5) 接入日志指标 trace
6) 增量更新、删除与对账   7) 评估集回归与灰度切流   8) 备份回滚与成本监控

代码 / 命令

# 面试表达:先讲假设与规模 → 各环节选型理由 → 指标与验证方式 → 运维兜底
# 验收用例:写入、检索、过滤、删除、增量更新、空结果、超时降级 各跑通一条

常见误区

  • 误区:接入就是写通一个检索接口。正解:生命周期、批量、一致性、观测与兜底才是工程主体。
  • 误区:框架默认配置可直接上生产。正解:池大小、批大小、阈值与并发都需压测与样本验证。

追问

  • 问:上线后检索退化怎么响应?答:核查入库量、模型与配置变更,跑评估集回归,必要时回滚版本。
  • 问:成本怎么控制?答:监控 Embedding 调用量、向量存储与检索 QPS,离线任务错峰限速。

参考来源