4.7 doc update (#1068)

* fix: plugin update * feat: get current time plugin * fix: ts * perf: select app ux * fix: ts * perf: max w * move code * perf: inform tip * fix: inform * doc * fix: tool handle * perf: tmp file store * doc * fix: message file selector * feat: doc * perf: switch trigger * doc * fix: openapi import * rount the number * parse openapi schema * fix empty line after variables (#64) * doc image * image size * doc * doc * catch error --------- Co-authored-by: heheer <71265218+newfish-cmyk@users.noreply.github.com>
2025-07-23 21:13:50 +00:00 · 2024-03-27 12:50:07 +08:00
parent c7e6448272
commit 6b7b03c245
160 changed files with 1393 additions and 558 deletions
--- a/docSite/content/docs/development/configuration.md
+++ b/docSite/content/docs/development/configuration.md
@@ -26,7 +26,7 @@ llm模型全部合并
  },
  "llmModels": [
    {
-      "model": "gpt-3.5-turbo", // 模型名
+      "model": "gpt-3.5-turbo", // 模型名(对应OneAPI中渠道的模型名)
      "name": "gpt-3.5-turbo", // 别名
      "avatar": "/imgs/model/openai.svg", // 模型的logo
      "maxContext": 16000, // 最大上下文
@@ -97,14 +97,16 @@ llm模型全部合并
  ],
  "vectorModels": [
    {
-      "model": "text-embedding-ada-002",
-      "name": "Embedding-2",
-      "avatar": "/imgs/model/openai.svg",
-      "charsPointsPrice": 0,
-      "defaultToken": 700,
-      "maxToken": 3000,
-      "weight": 100,
-      "defaultConfig":{}  // 默认配置。例如，如果希望使用 embedding3-large 的话，可以传入 dimensions:1024，来返回1024维度的向量。（目前必须小于1536维度）
+      "model": "text-embedding-ada-002", // 模型名（与OneAPI对应）
+      "name": "Embedding-2", // 模型展示名
+      "avatar": "/imgs/model/openai.svg", // logo
+      "charsPointsPrice": 0, // n积分/1k token
+      "defaultToken": 700, // 默认文本分割时候的 token
+      "maxToken": 3000, // 最大 token
+      "weight": 100, // 优先训练权重
+      "defaultConfig":{},  // 自定义额外参数。例如，如果希望使用 embedding3-large 的话，可以传入 dimensions:1024，来返回1024维度的向量。（目前必须小于1536维度）
+      "dbConfig": {}, // 存储时的额外参数（非对称向量模型时候需要用到）
+      "queryConfig": {} // 参训时的额外参数
    }
  ],
  "reRankModels": [],
--- a/docSite/content/docs/development/docker.md
+++ b/docSite/content/docs/development/docker.md
@@ -96,11 +96,13 @@ curl -O https://raw.githubusercontent.com/labring/FastGPT/main/projects/app/data

 ## 三、启动容器

-在 docker-compose.yml 同级目录下执行
+在 docker-compose.yml 同级目录下执行。请确保`docker-compose`版本最好在2.17以上，否则可能无法执行自动化命令。

 ```bash
 # 启动容器
 docker-compose up -d
+# 等待10s，OneAPI第一次总是要重启几次才能连上Mysql
+sleep 10
 # 重启一次oneapi(由于OneAPI的默认Key有点问题，不重启的话会提示找不到渠道，临时手动重启一次解决，等待作者修复)
 docker restart oneapi
 ```
@@ -109,7 +111,7 @@ docker restart oneapi

 可以通过`ip:3001`访问OneAPI，默认账号为`root`密码为`123456`。

-在OneApi中添加合适的AI模型渠道。
+在OneApi中添加合适的AI模型渠道。[点击查看相关教程](/docs/development/one-api/)

 ## 五、访问 FastGPT

--- a/docSite/content/docs/development/faq.md
+++ b/docSite/content/docs/development/faq.md
@@ -12,9 +12,8 @@ images: []
 遇到问题先按下面方式排查。

 1. `docker ps -a` 查看所有容器运行状态，检查是否全部 running，如有异常，尝试`docker logs 容器名`查看对应日志。
-2. 不懂 docker 不要瞎改端口，只需要改`OPENAI_BASE_URL`和`CHAT_API_KEY`即可。
-3. 容器都运行正常的，`docker logs 容器名` 查看报错日志
-4. 无法解决时，可以找找[Issue](https://github.com/labring/FastGPT/issues)，或新提 Issue，私有部署错误，务必提供详细的日志，否则很难排查。
+2. 容器都运行正常的，`docker logs 容器名` 查看报错日志
+3. 无法解决时，可以找找[Issue](https://github.com/labring/FastGPT/issues)，或新提 Issue，私有部署错误，务必提供详细的日志，否则很难排查。


 ## 二、通用问题
@@ -29,7 +28,8 @@ images: []

 ### 其他模型没法进行问题分类/内容提取

-需要给其他模型配置`toolChoice=false`，就会默认走提示词模式。目前内置提示词仅针对了商业模型API进行测试，国内外的商业模型基本都可用。
+需要给其他模型配置`toolChoice=false`，就会默认走提示词模式。目前内置提示词仅针对了商业模型API进行测试。
+问题分类基本可用，内容提取不太行。
   
 ### 页面崩溃

@@ -48,7 +48,7 @@ images: []
 2. 如果是国内模型，可能是命中风控了。
 3. 查看模型请求日志，检查出入参数是否异常。

-### 知识库索引没有进度
+### 知识库索引没有进度/索引很慢

 先看日志报错信息。有以下几种情况：

@@ -62,15 +62,27 @@ images: []

 或者是FastGPT请求不到 OneAPI（没放同一个网络）

+### 修改了 vectorModels 但是没有生效
+
+1. 重启容器，确保模型配置已经加载（可以在日志或者新建知识库时候看到新模型）
+2. 记得刷新一次浏览器。
+3. 如果是已经创建的知识库，需要删除重建。向量模型是创建时候绑定的，不会动态更新。
+
 ## 三、常见的 OneAPI 错误

+带有 requestId 的都是 OneAPI 的报错。
+
 ### insufficient_user_quota user quota is not enough 

 OneAPI 账号的余额不足，默认 root 用户只有 200 刀，可以手动修改。

 ### xxx渠道找不到

-OneAPI 中没有配置该模型渠道。或者是修改了配置文件中一部分的模型，但没有全部修改。
+FastGPT 模型配置文件中的 model 必须与 OneAPI 渠道中的模型对应上，否则就会提示这个错误。可检查下面内容：
+
+1. OneAPI 中没有配置该模型渠道，或者被禁用了。
+2. 修改了 FastGPT 配置文件中一部分的模型，但没有全部修改，仍有模型是 OneAPI 没配置的。
+3. 使用旧的向量模型创建了知识库，后又更新了向量模型。这时候需要删除以前的知识库，重建。

 如果OneAPI中，没有配置对应的模型，`config.json`中也不要配置，否则容易报错。

--- a/docSite/content/docs/development/intro.md
+++ b/docSite/content/docs/development/intro.md
@@ -54,11 +54,11 @@ Mongo 数据库需要注意，需要注意在连接地址中增加 `directConnec

 以下文件均在 `projects/app` 路径下。

-**环境变量**
+**1. 环境变量**

 复制`.env.template`文件，在同级目录下生成一个`.env.local` 文件，修改`.env.local` 里内容才是有效的变量。变量说明见 .env.template

-**config 配置文件**
+**2. config 配置文件**

 复制 `data/config.json` 文件，生成一个 `data/config.local.json` 配置文件，具体配置参数说明，可参考 [config 配置说明](/docs/development/configuration)

@@ -73,7 +73,7 @@ Mongo 数据库需要注意，需要注意在连接地址中增加 `directConnec
 ### 5. 运行

 ```bash
-# 给脚本代码执行权限
+# 给自动化脚本代码执行权限(非 linux 系统, 可以手动执行里面的 postinstall.sh 文件内容)
 chmod -R +x ./scripts/
 # 代码根目录下执行，会安装根 package、projects 和 packages 内所有依赖
 pnpm i
--- a/docSite/content/docs/development/one-api.md
+++ b/docSite/content/docs/development/one-api.md
@@ -1,6 +1,6 @@
 ---
 title: '部署和使用OneAPI，实现Azure、ChatGLM、本地模型接入'
-description: '部署和使用OneAPI，实现Azure、ChatGLM、本地模型接入'
+description: '部署和使用OneAPI，实现Azure、ChatGLM、本地模型接入。OneAPI使用教程'
 icon: 'Api'
 draft: false
 toc: true
@@ -41,7 +41,7 @@ SqlLite 版本不支持多实例，适合个人小流量使用，但是价格非

 **2. 打开 AppLaunchpad(应用管理) 工具**

-![step1](/imgs/oneapi-step1.jpg)
+![step1](/imgs/oneapi-step1.webp)

 **3. 点击创建新应用**

@@ -71,6 +71,13 @@ BATCH_UPDATE_INTERVAL=60
   2. OneAPI 会根据请求传入的`模型`来决定使用哪一个`Key`，如果一个模型对应了多个`Key`，则会随机调用。
 2. 令牌：访问 OneAPI 所需的凭证，只需要这`1`个凭证即可访问`OneAPI`上配置的模型。因此`FastGPT`中，只需要配置`OneAPI`的`baseurl`和`令牌`即可。

+### 大致工作流程
+
+1. 客户端请求 OneAPI
+2. 根据请求中的 `model` 参数，匹配对应的渠道（根据渠道里的模型进行匹配，必须完全一致）。如果匹配到多个渠道，则随机选择一个（同优先级）。
+3. OneAPI 向真正的地址发出请求。
+4. OneAPI 将结果返回给客户端。
+
 ### 1. 登录 One API

 打开 【One API 应用详情】，找到访问地址：
@@ -81,7 +88,7 @@ BATCH_UPDATE_INTERVAL=60

 ### 2. 创建渠道和令牌

-在 One API 中添加对应渠道，直接点击 【添加基础模型】，不要遗漏了向量模型
+在 One API 中添加对应渠道，直接点击 【添加基础模型】，不要遗漏了向量模型（Embedding）
 ![step6](/imgs/oneapi-step6.png)

 创建一个令牌
@@ -112,7 +119,7 @@ CHAT_API_KEY=sk-xxxxxx

 ### 2. 修改 FastGPT 配置文件

-可以在 `/projects/app/src/data/config.json` 里找到配置文件（本地开发需要复制成 config.local.json），配置文件中有一项是对话模型配置：
+可以在 `/projects/app/src/data/config.json` 里找到配置文件（本地开发需要复制成 config.local.json），配置文件中有一项是**对话模型配置**：

 ```json
 "llmModels": [
@@ -144,6 +151,24 @@ CHAT_API_KEY=sk-xxxxxx
 ],
 ```

+**添加向量模型:**
+
+```json
+"vectorModels": [
+  ......
+    {
+      "model": "text-embedding-ada-002",
+      "name": "Embedding-2",
+      "avatar": "/imgs/model/openai.svg",
+      "charsPointsPrice": 0,
+      "defaultToken": 700,
+      "maxToken": 3000,
+      "weight": 100
+    },
+  ......
+]
+```
+
 ### 3. 重启 FastGPT

 ```bash
--- a/docSite/content/docs/development/openapi/dataset.md
+++ b/docSite/content/docs/development/openapi/dataset.md
@@ -9,7 +9,7 @@ weight: 853

 | 如何获取知识库ID（datasetId） | 如何获取文件集合ID（collection_id） |
 | --------------------- | --------------------- |
-| ![](/imgs/getDatasetId.jpg) | ![](/imgs/getfile_id.png) |
+| ![](/imgs/getDatasetId.jpg) | ![](/imgs/getfile_id.webp) |



--- a/docSite/content/docs/development/proxy/nginx.md
+++ b/docSite/content/docs/development/proxy/nginx.md
@@ -15,7 +15,7 @@ weight: 951

 打开 「应用管理」，点击「新建应用」：

-![](/imgs/sealos3.jpg)  
+![](/imgs/sealos3.webp)  
 ![](/imgs/sealos4.png)

 ### 填写基本配置
--- a/docSite/content/docs/development/upgrading/47.md
+++ b/docSite/content/docs/development/upgrading/47.md
@@ -7,13 +7,45 @@ toc: true
 weight: 826
 ---

-## 修改配置文件
+## 1. 修改配置文件

 增加一些 Boolean 值，用于决定不同功能块可以使用哪些模型，同时增加了模型的 logo：[点击查看最新的配置文件](/docs/development/configuration/)

-## 初始化脚本
+## 2. Docker 部署的用户, 修改 docker-compose.yml 文件

-从任意终端，发起 1 个 HTTP 请求。其中 {{rootkey}} 替换成环境变量里的 `rootkey`；{{host}} 替换成自己域名
+在 fastgpt 容器中，挂在一个目录，用于存储临时文件（文件上传时候）。可以参考最新的 [docker-compose.yml](https://raw.githubusercontent.com/labring/FastGPT/main/files/deploy/fastgpt/docker-compose.yml) 
+
+```yaml
+......
+    fastgpt:
+        ......
+        volumes:
+            - ./config.json:/app/data/config.json
+            - ./fastgpt/tmp:/app/tmp
+......
+```
+
+## 2. Sealos 部署的用户，挂载存储券
+
+| Step1 | Step 2 | Step3 |
+| --- | --- | --- |
+| ![](/imgs/47-sealos1.png) | ![](/imgs/47-sealos2.png) | ![](/imgs/47-sealos3.png) |
+| Step4 | Step 5 |  |
+| ![](/imgs/47-sealos4.webp) | ![](/imgs/47-sealos5.png) | 完工，检查下应用状态 |
+
+命令如下：
+
+```bash
+kubectl patch statefulset {{这里改成第一步的应用名}} -p '{"spec":{"template":{"spec":{"securityContext":{"fsGroup": 1001, "fsGroupChangePolicy": "Always"}}}}}'
+
+# 例如下面的
+# kubectl patch statefulset fastgpt-test -p '{"spec":{"template":{"spec":{"securityContext":{"fsGroup": 1001, "fsGroupChangePolicy": "Always"}}}}}'
+```
+
+
+## 3. 初始化脚本
+
+升级完镜像后。从任意终端，发起 1 个 HTTP 请求。其中 {{rootkey}} 替换成环境变量里的 `rootkey`；{{host}} 替换成自己域名

 ```bash
 curl --location --request POST 'https://{{host}}/api/admin/initv47' \
@@ -24,7 +56,7 @@ curl --location --request POST 'https://{{host}}/api/admin/initv47' \
 脚本功能：
 1. 初始化插件的 parentId

-## 升级 ReRank 模型
+## 4. 升级 ReRank 模型

 4.7对ReRank模型进行了格式变动，兼容 cohere 的格式，可以直接使用 cohere 提供的 API。如果是本地的 ReRank 模型，需要修改镜像为：`luanshaotong/reranker:v0.2` 。

@@ -52,12 +84,19 @@ cohere的重排模型对中文不是很好，感觉不如 bge 的好用，接入
 1. 新增 - 工具调用模块，可以让LLM模型根据用户意图，动态的选择其他模型或插件执行。
 2. 新增 - 分类和内容提取支持 functionCall 模式。部分模型支持 functionCall 不支持 ToolCall，也可以使用了。需要把 LLM 模型配置文件里的 `functionCall` 设置为 `true`， `toolChoice`设置为 `false`。如果 `toolChoice` 为 true，会走 tool 模式。
 3. 新增 - HTTP插件，可实现OpenAPI快速生成插件。
-4. 优化 - 高级编排性能。
-5. 优化 - 抽离 Flow controller 到 packages。
-6. 优化 - AI模型选择。
-7. 修复 - 开源版重排选不上。
-8. 修复 - http 请求 body，不使用时，传入undefined。（会造成部分GET请求失败）
-9. 新增 - 支持 http url 使用变量。
-10. 修复 - 469 的提取的提示词容易造成幻觉。
-11. 修复 - PG HNSW索引未实际生效问题，本次更新后，搜索速度大幅度提升(但是可能会出现精度损失，如果出现精度损失需要参考PgVector文档，对索引进行调整)。详细见：https://github.com/pgvector/pgvector?tab=readme-ov-file#troubleshooting
-12. 新增 - Rerank 模型兼容 [cohere的格式](https://docs.cohere.com/reference/rerank-1)，可以直接使用 cohere 的 rerank 模型。
+4. 新增 - Rerank 模型兼容 [cohere的格式](https://docs.cohere.com/reference/rerank-1)，可以直接使用 cohere 的 rerank 模型。
+5. 新增 - Helm 安装。
+6. 优化 - 高级编排性能。
+7. 优化 - 抽离 Flow controller 到 packages。
+8. 优化 - AI模型选择。
+9. 优化 - 手动输入知识库弹窗。
+10. 优化 - 变量输入弹窗。
+11. 优化 - docker 部署，自动初始化副本集。
+12. 优化 - 浏览器读取文件自动推断编码，减少乱码情况。
+13. 修复 - 开源版重排选不上。
+14. 修复 - http 请求 body，不使用时，传入undefined。（会造成部分GET请求失败）
+15. 新增 - 支持 http url 使用变量。
+16. 修复 - 469 的提取的提示词容易造成幻觉。
+17. 修复 - PG HNSW索引未实际生效问题，本次更新后，搜索速度大幅度提升(但是可能会出现精度损失，如果出现精度损失需要参考PgVector文档，对索引进行调整)。详细见：https://github.com/pgvector/pgvector?tab=readme-ov-file#troubleshooting
+18. 修复Safari浏览器语音输入问题。
+19. 修复 - 自定义分割规则可输入正则特殊字符（之前输入的话，会导致前端崩溃）