97f2e4cb95
- B03：确定性段落聚合切片（窗计划哈希）、哈希bigram向量代次、reference_reading授权过滤、构建命令接口 - B09：场景检索入口与混合检索平行，两路等权，键带slice:前缀，v1不接偏好重排 - B06：参考材料两类载体（方法/片段），片段不登记方法消费，授权边界为来源用途+内容哈希 - B07：参考挑选反馈增语料类型字段，片段挑选只落账不进信号轨
119 lines
13 KiB
Markdown
119 lines
13 KiB
Markdown
<!-- 导航元信息: {"内容描述": "B09 上下文", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# B09 上下文
|
||
|
||
## 职责与对象
|
||
|
||
一次任务真正允许且实际使用的材料集合。
|
||
|
||
实例归属以[总体架构](../总体架构.md)为准；结构、状态和公开外壳分别引用数据模型与接口契约。
|
||
|
||
## 公开接口
|
||
|
||
| 用例 | 输入责任 | 输出与后果 |
|
||
|------|----------|------------|
|
||
| authorize_scope | 作者身份、任务目标、用途和选择 | 只能被收窄的读取范围 |
|
||
| search | 冻结范围和查询意图 | 合法候选及省略原因 |
|
||
| assemble | 必读、预算和固定绑定 | 角色所需材料 |
|
||
| freeze | 已执行探索、来源和投影 | 不可变快照和哈希 |
|
||
| replay | 快照、原读取身份和当前授权 | 可回读材料或明确失效 |
|
||
| check_dependencies | 来源、结构、策略和事务上下文 | 当前有效性及锁定依据 |
|
||
|
||
所有接口在本模块的接口.py 暴露。输入输出类型由同一公开表面导出，外部不导入私有模型或 SQL。
|
||
|
||
## 内部职责
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| 接口.py | 上下文公开用例和可导入合同 |
|
||
| 模型.py | 上下文稳定对象、外壳及内部状态 |
|
||
| 存储.py | 上下文快照、检索索引及台账的 SQL 与版本读写 |
|
||
| 任务范围.py | 作品、用途、时点和来源权限 |
|
||
| 来源读取.py | 按业务公开接口读取固定来源 |
|
||
| 声音材料.py | 经B06读取已认可声音，冻结身份/用途投影并核逐键材料 |
|
||
| 混合检索.py | 关键词与向量两路倒数排名融合及偏好重排 |
|
||
| 材料装配.py | 必读、预算、取舍及字段投影 |
|
||
| 探索回放.py | 按同一范围重放工具读取 |
|
||
| 冻结快照.py | 来源、结构、投影和消费片段 |
|
||
| 依赖校验.py | 授权、撤回、结构与数据版本变化 |
|
||
| 索引维护.py | 切块、嵌入、重建与陈旧拒绝 |
|
||
|
||
完整路径及运行模板见[目标文件清单](../项目目录与文件职责.md)。逐文件意图、边界与目标见[文件合同](../文件设计/后端-B09-上下文.md)。
|
||
|
||
## 当前检索底座
|
||
|
||
[基础设施向量评分](../../../../src/muse/基础设施/检索/向量.py)提供 Python 余弦相似打分，[混合检索](../../../../src/muse/上下文/混合检索.py)负责倒数排名融合。当前不依赖 pgvector 或外部嵌入服务；旧逐文件设计中的 pgvector 是历史目标，代码注释里的“裁决 A”因缺原文不作为现行决定依据。
|
||
|
||
## 实现约束
|
||
|
||
- 预组装、探索、回放和采纳复检使用一致范围，不能仅保护预组装。
|
||
- 来源数据经各业务公开接口取得，动态字段由 S04 投影；检索只能在已授权集合内缩小。
|
||
- 专名和数字有确定性检索路径，向量质量以中文样例验证。
|
||
- 方法索引指纹覆盖版本身份、实际文本、向量和嵌入器身份，并复检当前方法版本集合、确认提案语料及来源授权；不只比较行内自报哈希。检索复用本次核验的同一份载荷，不二次读入另一份索引。
|
||
- 索引及台账在同一事务替换，并发重建串行；来源经 B04 公开接口读取，不以方法列表页数量上限截断全集。重建不改正式方法，旧指纹或失效来源明确拒绝，不自动改写旧台账以冒充新鲜。
|
||
- 实际入选、省略、版本、片段和模型消费有记录；历史可重读不代表仍可用于新任务。消费登记复核派发回执的快照指纹与不可变逐键片段，和检查当前可发送性分开；新派发、恢复及采纳仍复检当前依据。
|
||
- 方法授权随任务范围的 `methods` 冻结，包含绑定身份、方法及版本身份、目标、材料键、材料哈希、有效结构哈希及 S04 投影版本；新绑定不能混入旧任务。两种用途取自冻结任务，不从材料反推。缺少结构或投影身份的旧方法范围不能继续使用，须重新授权。
|
||
- 快照复用 `frozen_scope` 与 `source_bindings`，只有预算入选的方法记入来源绑定。绑定的数据版本、有效结构哈希及真实 S04 投影版本必须与授权一致；逐键片段另按材料哈希核对，不用固定标签冒充投影版本。
|
||
- 方法材料的标题与证据取自绑定版本的确认提案，不混入后续提案。停用、释放、重绑、来源用途撤权或材料变化均阻断旧范围的回放与使用；当前版本指针前进不等于固定绑定自动升级。
|
||
- 装配记录保存逐键字符区间 `[开始, 结束)`；区间按入选顺序覆盖全文及分隔符。冻结按键取出方法全文精确比对，不以全文中包含某段文字代替材料归属校验。
|
||
- 模型发送保护在 S02 标记发送的同一短事务核对实际输入、冻结快照与方法依据；通过 B04/B03/S04 公开用例保护方法状态、原绑定、来源授权与字段策略，锁不跨模型调用。提交前的停用、释放、撤权或策略收紧与发送授权明确排序，不以早先只读检查代替发送关口。
|
||
- 模型候选采纳事务内按候选绑定的快照核对作者、作品与方法依据，并将依据保护到事务结束；依据失效则不写正文。方法状态采用当前有效性语义：同一绑定合法重新启用后可重新核验，但不会自动重跑失败任务；是否采纳仍需作者明确决定。
|
||
|
||
## 已确认作品声音的消费合同
|
||
|
||
写手任务通过B06公开接口冻结本书已确认声音，`voice`为固定声音身份或明确的null（尚无声音）；不读取未决提案，也不把新声音混入已冻结任务。声音绑定包含版本ID/revision、原内容哈希、有效结构哈希、当前S04投影版本及实际指导材料哈希，投影沿任务内容用途与执行用途计算。样张全文不进入写手请求，只发送投影后的叙述指导、已有字面依据的口癖和保护表达；声音指导不是人物事实、必须命中词表或规则已激活证明。
|
||
|
||
已有声音作为必读材料整项参与预算，放不下明确失败而非截断或静默省略；无声音不追加占位指导，不改变原写手材料。冻结时逐键核对真实材料与唯一来源绑定，不接受把指导搬到别的材料键或自报版本。声音变化、来源撤权或投影收紧使旧快照当前失效；null后首次确认同样要求重新授权。
|
||
|
||
回放、恢复、新发送和候选采纳均重验同一声音身份。新发送与采纳在短事务经B06保护当前指针、真实来源授权和S04策略，声音确认使用相同的作品级锁；包括首次确认与无声音发送之间的排序。锁不跨网络调用；已合法发送的历史快照及交付不因后来声音变化而被篡改，但旧候选不能跳过当前依据复检。
|
||
|
||
## 协作与失败
|
||
|
||
正文ABC回放资料由维护发布入口经B09封存，评测角色不直读正式业务表。封存输入只声明作品、目标章、历史文稿版本、连续基线数量和材料预算；B09经B01/B02/B05读取真实目录、已确认细纲、历史时点事实投影和原文，目标及未来章不能成为历史来源。目标正文只进入独立答案侧。S04投影明确使用evaluation/generation，剔除字段不能从其他载荷补回。
|
||
|
||
A使用连续历史基线及一般关键词补充原文，B仅使用时点卡片索引，C使用同一基线及卡片来源对应的补充原文，同时保留索引。A/C的补充码点预算相同且必须足额，C不得越过已声明历史集合回读卡来源；预算不足、缺连续基线或缺合法索引明确拒绝。检索的实际入选来源、片段和省略记录放封存依据，不将实验臂、内部身份或目标答案放入写手材料。封存是资料准备，不认证模型效果；执行仍核对封存哈希、字段策略和本次资料授权。
|
||
|
||
聚合 B01—B07 的查询和 S04 投影，S02 留痕；来源索引是派生物。
|
||
|
||
其他作品、未来章、未确认或撤回来源拒绝；必读不足返回具体缺项，不能补造材料。
|
||
|
||
## 验收行为
|
||
|
||
- 三阶段工具读取都拒绝越界。
|
||
- 结构用途收紧阻断旧范围的新派发与采纳，不改写已经合法派发的历史材料。
|
||
- 回放使用相同输入版本。
|
||
- 向量命中不绕过真实来源校验。
|
||
|
||
验收入口和替换条件见[迁移与验收](../迁移与验收.md)；这些条目是目标行为，不是已通过测试的声明。
|
||
|
||
### 方法检索的空结果
|
||
|
||
混合检索只读取可用的新鲜方法索引，不自动写入规划选择。空白查询在读取索引前以`CONTEXT_INPUT_INVALID`拒绝。结果保留索引身份；索引无条目时`empty_reason=empty_index`，有索引但两路都无命中时`empty_reason=no_match`并给出作者可读说明。有命中时该字段为null。此合同不改变B04固定绑定材料的列表返回值。
|
||
|
||
### 偏好重排通路
|
||
|
||
混合检索在关键词、向量两路 RRF 之上增加偏好路。偏好信号经公开接口取得：B07 暴露参考挑选信号（选用/拒绝计数，带位次偏置标记），B04 暴露消费统计（实际消费计数）；B09 不读两者私表。
|
||
|
||
弱强信号分列计数，不混算：参考挑选是弱信号（受位置偏置影响，排序靠前者天然更易被选中），改写采纳与实际消费是强信号。"种类→权重"映射由版本化权重表承担；偏好路初始权重保守（相对双路各 1.0 的量级不超过 0.25），权重表版本号写入检索回执。
|
||
|
||
重排保留 1~2 个探索位：将无任何挑选或消费信号的高相关版本注入候选，对抗熟悉度泡沫（挑熟悉的→推熟悉的→方法面越用越窄）；未晋升的尾部候选按原序保留，不破坏候选回填链。重排是纯函数：同一输入（得分表、信号表、权重版本）得到同一输出。
|
||
|
||
重排结果的审计链由两处承担：检索回执记录权重表版本、每个候选的偏好分项（选用/拒绝/消费计数与偏好值）及探索位标记；作者的挑选动作经 B07 参考挑选反馈落账，固化索引代次与权重版本。检索本身不是冻结任务的来源；作者实际选定的参考版本经任务范围 references 节冻结并受依赖复检（见 B06 参考改写），沿用偏好绑定先例的是该节而非检索回执。
|
||
|
||
### 场景片段检索
|
||
|
||
`场景检索` 与方法检索平行，服务参考改写语料源切换：关键词与向量两路 RRF 等权，语料为 B03 当前具备 `reference_reading` 用途来源的场景切片（授权过滤在查询时 join，代次只管向量新鲜度）。候选键带 `slice:` 前缀，与方法版本身份键空间不混。结果行携带书名、窗位置与原文预览，供作者知情挑选。
|
||
|
||
v1 不接偏好重排：重排信号语义是方法卡的选用/消费，场景切片无消费概念；检索入口保留与信号表同构的接缝，待片段挑选信号积累后另行评估。授权撤回、来源版本更新或代次陈旧时相应切片退出候选，不扩大为全池不可用。
|
||
|
||
### 读取前预算与摘要分页
|
||
|
||
新建任务在 `source_scope` 冻结 `context_policy_version=2` 和 `context_read_budget`。预算唯一默认值在 S02 `上下文预算.py`；输入字节与模型输出 token 分开核算。旧任务不补字段、不改回放哈希，超过部署硬上界返回 `CONTEXT_POLICY_REAUTH_REQUIRED`，由作者重新授权。
|
||
|
||
B09先通过 B01/B02/B05 公开元数据面检查目录数量、载荷字节和当前版本，再取得载荷。正文依赖复检不读取 `document`、不恢复草稿；事实当前依据检查只比正文版本与哈希，原文引文仍在事实确认入口验证。元数据大小在数据库侧计算，仅保证应用传输和物化上界，不代表数据库物理读取量相同。细纲和事实过大明确拒绝；事实工具可点名冻结范围内的有界对象集合，不把被省略材料冒充完整结果。
|
||
|
||
v2历史正文未指定结束位置时返回有界片段及 `has_more/next_cursor/omitted_reason`。游标绑定任务、冻结范围、正文版本及投影，不能跨任务或版本续用。S02在结果进入模型历史前分别检查单工具及累计工具字节；完整模型请求的系统提示、工具定义、输入、历史和序列化开销共同受 envelope 上界约束。读前预留和耗时使用现有工具事件持久化，恢复取该步骤最近累计量；失败读取与实际重复读取保留成本，不以进程重启清零。拒绝保留错误码、消费量和调用身份，不保存失败候选内容。
|
||
|
||
`读取并核对快照` 同时返回历史快照与当前依赖状态，消费入口无需重复整轮检查；发送、恢复、采纳仍分别复检当前授权。新 HTTP `context-snapshots/page` 使用绑定任务和用途的稳定游标，默认20、最多100条，只选择摘要字段而不读取装配正文，同页相同冻结范围与绑定只核验一次。旧无分页入口兼容保留，不静默截断。
|
||
|
||
离线机制回归见 `test_上下文读取上界.py` 的 `NC-O07-*` 用例；真实 PostgreSQL、生成合同与跨包端到端证据由集成验收记录。
|