你可能会问
真的完全免费吗？可以商用？
是。MIT 协议，可商用、可二次开发、可闭源分发，不用付费也不用署名（保留 LICENSE 即可）。
唯一的成本是模型厂商的 API 费用，这部分直接跟厂商结算，项目本身不收任何费用、不做中间层。
没有 GPU 能跑吗？服务器要什么配置？
不需要 GPU —— 模型推理都在厂商侧，本机只做检索和编排。
小规模（<1 万片段）2 核 2G 就够；中等规模建议 2 核 4G。注意向量数据比想象的占空间：实测 12,596 个片段（2048 维）的 Chroma 目录约 163MB。
支持哪些文档格式？中文效果怎么样？
支持 txt / md / docx / xlsx / pdf，单文件默认上限 20MB。
切分器针对中文做了专门处理：识别【章节】、第X章、中文标点边界，Q&A 问答对不会被拆开。相关性阈值也是按中文 embedding 的实际分数分布调的 —— 中文里即使内容无关相似度也有 0.65 左右，所以单独引入了一个 0.76 的相关性分界线。
问什么都回「知识库中没有相关信息」怎么办？
按顺序检查：① 文档状态是否为就绪且分片数 > 0；② 把相似度阈值调低（默认 0.5）；③ 用「预览切分效果」确认文档被合理切分。
如果希望资料外的问题也能回答，到「RAG 设置」开启自主回答开关。
入库很慢或者中途失败？
多半是 embedding 厂商的配额限制（实测火山方舟的配额是长周期累计的）。
项目已做断点续传：中断后进度保留，再点「入库」从上次位置继续，已完成的片段不会重复消耗配额。大知识库建议用 scripts/ingest_retry.py 挂后台跑。
管理后台有登录吗？部署后安全吗？
有内置登录。访问 /admin/ 下任何页面都会先跳登录页，默认账号 admin / 123456 首次启动自动创建，登录有效期 7 天。配置类和文档类接口全部需要管理员 token；聊天接口和嵌入组件保持公开 —— 否则嵌到别人网站上的组件根本跑不通。
但默认密码必须改掉，这是上线第一件事，同时把 APP_SECRET_KEY 换成随机值。要再加一层，部署文档里给了 SSH 端口转发 / IP 白名单 / Basic 认证三选一。另外 API Key 目前只做了 base64 混淆不是加密，生产环境应该换成 KMS / Vault。
可以只用某一个厂商吗？会不会绑定？
不绑定。15 项预设只是帮你省去查文档填地址的功夫，随时可以在页面上切换。
还有两个自定义槽位：任何兼容 OpenAI 或 Anthropic 接口的服务都能接 —— 自建 vLLM、one-api、LiteLLM、Ollama 本地模型都可以。
能嵌到微信小程序里吗？
可以，通过小程序的 web-view 组件加载。仓库里的 docs/EMBED_GUIDE.md 有微信/支付宝/抖音各平台的具体做法，以及 Electron、Tauri、iOS/Android WebView 的接入方式。
注意需要在小程序后台把域名加入业务域名白名单。
界面支持多语言吗？内网离线能自动选对语言？
支持简体中文 / 繁體中文 / 日本語 / English 四种，管理后台、聊天组件、独立聊天页都能切，选择记在 localStorage，后台和组件共用一个键。
默认语言先看浏览器时区，再看语言偏好，不查 IP —— 内网里客户端地址是 10.x / 192.168.x 本身不带地区信息，离线环境也连不上任何 IP 库，所以纯内网部署一样判断得对。切换语言后 AI 回答也跟着换：知识库仍是中文、检索逻辑一个字没改，只在提示词后面追加一段用目标语言写的作答指令。
忘记后台管理员密码了怎么办？
在 backend/ 目录下跑重置脚本：python -m scripts.reset_admin_password，按提示输入新密码（输入时不回显）。
也可以非交互式重置：python -m scripts.reset_admin_password --username admin --password 新密码；加 --list 先看看有哪些账号。重置后所有设备都会被登出，需要用新密码重新登录。
还没有任何 API Key，能先把项目跑起来吗？
能。服务正常启动，非模型类功能（后台、文档管理、嵌入代码等）全部可用；涉及模型调用的接口会返回明确的 llm_error / embedding_error，方便先把前后端联调跑通，Key 到了填上即可。
也可以先接 Ollama 本地模型：地址 localhost:11434，Key 随便填，不花一分钱。
入库报 dimension of 2048, got 1024 是怎么回事？
这是换了 Embedding 模型、但旧集合还锁着旧维度导致的。删文档、重启服务都解不掉 —— 空集合也保留维度锁，必须重建向量库。
到「模型配置」页点 🔌 测试并探测维度，横幅会写明锁定维度与当前模型维度，确认后一键重建：后台自动删集合、重建并把全部文档重新嵌入。即使新旧模型维度恰好相同，只要不是同一个模型也必须重建 —— 向量空间互不相通，否则检索会静默变成噪声。
火山方舟报 401？
十有八九是产品项选错了。包月套餐与按量付费是两个 Base URL：包月走 /api/plan/v3（OpenAI）或 /api/plan/v1（Anthropic），按量（豆包）走 /api/v3。
包月套餐的模型名必须固定填 ark-code-latest，具体路由到哪个模型在火山控制台选。用错地址不仅报错，还可能产生额外费用。
聊天时返回 429 怎么办？
429 是厂商侧限流。聊天接口已内置自动重试（45 秒预算、指数退避），正常使用基本不会看到。
连续高频提问仍触发，说明账号配额已达上限 —— 稍等一会儿，或换配额更高的模型。入库时的 429 则由断点续传机制处理，大知识库可用 scripts/ingest_retry.py --cooldown 60 挂后台跑。
SSE 流式回答在 Nginx 后面一次性蹦出来 / 中途断流？
Nginx 默认会缓冲上游响应，流式输出被攒成了一坨。给聊天接口单独关掉：proxy_buffering off; proxy_cache off;，长回答还应放宽读超时。
部署页有可直接抄的完整配置。后端本身已下发 X-Accel-Buffering: no，但反向代理上的缓冲仍建议显式关闭。
更新代码 / 改了前端，刷新页面却没变化？
后端对 /admin、/widget、/embed 已设置 Cache-Control: no-store，正常刷新即可。仍有残留就硬刷新：Mac 按 Cmd+Shift+R，Windows 按 Ctrl+Shift+R。
嵌入到外部网站的组件记得把引用地址的 ?v=1 版本号递增，逼着浏览器和 CDN 拿新文件。
Python 3.14 装不上某些包 / 依赖装进了错误的环境？
langchain-text-splitters 在新版本 Python 上装不上不影响运行 —— 切分器有内置实现，不依赖这个包；其余依赖已在 Python 3.14.5 上验证通过。
多 Python 环境（系统解释器、Homebrew、PyCharm 虚拟环境并存）时，用 python -m pip install -r requirements.txt 而不是裸 pip install，确保装的是当前 python 对应的环境；也可以直接 python run.py --install 让启动脚本自己装。