Admin 配置
从 Admin 左侧边栏打开设置管理运行时参数，打开模型配置管理生成模型、嵌入模型和重排模型。保存后的值会在服务重启后继续保留。修改会应用到新请求和新启动的任务；已经运行的任务可能继续使用启动时的值直至完成。
以下内容与这两个 Admin 页面当前实际显示的字段一致。建议从默认值开始，确认 CPU、内存、PostgreSQL、所选搜索服务和 S3 延迟后再提高并发。
API 限流
| 设置 | 用途 | 默认值 |
|---|---|---|
| 管理员登录 / 最大请求数 | 一个窗口内允许的登录尝试次数。 | 8 |
| 管理员登录 / 窗口秒数 | 登录计数窗口长度。 | 900 |
| Admin API / 最大请求数 | 一个窗口内允许的 Admin UI API 请求次数。 | 600 |
| Admin API / 窗口秒数 | Admin API 计数窗口长度。 | 60 |
| Developer OpenAPI / 最大请求数 | 一个窗口内允许的 Developer OpenAPI 请求次数。 | 1200 |
| Developer OpenAPI / 窗口秒数 | Developer OpenAPI 计数窗口长度。 | 60 |
这些限制在 Focowiki 内生效。反向代理或边缘服务应配置相互匹配的限流规则。
Worker
| 设置 | 用途 | 默认值或初始值 |
|---|---|---|
| 文档并发 | 同时处理的文档任务上限。模型、GraphRAG、嵌入、存储、数据库和搜索限制可能进一步降低实际并发。 | 2；测量后逐步增加，最大 32。 |
| S3 并发 | 文档处理和生成知识库更新使用的 S3 兼容对象操作并发上限，与文档并发独立配置。 | 默认 40；对象存储延迟升高或发生限流时降低，最大 48。 |
| 处理最大尝试次数 | 文件保持失败状态前允许的尝试次数。 | 3 |
| 处理重试延迟毫秒 | 临时失败后再次尝试前的等待时间。 | 30000 |
| 完成记录保留天数 | 已完成处理记录的保留天数。 | 7 |
大批量导入期间 CPU、数据库或模型服务商延迟上升时，降低文档并发；对象存储延迟或限流上升时，降低 S3 并发。
生成知识库
| 设置 | 用途 | 默认值或初始值 |
|---|---|---|
| 目录单页条目数 | 单个生成目录页直接列出的条目数，不限制目录内文件总数。 | 200 |
| 目录单页字节数 | 单个生成目录页允许的最大 UTF-8 字节数。 | 65536 |
| 根摘要字符数 | 根 index.md 中展示的知识库描述字符上限。 | 500 |
| 日志条目数 | log.md 保留的最近文档事件上限。 | 100 |
| 日志字节数 | 生成 log.md 的最大 UTF-8 字节数。 | 65536 |
每个成功的文档任务会先更新受影响的生成页面，再变为可用。系统不再提供批量、按文件或手动发布模式。
图关系
| 设置 | 用途 | 默认值 |
|---|---|---|
| 候选文件上限 | 为单个文件发现关系时考虑的文件数量。 | 200 |
| 接受关系上限 | 每个文件保留的关系数量。 | 50 |
| 默认搜索深度 | API 请求未提供深度时使用的关系层数。 | 1 |
| 最大搜索深度 | API 接受的最高关系层数。 | 2 |
| 默认搜索扇出 | 请求未提供时，每一步继续探索的相关文件数。 | 10 |
| 最大搜索扇出 | API 接受的最高扇出。 | 25 |
| 模型关系复核 | 允许当前生效模型复核关系建议。 | 开启 |
| 图分片大小 | 单个生成 _graph 分片允许的最大记录数。 | 5000 |
| 通用短语阈值 | 忽略过于宽泛的共享短语时使用的最小标准化长度。 | 4 |
默认深度和扇出不能高于各自最大值。复核开关决定是否由当前生效的生成模型检查发现的关系候选。完成文档上传仍然需要下文所述的生效生成模型和嵌入模型配置。
维护
| 设置 | 用途 | 默认值或初始值 |
|---|---|---|
| 存储一致性检查 | 定期查找可以安全清理的存储条目。 | 开启 |
| 存储扫描批次大小 | 单个批次检查的存储条目数。 | 500；最大 1000。 |
| 存储清理最大尝试次数 | 单个清理操作允许的尝试次数。 | 5 |
| 存储清理重试延迟毫秒 | 临时清理失败后的等待时间。 | 30000 |
| 硬删除并发 | 同时处理的资源删除清理操作数。 | 1；最大 16。 |
| 硬删除数据库批次大小 | 单个清理分页删除的数据库记录数。 | 1000 |
| 硬删除对象批次大小 | 单个清理分页删除的存储对象数。 | 1000 |
| 硬删除最大尝试次数 | 单个清理操作允许的尝试次数。 | 3 |
| 硬删除重试延迟毫秒 | 临时清理失败后的等待时间。 | 60000 |
| 失败硬删除保留天数 | 终态清理失败记录的保留天数。 | 30 |
维护索引用于把修改后的模型、提示词、输出格式、嵌入维度或搜索服务应用到已有知识库，也可以执行明确的修复、恢复或完整重建。普通上传和正文替换会在一个文档任务内完成全部必要处理；重命名、移动、元数据更新和删除会自动更新受影响内容。维护期间，已经可以读取的文件继续可用。
不兼容旧版本中的知识库和内容不能通过维护索引直接更新。请按照更新现有部署的步骤，把来源 Markdown 导入空目标部署；维护索引只适用于当前版本创建的知识库。
搜索
两种搜索服务继续使用相同的设置字段；修改 SEARCH_PROVIDER 不会增加、删除或重命名字段。
| 设置 | Meilisearch 中的作用 | OpenSearch 中的作用 | 默认值 |
|---|---|---|---|
| 搜索请求超时毫秒 | 限制包括可选重排在内的完整应用搜索请求。 | 限制包括可选重排在内的完整应用搜索请求。 | 8000 |
| 搜索服务超时毫秒 | 原生搜索截止时间和客户端时限。 | 搜索服务查询时限和应用截止时间。 | 1000 |
| 结果补取倍数 | 数据补全前额外获取候选结果。 | 数据补全前额外获取折叠后的候选结果。 | 3 |
| 索引更新文档数 | 单个索引任务的最大文档数。 | 单个批量请求的最大文档数。 | 10000 |
| 索引更新压缩字节数 | 单个序列化索引批次的最大字节数。 | 单个序列化批量请求的最大字节数。 | 8388608 |
| 搜索并发 | 搜索索引请求并发数。该字段没有固定的产品上限；实际活跃任务受文档并发限制，并在搜索服务繁忙时自动暂停。 | 并发批量请求或搜索服务操作数，仅在测量搜索服务后提高。 | 8 |
| 搜索任务轮询间隔毫秒 | 两次任务状态检查之间的延迟。 | 重试或最终可见性检查之间的延迟。 | 500 |
| 搜索任务超时毫秒 | 索引任务的总时限。 | 批量请求、索引和可见性操作的总时限。 | 600000 |
| 搜索任务最大尝试次数 | 任务和请求的最大重试次数。 | 临时请求和单项失败的最大重试次数。 | 5 |
| 搜索重试延迟毫秒 | 任务或请求重试前的延迟。 | 临时重试前的延迟，包含小范围随机调整。 | 2000 |
| 搜索清理批次大小 | 单次清理的旧索引记录上限。 | 单次清理的精确索引记录上限。 | 1000 |
| 搜索结果摘要长度 | 原生摘要截取长度。 | 高亮片段和标准化摘要的最大长度。 | 1200 |
搜索服务超时必须低于总请求超时。启用重排时，Focowiki 会为重排预留总请求预算的 40%，最多 5 秒，并限制可选检索工作以保留该窗口；快速请求会立即返回，不会等待预算耗尽。所选搜索服务的内存或磁盘延迟上升时，降低单次更新大小或在途任务数。
语义搜索
OpenSearch 和 Meilisearch 共用相同的语义设置。这些字段限制可选的 GraphRAG 和嵌入处理，不会修改生成文件树或来源 Markdown。
| 设置 | 用途 | 默认值 |
|---|---|---|
| 最大分块字符数 | 单个提取分块的最大字符数。 | 8000 |
| 最大分块数 | 单个上传文档的最大提取分块数。 | 32 |
| 最大证据目标数 | 单个语义单元保留的来源证据目标上限。 | 64 |
| GraphRAG 适配器超时毫秒 | 单次 GraphRAG 提取请求允许的最长时间。 | 30000 |
| 语义搜索通道截止毫秒 | 可选语义搜索通道的独立截止时间，不能高于完整搜索请求超时。 | 2500 |
| 查询嵌入并发 | 单进程同时执行的查询嵌入请求上限。 | 4 |
| 查询嵌入缓存条目数 | 单进程查询嵌入缓存条目上限。 | 1000 |
建议从默认值开始。工作进程的 CPU 或内存、模型延迟或搜索延迟升高时，降低分块或查询嵌入限制。可选语义搜索通道失败时会返回安全的语义状态，已经完成的精确和词法通道仍可返回结果。
文件处理列表展示准备、模型辅助、生成内容、GraphRAG、关系协调、索引、可用和清理工作的已提交进度，互不依赖的工作可以同时进行。文件只有在必需的来源、生成页面、关系、嵌入和搜索文档都已生效且可以读取后才会显示为可用。
嵌入模型
嵌入模型在模型配置页面的嵌入模型页签中管理，并同时适用于两种搜索服务。云服务使用带认证的 HTTPS 端点；认证模式 none 仅用于可信本地或私有网络端点。
| 设置 | 用途 | 默认值或初始值 |
|---|---|---|
| 显示名称 | Admin UI 中显示的名称。 | 包含服务商和用途。 |
| 认证模式 | api_key 发送后端凭据；none 不发送凭据。 | api_key |
| Base URL | OpenAI 兼容嵌入 API 地址。 | https://api.openai.com/v1 |
| API key | api_key 模式使用的后端凭据。 | api_key 模式必填，保存后不再完整显示。 |
| 模型名称 | 服务商的嵌入模型标识。 | 与服务商文档完全一致。 |
| 请求维度 | 兼容服务商支持的可选输出维度。 | 留空时使用模型实际返回的维度。 |
| 归一化 | Focowiki 应用的嵌入归一化方式。 | l2，也支持 none。 |
| 最大输入 tokens | 单个嵌入输入声明的最大预算。 | 8192 |
| 批次大小 | 单次请求发送的嵌入输入上限。 | 32 |
| 超时毫秒 | 单次嵌入请求的最长时间。 | 30000 |
| 重试次数 | 服务商临时失败后的最大重试次数。 | 2 |
| 最小请求间隔毫秒 | 两次服务商请求之间的最小间隔。 | 0 |
| 并发 | 同时执行的嵌入请求上限。 | 4 |
| 最大响应字节数 | 允许接收的服务商响应大小上限。 | 8388608 |
先创建配置，使用测试验证端点和实际嵌入维度，再使用激活。新文档任务使用当前生效配置。编辑已保存配置会创建新修订；已有知识库只有在维护索引完成后才会接入该修订。只切换搜索服务时，可以复用兼容的嵌入结果，无需重复调用相同模型。
公共混合搜索会从每种可用向量类型中获取有限且有序的候选，再与精确匹配、文本、中文分词和文件关系证据共同排序。嵌入配置不再包含公共搜索相关性阈值。从早期版本升级时会继续使用已有嵌入和搜索索引，不需要重新上传、重新嵌入或逐个维护知识库。如果旧游标在升级后被拒绝，搜索客户端应重新开始分页。
表格以只读状态展示实际维度、校验状态和生命周期状态。暂停后，新任务不会再选择该配置；恢复后，暂停的修订可以再次被选择。配置修订仍被生效或运行中任务引用时不能删除。列表、状态、错误、日志和 API 响应始终隐藏完整凭据。
重排模型
重排是可选的查询阶段。模型配置页面的重排模型页签只保存模型连接、凭据、模型标识、校验、生命周期、超时、重试、最小请求间隔和并发。创建配置后先使用测试，再使用激活。暂停、替换或删除重排模型不会重建知识库，也不会修改语义生成结果。重排模型缺失、暂停或失败时，搜索仍使用确定性的混合排序。
请填写服务商基础 URL，例如 https://provider.example/v1。Focowiki 会自动补全 /rerank，并向 https://provider.example/v1/rerank 发送标准重排请求。该字段不要填写 /rerank 或 /v1/chat/completions；重排模型不支持 Chat Completions 协议。
最终结果 limit、rerankTopK 和 rerankScoreThreshold 属于 Developer OpenAPI 单次请求字段，因此不会出现在 Admin 设置中。rerank 默认是 false；启用后，接口只发送已经授权的标题、路径和限制长度的来源正文摘要。分数阈值默认为 0，因此重排通常只改变顺序，不删除候选。显式设置正阈值可以过滤非精确候选；如果全部被过滤，响应会返回 RERANKER_ALL_BELOW_THRESHOLD。
模型
生成模型在模型配置页面的模型页签中管理。完成上传需要一个生效生成模型和一个已经验证并生效的嵌入模型配置，以保证每个被接受的文档在变为可用前遵循相同索引契约。同一时间只能有一个生效生成模型。
| 设置 | 用途 | 推荐值 |
|---|---|---|
| 显示名称 | Admin UI 中显示的名称。 | 包含服务商和用途。 |
| API 模式 | 服务商使用的协议。Responses 通过 text.format 发送严格 JSON Schema；Chat Completions 先通过 response_format 发送严格 JSON Schema，只有服务商明确拒绝该能力时才使用 JSON 对象兼容模式。 | responses 或 chat_completions，与服务商端点一致。 |
| Base URL | OpenAI 兼容 API 地址。 | 服务商要求时包含 /v1。 |
| API key | 后端使用的服务商凭据。 | 使用独立密钥并定期轮换。 |
| 模型名称 | 服务商模型标识。 | 与服务商文档完全一致。 |
| 上下文窗口 tokens | 模型上下文容量。 | 使用服务商公布的上限。 |
| 请求最大超时毫秒 | 单次模型请求允许的总时间。 | 长文件使用 600000 或更高。 |
| 请求空闲超时毫秒 | 模型响应没有活动时允许的最长等待时间。 | 120000 到 300000。 |
| 建议生成并发 | 同时执行的模型请求数。 | 从 1 或 2 开始。 |
| 临时错误重试延迟毫秒 | 服务商临时失败后再次尝试前的等待时间。 | 60000 |
| 请求最小间隔毫秒 | 两次模型请求之间的最小等待时间。 | 稳定服务使用 0，严格限流时适当增加。 |
模型创建后不会再次显示完整 API 密钥。暂停模型后，新任务不会再选择该模型。运行中的任务仍在使用模型时，需要等待任务完成后再删除。
结构化输出能力会随当前模型修订复用。认证、配额、超时、内容和其他请求错误不会触发格式切换。模型执行记录只保留安全的请求 ID、结束状态、服务商返回的令牌计数、耗时和重试分类；不会保存提示词、来源正文、凭据或推理内容。
配置生效
Admin 运行时设置和模型配置由 Focowiki 保存，不应写入 .env。端口、域名、基础设施凭据、数据库连接上限、存储凭据和日志路径仍属于启动配置。修改启动配置后需要重启对应服务。