business-assistant/docs/concurrency.md

服务并发配置与边界（F099）

F104新增共享内存接纳：问答、分类、后台扫描和分析合计默认4个名额，RSS和可用内存检查可能进一步拒绝；下表16路不再是默认可同时执行的问答数。各阶段原并发配置保留。生产硬隔离须安装systemd unit，见内存保护。

生产API/CLI的问答并发通过环境变量配置；本轮新增两项，本地均为8：

KNOWLEDGE_ANALYSIS_CONCURRENCY=8
RETRIEVAL_CONTENT_CONCURRENCY=8

两项范围1–32、默认8，系统环境变量优先于项目.env，非法值启动失败，重启后生效。直接构造Recommender的测试/开发调用仍可显式传workers；API/CLI均注入环境配置。F170将全文分析改为先准备各候选的原有分块，再由单个请求内证据块池调度，不再额外创建候选协调线程池；真正模型调用仍最多workers路，不会变成8×8调用。卡片短文案阶段复用同一并发配置。不同知识库完整原文回读各自存储结果，按库顺序合并后仍按原候选顺序恢复和校验；同库首段读取完成后才查询剩余分段。只有六库时配置8实际最多6路；某库没有入选候选则不创建读取任务。

原文分析调度（F170）

在4000字节组块、长字段1000字切分不变的前提下，以既有分块序列化证据字节量估算任务权重，比较原顺序和稳定长块优先顺序的预计最终工作线程负载。只有预计负载至少下降5%才改变开始顺序；单worker、所有块一波可运行、同长或收益不足时保留原顺序。资料相关性、选中数量、分析块数量、模型调用/重试上限、输入/输出预算均不调整，不删独有条件/例外或合并不同来源。各块的系统提示、title/情形/区划、主体事实、evidence_id、path/offset/text及修正反馈保持原协议。

各任务结果仍按原候选和原chunk_index归位后再合并；引用/资格验证和两次局部尝试不变，任一块失败仍禁止该来源进入完整推荐与综合。取消标志保留来源内隔离，已排队块先检查取消状态，在途调用可能继续；新开始顺序可能改变取消时已有的片段，不保证中断时部分诊断集合完全相同，完整性门槛不放宽。

字节量不是模型输出复杂度或真实耗时。长块优先只是启发式，不保证每组请求更快；耗时与输入长度反向时可能变慢。仅本地合成Git原实现对照验证：相同输入/提示和完整输出相同，相关耗时替身的8来源36块样例中位165.189→153.623ms（3次），1/3/12来源没有显著重排收益，保留原顺序。虚拟反例中预计权重改善但真实设定时长5→6，明确不能由此承诺用户11块会从6.653秒减少多少。没有调用真实模型、Redis/检索或部署，实际收益及模型服务容量仍需获准后验证。

新增analysis_prepare跨度（包含原文提取、原有分块、估算和排序），仍嵌套在analysis中；新增数字测量后缀.analysis：analysis_scheduled_chunks（待模型分析块数，不含QA快路径）、analysis_reordered_chunks（相较原顺序换位块数）、analysis_schedule_original_weight/analysis_schedule_selected_weight（预计最后线程负载，单位为累计证据字节权重，不是ms/token，也不含完整提示/标题补入开销）。指标不含来源名、编号、原文或主体数据。对比时继续看analysis墙钟和model_wait.analysis，不可把executor_wait或模型调用累计量当总时间。

executor_wait.analysis在F170前同时累计候选协调池和证据块池等待，F170后只剩证据块池；例如3候选11块由14次变成11次并不代表少分析了3块。跨版本不能把该累计量直接相减当作真实阶段提速；分块数看analysis_scheduled_chunks和候选诊断，实际调用及重试看model_call.analysis，阶段墙钟看analysis。

配置清单

下表是代码默认值，不代表未核对的部署环境实际值；本轮仅修改上述两项本地配置。

环境变量	默认	作用域
API_MAX_CONCURRENT_REQUESTS	16	chat接纳上限；公司分类有独立接纳池但复用此数值
API_LLM_CONCURRENCY	8	API进程内共享模型名额，覆盖问答、rerank、图片识别、公司分类及后台分析
API_RETRIEVAL_CONCURRENCY	4	API进程内同时检索的请求数
RETRIEVAL_QUERY_CONCURRENCY	4	单请求查询并发
RETRIEVAL_BANK_CONCURRENCY	6	单查询跨库向量检索并发
RETRIEVAL_CONTENT_CONCURRENCY	8	单请求跨库完整原文回读并发
RERANK_CONCURRENCY	4	单请求相关性初筛并发
KNOWLEDGE_ANALYSIS_CONCURRENCY	8	单请求全文分析、候选协调和随后卡片短文案并发
SESSION_ANALYSIS_CONCURRENCY	4	后台同时分析的会话数

离线知识摘要的SUMMARY_CONCURRENCY已有独立环境配置，不属于在线请求。API进程数仍固定1，这是会话排他安全边界，不将其开放成可随意提高的并发配置。CLI单独运行时不使用API进程的共享模型信号量。

已有保护与未验证风险

• 同一API进程内同一thread_id互斥，容量已满拒绝新请求；断线后保持会话锁到工作线程退出。同一Redis会话命名空间不能用多个API进程/副本或混用CLI并发写。
• 请求计时及结果各自隔离；跨库原文读取使用线程局部容器后合并。各库Milvus只读客户端固定数据库，无切库操作；实际部署SDK连接池和容量仍需多用户压力验证。
• 本地向量计算加锁；API模型调用受共享上限约束。全文分析调到8后，单请求可能占满默认8个名额，其他请求和后台任务需等待；当前信号量不保证公平排队或前台优先。
• 嵌套并发不能只看一个8：默认4个检索请求×每请求4条查询×6个库，向量检索最多可能有96个在途调用；原文回读最多4×min(8,6)=24路。检索两个阶段同请求串行，不应简单相加宣称每请求同时发生。连接、线程、内存和远端限流要结合实际负载确认。
• 同步在途调用不能立即取消；更高并发可能增加断线后的资源释放等待。数据越大，完整记录与分析结果的内存成本越高。
• 本轮合成屏障测试证明8路模型分析上限、六库并行、多段结果与串行完全一致、低并发上限及单库读取失败隔离；不代表实际服务吞吐、SDK压力或所有语义正确。

重启后优先比较同类请求的total_ms、analysis、model_wait.analysis、retrieval_call.retrieve、content_read及错误率。content_read现在可能并行，其total_ms是各调用累计，不是阶段墙钟；检索整体耗时看retrieve。先测单请求，再测多请求并观察P95，不能把单请求改善当成总容量验收。