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均注入环境配置。全文分析的候选协调池和共享证据块执行池使用同一上限，真正模型调用在共享证据块池，不会变成8×8调用；卡片短文案阶段复用这一配置。不同知识库完整原文回读各自存储结果，按库顺序合并后仍按原候选顺序恢复和校验；同库首段读取完成后才查询剩余分段。只有六库时配置8实际最多6路；某库没有入选候选则不创建读取任务。

配置清单

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

环境变量	默认	作用域
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，不能把单请求改善当成总容量验收。