docs：更新函数库、知识库、应用的常见问题

Author: greenyhsj

docs/faq/apply_setting.md

@@ -0,0 +1,33 @@
+# 应用相关问题
+
+## 1 应用高级编排设置页面画布显示问题
+!!! Abstract ""
+    浏览器内核版本过低（如谷歌浏览器 93.0.4577.63），需要进行浏览器升级。  
+    **注意**：工作流编排不支持 Safari 浏览器，建议使用最新版本的谷歌的浏览器。
+
+## 2 使用换个答案后检索不到知识库
+!!! Abstract ""
+    当使用【换个答案】功能时，检索机制会排除上一次检索到的所有分段，然后重新进行检索。如果上一次检索结果中只有一个匹配项，那么重新检索时可能会出现结果为空的情况。
+
+## 3 同一个应用，显示不同语言界面
+!!! Abstract ""
+    应用显示设置中的语言选择未统一。 需要在应用显示设置中选择所需语言并保存。
+
+![doc](../img/FAQ/语言显示设置.png)
+
+## 4 应用文档内容提取报错“File is not a zip file”
+!!! Abstract ""
+    上传的文件实际是 doc 类型文件，而非 zip 文件，需要确保上传文件格式正确。
+
+
+## 5 应用添加 MCP 组件报错“unhandled errors in a TaskGroup(1 sub-exception)”
+!!! Abstract ""
+    MCP 服务启动失败，数据库连接密码包含特殊字符 `@`，与 dbhub 启动命令冲突。
+
+## 6 应用添加 MCP 组件报错“transport”
+!!! Abstract ""
+    MCP Server Config 配置格式不正确，缺少 "transport": "sse" ， 需在配置中添加  "transport": "sse"。
+
+## 7 请求 Swagger API 报错“URL scheme must be 'http' or 'https' for CORS request.”
+!!! Abstract ""
+    Swagger 文档的 schemes 格式未正确选择，IP 地址使用了 http，而域名使用了 https。 确保 IP 和域名的协议需匹配。

docs/faq/function_library.md

@@ -0,0 +1,34 @@
+# 函数库
+
+## 1 函数库运行后提示缺少依赖
+
+![doc](../img/FAQ/函数库缺少依赖.png){width="900px"}
+
+!!! Abstract ""
+    函数库运行时提示缺少依赖，是因为某些函数库在运行时需要调用其他第三方库来完成特定功能。如果这些第三方库未安装，函数库就无法正常运行，从而提示缺少依赖。  
+    进入 maxkb 容器 ：
+    ```
+    docker exec -it maxkb bash 
+    ```
+    使用 pip 安装第三方依赖，如 pymysql ： 
+    ```    
+    pip install pymysql
+    ```
+
+## 2 函数库连接 SQL Server 数据库报错
+
+![doc](../img/FAQ/函数库连接数据库失败.png)
+
+!!! Abstract ""
+    连接 SQL Server 数据库时，报错提示： pymssql 连接失败 20002, b'DB-Lib error message 20002, severity 9: Adaptive Server connection failed。  
+    可能原因：
+
+    - 网络问题：容器无法访问目标服务器 IP（如 192.168.0.23）。
+    - 依赖问题：pymssql 版本不兼容或安装失败。
+    - 连接配置问题：未指定正确的 TDS 版本。
+    
+    解决方法:
+
+    - 确保网络连通:检查容器与目标服务器之间的网络连接是否正常，以及 SQL Server 的配置，确保其允许远程连接，并检查防火墙设置是否允许访问目标端口。
+    - 重新安装兼容版本的 pymssql。在容器中安装依赖库后，确保后续在函数库中正确使用这些依赖库连接数据库。
+    - 指定 TDS 版本：在连接语句中明确指定 TDS 版本（如 7.0）。

docs/faq/install_configuration.md

@@ -21,7 +21,7 @@
     ```
     找到导致依赖冲突的包，通常通过查看错误日志来确定具体冲突的包名。完成依赖包的清理后，重启服务 mkctl restart 以确保更改生效。
 
-## 4 PostgreSQL 超过最大客户端连接数,提示 too many clients already 的错误
+## 4 PostgreSQL 超过最大客户端连接数，提示 too many clients already 的错误
 
 !!! Abstract ""
     这表明当前配置的客户端连接数已达到上限，需要调整配置以允许更多的连接。进入 PostgreSQL 配置文件所在的目录：

docs/faq/knowledge_base.md

@@ -0,0 +1,59 @@
+# 知识库
+
+## 1 智能分段效果不理想
+
+!!! Abstract ""
+    默认的分段逻辑无法完全适配特定文档的内容结构，可以尝试在导入文档后选择“高级分段”，并在分段标识输入框中直接输入正则表达式，以实现精准的分段操作。
+
+![doc](../img/FAQ/使用高级分段.png){width="900px"}
+
+!!! Abstract ""
+    **应用场景举例**：
+    
+    - **多级数字编号**  
+        正则表达式：\d+\.\d*\.\d*\.[a-zA-Z\s]*[\u4e00-\u9fa5，]+  
+        示例：1. 一级标题 1.1 二级标题
+
+    - **中文序号编号**：  
+        正则表达式：[一二三四五六七八九十]*、[\u4e00-\u9fa5a-zA-Z]+  
+        示例：一、标题
+
+    - **小说章节目录**：  
+        正则表达式：[第][一二三四五六七八九十]+[章][\u4e00-\u4e00a-zA-Z]+  
+        示例：第一章 标题
+
+    - **多级中文+数字编号**：  
+        正则表达式：[一二三四五六七八九十|1-9]+[、|.]1-9*.[1-9]*[\u4e00-\u9fa5a-zA-Z]+  
+        示例：一、一级标题 1.1 二级标题
+    
+    详细操作和预览效果可参考 [**MaxKB 使用正则表达式分段**](https://kb.fit2cloud.com/?p=bfe242a4-9a77-459c-ac75-4ef078e170c9)。
+
+## 2 上传文档向量化后，字符数为 0
+
+!!! Abstract ""
+    上传的文档类型实际是 `.doc` 格式，而非其他支持的格式，导致向量化后字符数为 0。
+    上传文档要求：
+
+    - 文本文件：Markdown、TXT、PDF、DOCX、HTML、XLS、XLSX、CSV、ZIP；
+    - 表格：XLS、XLSX、CSV、ZIP;
+    - QA 问答对：XLS、XLSX、CSV、ZIP；
+
+## 3 文档提交成功，但未显示上传的文档
+
+!!! Abstract ""
+    文档提交成功后未显示上传的文档，可能是反向代理的请求大小配置不，增加代理配置后可解决此问题。
+
+## 4 知识库以 ZIP 格式导出再导入时分段数不一致
+
+!!! Abstract ""
+    导出知识库后，重新上传 ZIP 文件时，请选择 **“QA 问答对”** 进行导入。
+
+## 5 知识库上传文档后，文档标题乱码
+
+!!! Abstract ""
+    的压缩软件导致问题。已知 WinRAR 和 52 压缩存在兼容性问题，建议使用其他压缩软件进行压缩和解压操作。
+
+## 6 向量化成功，但生成问题失败
+
+!!! Abstract ""
+    可能是当前使用的生成问题的大模型存在问题。可以尝试更换其他生成问题的大模型来解决此问题。此外，可以检查后台日志文件以获取更多错误信息，日志文件位于 `/opt/maxkb/logs` 目录下，通过查看日志可以了解具体的错误原因。

docs/faq/system_management.md

@@ -97,14 +97,24 @@
     原因可能是模型名称或版本不正确。 解决步骤：  
 
     - 检查模型名称：在容器中通过 curl 请求查看是否有对应的模型名称返回
-    - 检查 XInference 版本。当前使用的版本为 v1.3.0.post2，这是一个测试版本，可能存在不稳定的情况。建议切换到更稳定的版本，例如 XInference 的最新稳定版本。
+    - 检查 XInference 版本。如果使用的版本为 v1.3.0.post2 ，该版本为测试版本可能存在不稳定的情况。建议切换到更稳定的版本，例如 XInference 的最新稳定版本。
 
 
-### 2.4 检查参数是否正确：Connection error
+### 2.4 添加模型失败提示 Connection error
 
 !!! Abstract ""
-    这通常是由网络连接问题引起的。排查思路：  
+    通常是由网络连接问题引起的。排查思路：  
 
     - 检查防火墙设置：确认防火墙是否限制了相关端口。如果限制了，请开放该端口，确保容器可以正常访问网络。
 
-    - 检查容器网络配置：确认容器内是否有网络连接。可以尝试在容器内执行网络测试命令（如 ping 或 curl）来检查网络连通性。
+    - 检查容器网络配置：确认容器内是否有网络连接。可以尝试在容器内执行网络测试命令（如 ping 或 curl）来检查网络连通性。
+
+### 2.5 添加模型失败提示 balance 相关内容
+
+!!! Abstract ""
+    在对应的平台上检查模型可用性，确保模型有余额可调用。
+
+### 2.6 添加模型失败提示 'str' object has no attribute 'model_dump 或者 Invalid API-key provided
+
+!!! Abstract ""
+    核实API域名和密钥：确保 API 域名是可用且配置正确的，并且对应的 API Key 是有效的、具有足够权限的。如果是第三方代理服务，可能需要联系其提供方确认服务状态和配置要求。

docs/img/FAQ/使用高级分段.png

@@ -105,6 +105,9 @@ nav:
     - 常见问题:
         - 安装部署: faq/install_configuration.md
         - 系统管理: faq/system_management.md
+        - 函数库: faq/function_library.md
+        - 知识库: faq/knowledge_base.md
+        - 应用: faq/apply_setting.md
     - 实践教程:
             - Ollama 离线部署 LLM 模型: faq/Offline_install_OllamaModel.md
             - Ollama 使用 GPU 运行 LLM 模型: faq/GPU_runOllama.md