## Code Structure
### Next.js
FastGPT uses Next.js page routing. To separate frontend and backend code, directories are split into global, service, and web subdirectories for shared, backend-only, and frontend-only code respectively.
### Monorepo
FastGPT uses pnpm workspace for its monorepo structure, with two main parts:
* projects/app - FastGPT main project
* packages/ - Submodules
* global - Shared code: functions, type declarations, and constants usable on both frontend and backend
* service - Server-side code
* web - Frontend code
* plugin - Custom workflow plugin code
### Domain-Driven Design (DDD)
FastGPT's code modules follow DDD principles, divided into these domains:
* core - Core features (knowledge base, workflow, app, conversation)
* support - Supporting features (user system, billing, authentication, etc.)
* common - Base features (log management, file I/O, etc.)
Code Structure Details
``` . ├── .github // GitHub config ├── .husky // Formatting config ├── document // Documentation ├── files // External files, e.g., docker-compose, helm ├── packages // Subpackages │ ├── global // Frontend/backend shared subpackage │ ├── plugins // Workflow plugins (for custom packages) │ ├── service // Backend subpackage │ └── web // Frontend subpackage ├── projects │ └── app // FastGPT main project ├── python // Model code, unrelated to FastGPT itself └── scripts // Automation scripts ├── icon // Icon scripts: pnpm initIcon (write SVG to code), pnpm previewIcon (preview icons) └── postinstall.sh // ChakraUI custom theme TS type initialization ├── package.json // Top-level monorepo ├── pnpm-lock.yaml ├── pnpm-workspace.yaml // Monorepo declaration ├── Dockerfile ├── LICENSE ├── README.md ├── README_en.md ├── README_ja.md ├── dev.md ```
## 代码结构说明
### nextjs
FastGPT 使用了 nextjs 的 page route 作为框架。为了区分好前后端代码，在目录分配上会分成 global, service, web 3 个自目录，分别对应着 `前后端共用`、`后端专用`、`前端专用` 的代码。
### monorepo
FastGPT 采用 pnpm workspace 方式构建 monorepo 项目，主要分为两个部分：
* projects/app - FastGPT 主项目
* packages/ - 子模块
* global - 共用代码，通常是放一些前后端都能执行的函数、类型声明、常量。
* service - 服务端代码
* web - 前端代码
* plugin - 工作流自定义插件的代码
### 领域驱动模式（DDD）
FastGPT 在代码模块划分时，按 DDD 的思想进行划分，主要分为以下几个领域：
* core - 核心功能（知识库，工作流，应用，对话）
* support - 支撑功能（用户体系，计费，鉴权等）
* common - 基础功能（日志管理，文件读写等）
代码结构说明
``` . ├── .github // github 相关配置 ├── .husky // 格式化配置 ├── document // 文档 ├── files // 一些外部文件，例如 docker-compose, helm ├── packages // 子包 │ ├── global // 前后端通用子包 │ ├── plugins // 工作流插件（需要自定义包时候使用到） │ ├── service // 后端子包 │ └── web // 前端子包 ├── projects │ └── app // FastGPT 主项目 ├── python // 存放一些模型代码，和 FastGPT 本身无关 └── scripts // 一些自动化脚本 ├── icon // icon预览脚本，可以在顶层 pnpm initIcon(把svg写入到代码中), pnpm previewIcon（预览icon） └── postinstall.sh // chakraUI自定义theme初始化 ts 类型 ├── package.json // 顶层monorepo ├── pnpm-lock.yaml ├── pnpm-workspace.yaml // monorepo 声明 ├── Dockerfile ├── LICENSE ├── README.md ├── README_en.md ├── README_ja.md ├── dev.md ```| Protocol/Feature | SSO | Member Sync Support |
|---|---|---|
| Lark | Yes | Yes |
| WeCom | Yes | Yes |
| DingTalk | Yes | No |
| SAML 2.0 | Yes | No |
| OAuth 2.0 | Yes | No |
| WeCom | DingTalk | Lark |
|---|---|---|
|  |  |  |
| 协议/功能 | SSO | 成员同步支持 |
|---|---|---|
| 飞书 | 是 | 是 |
| 企业微信 | 是 | 是 |
| 钉钉 | 是 | 否 |
| Saml2.0 | 是 | 否 |
| Oauth2.0 | 是 | 否 |
| 企业微信 | 钉钉 | 飞书 |
|---|---|---|
|  |  |  |
| Team Mode | SMS/Email Registration | Admin Direct Add | SSO Registration | |||
|---|---|---|---|---|---|---|
| Creates Default Team | Joins Root Team | Creates Default Team | Joins Root Team | Creates Default Team | Joins Root Team | |
| Single-team Mode | ❌ | ✅ | ❌ | ✅ | ❌ | ✅ |
| Multi-team Mode | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
| Sync Mode | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 团队模式 | 短信/邮箱 注册 | 管理员直接添加 | SSO 注册 | |||
|---|---|---|---|---|---|---|
| 是否创建默认团队 | 是否加入 Root 团队 | 是否创建默认团队 | 是否加入 Root 团队 | 是否创建默认团队 | 是否加入 Root 团队 | |
| 单团队模式 | ❌ | ✅ | ❌ | ✅ | ❌ | ✅ |
| 多团队模式 | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
| 同步模式 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
* 🐞 Submit any FastGPT bugs, issues, or feature requests to [GitHub Issues](https://github.com/labring/fastgpt/issues/new/choose).
file: ./content/guide/getting-started/index.mdx
meta: {
"title": "快速了解 FastGPT",
"description": "FastGPT 的能力与优势"
}
import { Alert } from '@/components/docs/Alert';
import FastGPTLink from '@/components/docs/linkFastGPT';
FastGPT 是一个基于大语言模型的 AI Agent 应用开发平台，集知识库问答、可视化工作流、Agent 编排、工具调用和技能扩展于一体，让开发者和业务人员都能快速构建专属 AI 应用。
* 🐞 请将任何 FastGPT 的 Bug、问题和需求提交到 [GitHub Issue](https://github.com/labring/fastgpt/issues/new/choose)。
file: ./content/guide/getting-started/quick-start.en.mdx
meta: {
"title": "Quick Start",
"description": "Quickly experience FastGPT through four use cases: Conversational Agent, Knowledge Base, Workflow, and Agent V2"
}
This article uses four complete use cases to help you quickly understand FastGPT's core application types and complete the basic setup from simple conversations to complex task orchestration.
This page is suitable for first-time FastGPT users, as well as pre-sales, delivery, operations, legal, and administrative roles who want to quickly experience the platform's capabilities. After completing this page, you will build the following in order:
1. Conversational Agent: Corporate email writing assistant.
2. Knowledge Base + Conversational Agent: Civil Code Q\&A assistant.
3. Workflow: Content review and automatic rewriting.
4. Agent V2: Intelligent data analysis Agent.
We recommend preparing the following in advance:
* An available AI model, such as GLM-5.1 or other configured models.
* A knowledge base test file, such as the Civil Code, company policies, product manuals, etc.
* If you want to test the Email tool, prepare an email SMTP authorization code.
* If you want to test Agent V2 data analysis, prepare a sample Excel or CSV file.
When reading, focus on three things: what kind of problems each application type is suitable for, why the key configurations are written this way, and what to observe during validation. The parameters and prompts in this article are reusable starting points; for production deployment, you can replace them with your own business materials, review rules, notification channels, and data files.
## Case 1: Conversational Agent — Corporate Email Writing Assistant
### 1.1 Use Cases
Conversational Agents are suitable for lightweight Q\&A, content generation, copy refinement, and standardized output. This case does not link a knowledge base or rely on complex workflows; it simply uses model configuration, prompts, and an Email tool to build a corporate email writing assistant.
Employees often need to handle emails for project updates, cross-departmental collaboration, customer replies, meeting minutes, and more. Using AI to standardize email formats and expression styles can improve writing efficiency and maintain the professionalism of external corporate communications.
The focus of this case is not to have the AI randomly generate an email, but to consolidate the stable requirements of corporate email writing into the prompt, such as subject lines, salutations, body structure, action items, and risk reminders. For beginners, it also serves as a minimal closed loop for understanding FastGPT application configuration: first define the role, then constrain the output, and finally extend execution actions through tools.
### 1.2 Configuration Steps
1. **Create a Conversational Agent**
Click "New" in the workspace, select "Conversational Agent", and fill in the application name as `Corporate Email Writing Assistant`.
2. **Enter the Application Configuration Page**
After creation, enter the application configuration page. The page is usually divided into left and right columns: the left is AI configuration, and the right is debug preview.
3. **Select a Model**
In the AI configuration, select the base model for the Conversational Agent. This case uses GLM-5.1, but you can replace it with other available models configured in your current environment.
When selecting a model, prioritize two aspects: first, whether the model is good at business writing, and second, whether it consistently follows the required format. Email writing is a low-risk, low-structure task, so you usually do not need the strongest model available, but you should still choose one with a natural tone and reliable instruction following.
4. **Write the Prompt**
The prompt needs to clearly describe the assistant's role, output format, and constraints. You can use the following example:
```md
You are a corporate email writing expert, helping employees write professional, clear, and appropriate work emails.
Output format:
- **Subject line**: Concise and clear
- **Salutation**: Choose "Dear Mr./Ms. XX" or "Hi XX" based on the relationship with the recipient
- **Body**: Three-part structure (Background → Core content → Action items)
- **Sign-off**: Name, Title, Department
Rules:
- Keep the body between 200-500 words
- List action items and to-dos with bullet points
- When involving sensitive content like salary, HR, or legal matters, remind the user to send with caution
- Use a neutral and polite tone when unsure of the relationship with the recipient
```
Write the prompt into the prompt module.
This prompt consists of three parts: the role definition stabilizes the assistant's identity, the output format constrains the email structure, and the rules control risk boundaries. In actual business, you can continue to add corporate tone requirements, brand terminology, banned words, signature formats, and more to make the output more aligned with internal standards.
5. **Add the Email Tool**
Tools encapsulate complex operations. This case uses the Email sending tool to give the AI assistant the ability to send emails after generating them. Click the plus sign on the right side of the tools and select "Send Email".
You can think of tools as the AI's external capabilities. Without tools, the assistant can only generate the email body; after adding the Email tool, the assistant can execute the sending action after user confirmation. In a production environment, it is recommended to have the assistant generate an email draft first, and then have the user confirm the sending, to avoid accidental sending or sending to the wrong recipient.
6. **Configure the Email Tool**
Enter the tool configuration page and fill in the parameters related to the email service.
7. **Activate the Tool**
Click "Settings" to enter the tool activation page, then click "Activate Tool".
8. **Fill in the Email SMTP Information**
This case uses QQ Mail as an example. When testing, you can fill it out as follows:
```text
SMTP Server Address: smtp.qq.com
SMTP Port: 465
Enable SSL
SMTP Username: Email address
SMTP Password: Authorization code
```
For the authorization code, please refer to the [Authorization Code Acquisition Tutorial](https://cloud.tencent.com/developer/article/2177098).
9. **Set the Conversation Opening**
The conversation opening is used to tell users what this AI assistant can do. You can fill in:
```text
Hello! I am the Email Writing Assistant 📧
Please tell me: Who is the recipient? What is the purpose of the email? What key information needs to be included?
I will help you generate a professional and appropriate email.
```
After filling it out, you can see the effect in the preview area on the right.
10. **Validate the Result**
After configuration, enter your email requirements in the debug preview to check whether the assistant can generate an email with a clear structure and appropriate tone.
If the user's information is insufficient, the assistant should proactively prompt to supplement the recipient, email purpose, key information, etc.
When verifying, it is recommended to test at least three types of inputs: an email requirement with complete information, a vague requirement missing the recipient or purpose, and an email requirement containing sensitive information. An email assistant ready for production not only needs to be able to "write", but also needs to be able to ask follow-up questions when information is insufficient, and remind users to send with caution in sensitive scenarios.
### 1.3 Business Value
* **Improve Writing Efficiency**: Transform high-frequency emails like project updates, customer follow-ups, and meeting minutes from "writing from scratch" to "generating after filling in key information", reducing repetitive labor.
* **Unify Communication Standards**: Consolidate standards for salutations, body structure, action items, and sign-offs into the Prompt, reducing the communication costs caused by differences in writing styles among employees.
* **Reduce Sending Risks**: Add sensitive information reminders, missing information follow-ups, and neutral tone constraints through the Prompt to reduce incomplete, inappropriate, or over-promising emails.
* **Expand Office Automation**: Combined with the Email tool, you can continue to integrate office workflows such as notifications, approvals, Lark, DingTalk, and WeCom, extending email writing from content generation to business action execution.
## Case 2: Knowledge Base + Conversational Agent — Civil Code Q\&A Assistant
### 2.1 Use Cases
A knowledge base is ideal for scenarios where answers must be based on provided materials, such as policy Q\&A, product manual Q\&A, legal article retrieval, and customer service knowledge support. Without a knowledge base, the AI primarily relies on its own model capabilities to answer questions. Once a knowledge base is connected, the AI first searches your materials and then organizes answers based on the search results.
In this case, we import the *Civil Code of the People's Republic of China* into the knowledge base and create a Civil Code Q\&A assistant. When users ask questions in natural language, the assistant should prioritize citing the original Civil Code text to reduce fabricated responses.
Think of the knowledge base as a "reference room" configured for the AI. The model itself has general knowledge but doesn't know your company policies, product details, internal processes, or specific regulatory versions. The knowledge base turns these materials into searchable content, allowing the AI to look up information before organizing an answer. For legal, policy, customer service, and after-sales scenarios, this is more controllable than relying solely on the model's memory.
### 2.2 Preparation
* Example file: Prepare a copy of the *Civil Code of the People's Republic of China* or another regulatory/documentation file.
* A usable conversation model and vector model.
* A legal question for testing, e.g., "My lease isn't up yet, but the landlord wants to sell the house. What should I do?"
### 2.3 Configuration Steps
1. **Create a Knowledge Base**
Click **Knowledge Base** on the left side of the homepage, then click **New** in the top right corner. Name the knowledge base `Civil Code Q&A Assistant`. Keep the other default settings for this case.
2. **Create a Text Dataset**
Click **New**, then select **Text Dataset** to import local documents.
3. **Upload a Local File**
Click **Upload Local File** and select the example file. In real use, you can upload multiple files at once; for this case, we upload only one file as a demonstration.
4. **Set Parsing Parameters**
After entering the parameter settings page, choose the parsing method based on the file type.
Recommended common settings:
* **File Parsing Settings**: Enable when uploading PDFs; for regular Word, Markdown, TXT files, start with the default configuration.
* **Processing Method**: For most scenarios, choose chunked storage — it's lower cost and faster for retrieval.
* **Chunking Conditions**: Controls how many tokens each chunk contains. Use the default values for quick testing.
* **Index Enhancement**: For plain text, usually check the first two options; if the document contains images, enable image-related enhancements.
These parameters directly affect the quality of subsequent Q\&A. If chunks are too large, search results may include too much irrelevant content, making answers verbose. If chunks are too small, key context may be split, causing answers to lack supporting evidence. For the quick-start phase, use the default configuration. When officially integrating enterprise policies, contracts, or product manuals, adjust these parameters gradually based on Q\&A performance.
5. **Preview Chunking Results**
After reaching the data preview step, check whether the chunks are complete and readable. If chunks are too long or too short, go back and adjust the parameters.
When previewing chunks, focus on three things: whether paragraphs are abnormally cut off, whether titles and body text remain within the same semantic range, and whether tables, clauses, or numbering are still readable. If the quality of these knowledge fragments is unstable, even a well-written Prompt in the application will struggle to consistently produce accurate answers.
6. **Wait for the Knowledge Base to Be Ready**
Once the data status changes to "Ready," the knowledge base can be referenced by applications.
7. **Create and Link a Conversational Agent**
Create a new Conversational Agent, also named `Civil Code Q&A Assistant`. After creation, link the knowledge base you just created in the application configuration.
After linking the knowledge base, the application's response flow changes from simple conversation to "user question → knowledge base search → model summarizes answer." This is the key difference between Case 1 and Case 2: Case 1 emphasizes content generation, while Case 2 emphasizes answering based on provided materials.
8. **Configure the Q\&A Prompt**
The Civil Code Q\&A assistant needs to emphasize "answer based on the knowledge base" and "cite the original text." You can use the following Prompt:
```md
You are a professional Civil Code Q&A assistant, answering legal questions based on the original text of the _Civil Code of the People's Republic of China_.
Rules:
- Strictly answer based on the Civil Code articles retrieved from the knowledge base; do not fabricate legal provisions.
- Every answer must cite the original Civil Code text (book, chapter, article).
- If there is no directly corresponding provision in the Civil Code, state this honestly and do not give legal advice.
- When applying the law to specific cases, remind the user: "This answer is for reference only; please consult a professional lawyer."
- Provide plain-language explanations of legal terms so that users without a legal background can understand.
Output format:
1. **Legal Conclusion** (1–3 sentence summary)
2. **Relevant Article Citation** (original excerpt + book/chapter/article number)
3. **Plain-Language Explanation** (explain the meaning of the article in everyday language)
4. **Practical Advice** (2–3 actionable suggestions)
5. **Disclaimer** ("This answer is based on the original Civil Code text and does not constitute legal advice. For specific cases, please consult a professional lawyer.")
```
For legal Q\&A scenarios, it's especially important to define boundaries: what can be answered is a general explanation based on the materials; the model's output should never be packaged as formal legal advice. Requiring article citations, stating uncertainty, and adding disclaimers in the Prompt all aim to make the output more traceable and compliant with high-risk knowledge Q\&A usage norms.
9. **Configure the Opening Message**
The opening greeting can include a few example questions to help users quickly understand how to use this assistant:
```text
Hello! I'm the Civil Code Q&A Assistant ⚖️
I answer legal questions based on the original text of the *Civil Code of the People's Republic of China*.
You can ask me:
["My lease isn't up yet, but the landlord wants to sell the house. What should I do?"]
["I received a product I bought online and it was broken, but the seller won't accept a return. What does the law say?"]
["The upstairs neighbor's leak soaked my ceiling. Can I claim compensation?"]
⚠️ Note: My answers are for reference only. For specific legal issues, please consult a professional lawyer.
```
If you add `[question content]` in the opening greeting, users can click the question to ask it directly — useful for demonstrations and guidance.
10. **Verify Q\&A Performance**
Ask a question related to the Civil Code and check whether the answer includes a legal conclusion, article citation, plain-language explanation, and disclaimer.
When verifying, don't just check whether the answer "looks like a legal answer" — also check whether it actually references the knowledge base content. It's recommended to test with questions inside the materials, outside the materials, and ambiguous questions: questions inside the materials should cite the original text; questions outside the materials should state that a direct confirmation is not possible; ambiguous questions should proactively prompt the user to provide more facts.
### 2.4 Business Value
* **Lower the barrier to material retrieval**: Turn lengthy regulations, policies, and manuals into a natural language Q\&A entry point, allowing business users to quickly find relevant content without needing to know keywords or directory locations first.
* **Improve answer credibility**: Through knowledge base retrieval and original text citations, answers have a source basis, reducing the risk of the model fabricating or giving vague responses based on experience.
* **Accumulate organizational knowledge**: Internal company policies, product FAQs, after-sales SOPs, contract templates, and other materials can be continuously added to the knowledge base, forming maintainable and reusable knowledge assets.
* **Adapt to high-frequency support scenarios**: Legal, HR, administrative, customer service, and delivery teams can all use a similar model to turn repetitive inquiries into self-service Q\&A, improving response efficiency.
## Case 3: Workflow — Content Review and Automatic Rewriting
### 3.1 Use Cases
Workflows are ideal for tasks with fixed steps, clear logic, and the need for branching decisions or human confirmation. This case breaks down content compliance review into several stages: knowledge base retrieval, AI classification, conditional branching, automatic rewriting, rejection explanation, and human confirmation, simulating the review process before enterprise content is published.
Its core value lies in two aspects:
1. **Automation**: Once triggered, the system automatically executes multiple steps according to the preset workflow.
2. **Standardization**: The same input goes through the same judgment and processing, reducing human variability.
To determine whether a task is suitable for a workflow, check if it has three characteristics: "stable steps, clear rules, and repeatable execution." Content review is a typical scenario: the input is content to be published, the rules come from a compliance knowledge base, and the output is usually pass, rewrite, or reject, with the option to add human confirmation in between. This improves processing efficiency while retaining risk control.
### 3.2 Preparation
First, create a "Content Compliance Rules" knowledge base and upload a simple text file. You can directly use the following rule template:
```text
Content Compliance Rules
Safe Content (can be published directly)
- Objective factual statements
- Normal event notifications, meeting arrangements
- Product feature descriptions (based on real data)
- Industry knowledge sharing
Sensitive Wording (needs rewriting)
- Absolute language: "best," "first," "100%," "absolute," "only"
- Exaggerated claims: "disrupting the industry," "unprecedented," "unmatched"
- Unverified data: conversion rates, satisfaction rates, growth rates without sources
- Comparative disparagement: directly naming competitors and belittling them
Prohibited Content (must not be published)
- Illegal information: involving pornography, gambling, drugs, fraud, pyramid schemes
- Personal attacks: insults, defamation against individuals or groups
- False information: fabricated data, forged qualifications, impersonating official sources
- Sensitive topics: political sensitivity, religious discrimination, regional attacks
```
The rule base does not need to be complex at the start. For quick validation, split the rules into three categories: "safe, needs rewriting, prohibited." For formal use, you can continue adding rules by industry, brand, channel, or region, such as advertising-sensitive terms, medical compliance requirements, prohibited financial marketing claims, brand tone guidelines, and so on.
### 3.3 Workflow Design
Before configuring nodes, it's recommended to confirm the complete workflow. This case can be designed as follows:
1. **User Input**: As the workflow starting point, receives the content to be reviewed.
2. **Knowledge Base Retrieval**: Recalls relevant rules from the content compliance rules base. It is recommended to set the citation limit to 1-2 entries.
3. **AI Content Compliance Classification**: Combines user input and retrieval results to classify the content as "Safe / Sensitive but Rewritable / Prohibited."
4. **Conditional Branching**: Enters different branches based on the classification result.
5. **Safe Branch**: Directly outputs the original text, indicating it can be published.
6. **Sensitive but Rewritable Branch**: Calls AI to rewrite the content, then submits it for user confirmation.
7. **Prohibited Branch**: Outputs a rejection explanation and provides revision suggestions.
8. **Final Output**: Returns the original text, rewritten version, or rejection explanation.
When designing a workflow, first determine the responsibility of each node to avoid having a single AI node simultaneously handle "retrieving rules, judging classification, rewriting content, explaining reasons," etc. Once responsibilities are clearly separated, each node's prompt will be shorter and more stable, making it easier to locate issues later: whether the knowledge base failed to recall rules, the review node misclassified, or the condition in the decision node didn't match.
### 3.4 Configuration Steps
1. **Create a Workflow**
Go to the workflow homepage, click "New Workflow," and name it `Content Review and Automatic Rewriting`.
After creation, enter the workflow editing page.
The complete workflow diagram for this case is as follows:
2. **Configure the Opening Message**
In the system configuration, fill in the opening statement to explain the assistant's review rules and usage.
```md
Hello! I am the Content Compliance Review Assistant 🛡️
Please send me the content you need reviewed, and I will automatically judge it according to the rules:
- **✅ Safe** — Content has no sensitive information and can be published directly
- **⚠️ Sensitive but Rewritable** — Contains correctable wording; I will rewrite it and send it back for your confirmation
- **🚫 Prohibited** — Contains red-line content and is rejected with an explanation
Supports single text review or batch submission (multiple items separated by line breaks).
**Let's get started.**
```
3. **Call the Knowledge Base**
Add a knowledge base retrieval node in the workflow, select the previously created content compliance rules base. The input for this node uses the user input, and the output is referenced by subsequent AI nodes.
The purpose of this node is not to have the model read the entire rule base, but to retrieve the rule fragments most relevant to the current content for the subsequent review node. You can initially set the citation limit to 1-2 entries to keep the prompt context focused; if the rule base is larger or the categories are more detailed, gradually increase the citation count.
4. **Configure the Content Review Node**
Add an AI dialogue node and rename it to "Content Review Node." This node is responsible for outputting the classification result based on the user input and knowledge base rules.
```md
You are a content compliance review expert. Based on the compliance rules retrieved from the knowledge base, determine the compliance level of the user's input content.
Classification criteria:
- Safe: Content has no sensitive information and can be published directly
- Sensitive but Rewritable: Contains correctable sensitive wording; can be published after rewriting
- Prohibited: Contains red-line content and cannot be published
Output format:
Output only one of three labels: Safe / Sensitive but Rewritable / Prohibited
```
Note: The knowledge base reference must select the previously created knowledge base, otherwise the AI cannot read the rule content.
The output of the review node should be as stable as possible, because it directly affects the decision node's branching. For a quick demo, you can output only the three labels "Safe / Sensitive but Rewritable / Prohibited"; if you need stricter automation integration later, you can switch to structured output, such as returning the classification, reason, and matched rules together, making it easier for downstream nodes to perform precise matching and logging.
5. **Test the Review Node**
Click "Run" in the top right corner, input a piece of content to be reviewed, and confirm that the review node returns a stable classification result.
Test this node individually instead of waiting until the entire workflow is built. Input a normal event announcement, marketing copy containing absolute language, and clearly prohibited text, and observe whether the classification meets expectations. If the classification is unstable, first adjust the rule base wording and the review prompt before continuing to configure subsequent branches.
6. **Hide Intermediate Output**
Click the settings button on the right side of the model to adjust the node's basic settings. Since the user only needs the final result, it is recommended to hide the intermediate output of the content review node.
7. **Configure the Decision Node**
Add a decision node to branch based on the "Safe / Sensitive but Rewritable / Prohibited" output from the content review node.
The decision node acts as a switch in the workflow. The more stable the output from the previous step, the easier it is to configure the decision node; if the review node's output contains explanatory text, the condition may fail to match. Therefore, in branching workflows, it is common to first constrain the output format of the upstream node before configuring the decision node conditions.
8. **Configure the Safe Branch**
When the review result is "Safe," directly output the original text. In a production scenario, you could also add spot-checking or human confirmation.
The output effect is as follows:
9. **Configure the Sensitive but Rewritable Branch**
When the review result is "Sensitive but Rewritable," add an AI dialogue node to automatically rewrite the content. You can use the following prompt:
```md
You are a content rewriting expert. Rewrite the user's input content into a compliant version.
Rewriting principles:
- Preserve the original meaning and information, do not change the core expression
- Replace absolute language with objective statements, e.g., "best" → "industry-leading"
- Replace unverified data statements with reasonable speculation, e.g., "100% effective" → "most users report it effective"
- Replace sensitive wording with neutral expressions
- Maintain the original style and tone
```
After rewriting, you can add a user choice node to let the user accept the rewrite, continue rewriting, or abandon it.
The human confirmation node is suitable for paths that are risky but correctable. AI can propose rewrite suggestions, but whether to publish is still left to the business personnel to confirm. This reduces the time spent on initial screening and repeated revisions while not handing over the final publishing decision entirely to the automated workflow.
If the user accepts the rewrite, output the rewritten result; if the user chooses to continue rewriting, it can be connected back to the content rewriting node; if the user abandons it, output the original text.
10. **Configure the Prohibited Branch**
When the review result is "Prohibited," add an AI dialogue node to output a rejection explanation. You can use the following prompt:
```md
The content submitted by the user cannot be published because it contains prohibited information. Please explain the reason in a polite and professional tone.
Output format:
1. One sentence stating that the content cannot be published
2. List specific violation points (1-3 items)
3. Provide alternative suggestions (e.g., suggest which aspects to modify before resubmitting)
```
11. **Verify the Complete Workflow**
Input safe content, sensitive content, and prohibited content separately, and confirm that all three branches return the expected results.
When verifying the complete workflow, it is recommended to record the input, review classification, branch entered, and final output for each test case. If the output does not meet expectations, troubleshoot node by node: first check whether the knowledge base recalled the correct rules, then whether the review node classified accurately, and finally whether the decision node conditions and branch output are configured correctly.
### 3.5 Business Value
* **Standardize review rules into a workflow**: Embed the judgment criteria for pre-publication content review into a knowledge base and node configuration, reducing reliance on personal experience passed down verbally.
* **Improve processing efficiency**: Safe content can pass quickly, sensitive content is automatically rewritten, and prohibited content receives a direct explanation, allowing reviewers to focus on content that requires judgment.
* **Retain human control points**: Add user confirmation for gray-area scenarios like "sensitive but rewritable," preventing the automated workflow from making publishing decisions directly for business personnel.
* **Easy to reuse and extend**: The same workflow can be applied to marketing copy, customer service scripts, announcements, event pages, short video scripts, and other content review scenarios by replacing the rule base and a few prompts.
* **Reduce compliance risk**: Through fixed branches and rejection explanations, high-risk content has a clear interception path, reducing the risk of accidental publication, exaggerated claims, or non-compliant expressions.
## Case 4: Agent V2 — Intelligent Data Analysis Agent
### 4.1 Use Cases
Agent V2 is ideal for open-ended, multi-step tasks that require dynamic planning. Unlike workflows, where every step must be predefined, Agent V2 is better suited for tasks with “unfixed steps,” such as data analysis, file processing, multi-tool collaboration, and complex problems that require follow-up clarification.
This case simulates the daily data analysis needs of operations, product, or sales teams: upload an Excel file, ask questions in natural language, and let the Agent autonomously read the file, formulate an analysis plan, and execute the analysis in a virtual machine.
In Case 3, the workflow required you to design a fixed path of “retrieval rules → classification → branching → rewriting or rejection.” Agent V2, on the other hand, acts more like an autonomous executor. You don’t need to define every step in advance; just provide the goal and the file. The Agent decides whether to read the file first, perform statistics, ask follow-up questions, or run code based on the data structure and problem complexity.
Data analysis is a great way to experience Agent V2 because it naturally has three characteristics: the analysis path is not fixed, it often requires multi-step reasoning, and the requirements may need clarification. With the same Excel file, different users might care about product sales, channel ROI, regional trends, or anomalous orders. A fixed workflow can hardly cover all paths in advance, but Agent V2 can dynamically plan based on the question.
### 4.2 Preparation
* Sample file: Prepare a sales data Excel or CSV table.
* A conversation model that supports Agent V2.
* Virtual machine capability is available in the current environment.
### 4.3 Configuration Steps
1. **Create an Agent V2 Application**
In the workspace, click “Create Application,” select `Conversational Agent V2`, and name it `Intelligent Data Analysis Agent`.
2. **Configure Model and Prompt**
Continue using the GLM-5.1 model for AI configuration. The system prompt can refer to:
```md
You are a senior data analyst Agent. You can read data files uploaded by users, run Python analysis code in the sandbox, and proactively ask users for clarification.
Tools:
- 📄 **Read File** — Read Excel/CSV data uploaded by the user
- 💻 **Sandbox Execution** — Run Python scripts (pandas/matplotlib/numpy)
- ❓ **Proactive Follow-up** — Confirm with the user when analysis requirements are unclear
Workflow:
1. After receiving data and a question, first read the file to understand the data structure and content
2. Formulate an analysis plan and present it to the user as a list of steps
3. Execute step by step according to the plan, showing key findings at each step
4. Proactively ask follow-up questions when encountering ambiguous requirements, such as unclear metric definitions or missing comparison baselines
5. Dynamically update the plan based on follow-up results
6. Output an analysis report containing data overview, core findings, visual charts, and business recommendations
Security Rules:
- Only data analysis is allowed in the sandbox; no network access, no writing files to the host machine
- Data is used only for this analysis; do not expose raw sensitive data in the report
- Mark confidence levels for uncertain conclusions
Output Format:
1. 📋 Analysis Plan (automatically generated based on data)
2. 📊 Data Overview (row count, column names, missing values, basic statistics)
3. 🔍 Core Findings (3-5 key insights, supported by charts)
4. 💡 Business Recommendations (actionable suggestions based on data)
```
The key point of this prompt is to have the Agent plan before executing, rather than jumping straight to conclusions. For data analysis tasks, first reading the data structure, confirming field meanings, and formulating an analysis plan can significantly reduce the risk of misunderstanding requirements or misusing metrics. In production use, you can continue to supplement internal metric definitions, such as GMV, ROI, conversion rate, active customers, repurchase rate, etc.
3. **Configure the Opening Message**
The opening remarks guide the user to upload a data file and ask analysis questions:
```text
Hello! I am the Intelligent Data Analysis Agent 📊
Just drag and drop your Excel or CSV file here and tell me what you want to analyze.
For example:
- "Analyze this sales data and find the best-selling products and trends"
- "Help me look at changes in user activity and find the reasons for the decline"
- "Compare the conversion rates of three channels, which one has the highest ROI?"
I will first understand your data, formulate an analysis plan, and then run the analysis code in the sandbox.
I will proactively ask you for clarification when needed.
```
4. **Enable Virtual Machine Capability**
Data analysis usually requires reading files and executing code, so the virtual machine configuration needs to be enabled.
The virtual machine capability is used to isolate the code execution environment. The Agent can run data analysis scripts, read uploaded files, and generate statistical results within it, without directly affecting the local host environment. For scenarios that require running Python, processing Excel, drawing charts, or performing batch calculations, this is an important capability that distinguishes Agent V2 from ordinary conversation applications.
5. **Upload File and Test**
Upload the sample sales data file and enter the question:
```text
Help me analyze this sales data to see which products sell well and which channel has the highest ROI
```
The Agent will first break down the task and then execute the analysis step by step.
During execution, you can see the task running in the virtual machine without affecting the local environment.
When testing, focus on whether the Agent has a complete analysis process: does it first identify the table fields, explain the analysis plan, run code when needed, and give business recommendations based on the results? If the problem description is unclear, the ideal behavior is not to force an analysis but to first ask the user for key definitions.
### 4.4 Verification of Results
The final result should include the analysis plan, data overview, core findings, and business recommendations.
When verifying results, it is recommended to focus on four dimensions: whether the conclusions come from actual data, whether the metric definitions are clear, whether the charts or statistics support the conclusions, and whether the business recommendations are actionable. The value of a data analysis Agent is not just to output a summary, but to connect the process of “reading data, calculating metrics, explaining results, and proposing recommendations.”
### 4.5 Business Value
* **Lower the barrier to data analysis**: Business users can directly upload Excel or CSV files and ask questions in natural language, without needing to write SQL, Python, or complex formulas first.
* **Support open-ended exploration**: The same data can be repeatedly queried around sales, channels, regions, customers, trends, outliers, etc., suitable for scenarios without a fixed analysis path.
* **Increase analysis transparency**: The Agent shows the analysis plan and key steps, so users can see how it understands the data, calculates metrics, and draws conclusions.
* **Isolate code execution risk**: By executing analysis scripts in a virtual machine, risks of local environment contamination, dependency conflicts, and permission misuse are reduced.
* **Consolidate business analysis capabilities**: Scenarios such as sales reviews, weekly operations reports, campaign attribution, and product metric diagnostics can all reuse this type of Agent, turning data analysis from an expert task into a daily workflow.
## Choosing Between the Four Types
After completing the four cases, you can understand the common application types of FastGPT as a progression from simple to complex capabilities: Conversational Agent solves "how to answer and generate content," Knowledge Base solves "what materials to base answers on," Workflow solves "what fixed process to follow," and Agent V2 solves "how to autonomously plan and execute open-ended tasks."
| Application Type | Suitable Scenarios | Core Capabilities |
| ------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------ |
| Conversational Agent | Lightweight Q\&A, copywriting, standardized output | Prompt, model configuration, tool calling |
| Knowledge Base + Conversational Agent | Q\&A based on documents, policies, regulations, product manuals | File import, knowledge base retrieval, citing sources |
| Workflow | Fixed steps, conditional branches, review flows, automated processing | Node orchestration, decision nodes, human confirmation |
| Agent V2 | Data analysis, complex tasks, multi-step reasoning, dynamic planning | Autonomous planning, tool calling, virtual machine execution |
When selecting, you can judge based on task complexity:
1. If it's just lightweight conversation or standardized copy generation, prioritize the Conversational Agent.
2. If answers must be based on existing materials, choose Knowledge Base + Conversational Agent.
3. If the process is fixed and requires conditional branches, human confirmation, or automated processing, choose Workflow.
4. If the task is open-ended with unfixed steps and requires autonomous analysis, tool calling, or code execution, choose Agent V2.
In real projects, you can also combine these capabilities. For example, a customer service assistant can use a Knowledge Base to answer product questions and then query orders via tools; content review can use a Workflow to fix the review path while maintaining rules with a Knowledge Base; data analysis scenarios can first use Agent V2 for exploration, then solidify stable analysis steps into a Workflow.
file: ./content/guide/getting-started/quick-start.mdx
meta: {
"title": "快速上手",
"description": "通过对话 Agent、知识库、工作流和 Agent V2 四个案例快速体验 FastGPT"
}
本文通过四个完整案例，帮助你快速理解 FastGPT 的核心应用类型，并完成从简单对话到复杂任务编排的基础搭建。
本页适合第一次接触 FastGPT 的用户，也适合售前、交付、运营、法务、行政等角色快速体验平台能力。完成本页后，你将依次搭建：
1. 对话 Agent：企业邮件撰写助手。
2. 知识库 + 对话 Agent：民法典问答助手。
3. 工作流：内容审核与自动改写。
4. Agent V2：智能数据分析 Agent。
建议提前准备以下内容：
* 可用的 AI 模型，例如 GLM-5.1 或其他已配置模型。
* 一个知识库测试文件，例如民法典、公司制度、产品手册等。
* 如果要测试 Email 工具，准备邮箱 SMTP 授权码。
* 如果要测试 Agent V2 数据分析，准备一个 Excel 或 CSV 示例文件。
阅读时建议重点关注三件事：每种应用类型适合解决什么问题、关键配置为什么这样写、验证时应该观察哪些效果。本文中的参数和 Prompt 都是可复用的起点，正式落地时可以替换为你自己的业务资料、审核规则、通知渠道和数据文件。
## 案例一：对话 Agent—企业邮件撰写助手
### 1.1 适用场景
对话 Agent 适合轻量问答、内容生成、文案润色、标准化输出等场景。本案例不关联知识库，也不依赖复杂流程，只通过模型配置、Prompt 和 Email 工具完成一个企业邮件撰写助手。
企业员工经常需要处理项目同步、跨部门协作、客户回复、会议纪要等邮件。通过 AI 统一邮件格式和表达风格，可以提升写作效率，也能保持企业对外沟通的专业性。
这个案例的重点不是让 AI 随意生成一封邮件，而是把企业邮件写作中的稳定要求沉淀到 Prompt 中，例如主题行、称呼、正文结构、行动项和风险提醒。对于新手来说，它也是理解 FastGPT 应用配置的最小闭环：先定义角色，再约束输出，最后通过工具扩展执行动作。
### 1.2 配置步骤
1. **创建对话 Agent**
在工作台点击新建，选择对话 Agent，应用名称填写为 `企业邮件撰写助手`。
2. **进入应用配置页**
创建完成后进入应用配置页。页面通常分为左右两栏：左侧是 AI 配置，右侧是调试预览。
3. **选择模型**
在 AI 配置中选择对话 Agent 使用的基础模型。本案例使用 GLM-5.1，你也可以替换为当前环境中已配置的其他可用模型。
选择模型时优先关注两点：一是模型是否擅长中文商务表达，二是输出是否稳定遵守格式。邮件撰写属于低风险、低结构复杂度任务，通常不需要过度追求最强模型，但要确保语气自然、指令遵循能力较好。
4. **编写 Prompt**
Prompt 需要清晰描述助手的角色、输出格式和约束。可以使用以下示例：
```md
你是一个企业邮件撰写专家，帮助员工撰写专业、清晰、得体的工作邮件。
输出格式：
- **主题行**：简洁明确
- **称呼**：根据收件人关系选择“尊敬的 XX 总”或“Hi XX”
- **正文**：三段式（背景 → 核心内容 → 行动项）
- **落款**：署名、职位、部门
规则：
- 正文控制在 200-500 字
- 行动项和待办用项目符号列出
- 涉及薪资、人事、法律等敏感内容时，提醒用户谨慎发送
- 不确定收件人关系时使用中性礼貌语气
```
将 Prompt 写入提示词模块。
这段 Prompt 由三部分组成：角色定义用于稳定助手身份，输出格式用于约束邮件结构，规则用于控制风险边界。实际业务中可以继续补充企业语气要求、品牌用语、禁用词、签名格式等内容，让输出更贴合内部规范。
5. **添加 Email 工具**
工具是对复杂操作的封装。本案例使用 Email 邮件发送工具，让 AI 助手在生成邮件后具备发送能力。点击工具右侧的加号，选择 Email 邮件发送。
可以把工具理解为 AI 的外部能力。没有工具时，助手只能生成邮件正文；添加 Email 工具后，助手可以在用户确认后执行发送动作。正式环境中建议先让助手生成邮件草稿，再由用户确认发送，避免误发或发送给错误收件人。
6. **配置 Email 工具**
进入工具配置页，填写邮件服务相关参数。
7. **激活工具**
点击设置后进入工具激活页面，再点击工具激活。
8. **填写邮箱 SMTP 信息**
本案例以 QQ 邮箱为例。测试时可以按以下方式填写：
```text
SMTP 服务器地址：smtp.qq.com
SMTP 端口：465
启用 SSL
SMTP 用户名：邮箱地址
SMTP 密码：授权码
```
授权码可参考 [授权码获取教程](https://cloud.tencent.com/developer/article/2177098)。
9. **设置对话开场白**
对话开场白用于告诉用户这个 AI 助手可以做什么。可以填写：
```text
你好！我是邮件撰写助手 📧
请告诉我：收件人是谁？邮件目的是什么？需要包含哪些关键信息？
我会帮你生成一封专业、得体的邮件。
```
填写后，可以在右侧预览区域看到效果。
10. **验证运行效果**
配置完成后，在调试预览中输入邮件需求，检查助手是否能生成结构清晰、语气得体的邮件。
如果用户信息不足，助手应主动提示补充收件人、邮件目的、关键信息等内容。
验证时建议至少测试三类输入：信息完整的邮件需求、缺少收件人或目的的模糊需求、包含敏感信息的邮件需求。一个可上线的邮件助手不只要“能写”，还要能在信息不足时追问，在敏感场景下提醒用户谨慎发送。
### 1.3 业务价值
* **提升写作效率**：将项目同步、客户跟进、会议纪要等高频邮件从“从零写”变成“填写关键信息后生成”，减少重复劳动。
* **统一沟通标准**：把称呼、正文结构、行动项、落款等规范固化到 Prompt 中，降低不同员工写作风格差异带来的沟通成本。
* **降低发送风险**：通过 Prompt 增加敏感信息提醒、信息缺失追问和中性语气约束，减少不完整、不恰当或过度承诺的邮件。
* **扩展办公自动化**：配合 Email 工具后，可以继续接入通知、审批、飞书、钉钉、企业微信等办公流程，将邮件撰写从内容生成延伸到业务动作执行。
## 案例二：知识库 + 对话 Agent—民法典问答助手
### 2.1 适用场景
知识库适合“回答必须基于资料”的场景，例如制度问答、产品手册问答、法律条文检索、客服知识支持等。没有知识库时，AI 主要依赖模型自身能力回答；接入知识库后，AI 会先检索你的资料，再基于检索结果组织答案。
本案例将《中华人民共和国民法典》导入知识库，并创建一个民法典问答助手。用户用自然语言提问时，助手需要优先引用民法典原文，减少凭空生成。
可以把知识库理解为给 AI 配置的“资料室”。模型本身具备通用知识，但不了解你的公司制度、产品细节、内部流程或指定法规版本；知识库把这些资料变成可检索内容，让 AI 在回答前先查资料，再组织答案。对于法律、制度、客服、售后等场景，这比单纯依赖模型记忆更可控。
### 2.2 准备内容
* 示例文件：准备一份《中华人民共和国民法典》或其他法规制度类文档。
* 一个可用的对话模型和向量模型。
* 一个用于测试的法律问题，例如“租房合同没到期，房东要卖房，我该怎么办？”。
### 2.3 配置步骤
1. **创建知识库**
在主页点击左侧的知识库，进入后点击右上角的新建。知识库名称填写为 `民法典问答助手`，案例阶段其他配置保持默认即可。
2. **创建文本数据集**
点击新建，再选择文本数据集，用于导入本地文档。
3. **上传本地文件**
点击上传本地文件，选择示例文件。实际使用时可以同时上传多个文件，本案例只上传一个文件作为演示。
4. **设置解析参数**
进入参数设置页后，根据文件类型选择解析方式。
常用配置建议：
* **文件解析设置**：上传 PDF 时建议开启；普通 Word、Markdown、TXT 等文件可先使用默认配置。
* **处理方式**：大多数场景选择分块存储，成本较低，检索速度也更快。
* **分块条件**：控制每个分块包含多少 Token，快速测试时使用默认值即可。
* **索引增强**：纯文本通常勾选前两个选项；如果文档包含图片，可勾选图片相关增强。
这些参数会直接影响后续问答质量。分块过大时，检索结果可能包含太多无关内容，回答容易变得冗长；分块过小时，关键上下文可能被拆散，回答容易缺少依据。快速上手阶段可以先使用默认配置，正式接入企业制度、合同、产品手册时，再根据问答效果逐步调整。
5. **预览分块效果**
到数据预览步骤后，检查分块是否完整、可读。如果分块过长或过短，再返回调整参数。
预览分块时重点看三点：段落是否被异常截断，标题与正文是否保留在同一语义范围内，表格、条款或编号是否仍然可读。只要这里的知识片段质量不稳定，后续应用即使 Prompt 写得很好，也很难稳定给出准确答案。
6. **等待知识库就绪**
当数据状态变为“已就绪”后，知识库即可被应用引用。
7. **创建并关联对话 Agent**
创建一个新的对话 Agent，名称同样填写为 `民法典问答助手`。创建完成后，在应用配置中关联刚刚创建的知识库。
关联知识库后，应用的回答链路会从单纯对话变成“用户问题 → 知识库检索 → 模型总结回答”。这也是案例一和案例二的关键差异：案例一强调内容生成，案例二强调基于资料回答。
8. **配置问答 Prompt**
民法典问答助手需要强调“基于知识库回答”和“引用原文”。可以使用以下 Prompt：
```md
你是一个专业的民法典问答助手，基于《中华人民共和国民法典》原文回答法律问题。
规则：
- 严格基于知识库检索到的民法典条文回答，不得臆造法条
- 每条回答必须引用民法典原文（编、章、条）
- 如果民法典中没有直接对应的规定，如实说明，不做法律建议
- 涉及具体案件的法律适用时，提醒用户“本回答仅供参考，建议咨询专业律师”
- 对法律术语做通俗解释，让非法学背景的用户也能理解
输出格式：
1. **法律结论**（1-3 句概述）
2. **相关法条引用**（原文摘录 + 编章节条号）
3. **通俗解读**（用日常语言解释法条含义）
4. **实务建议**（2-3 条可操作建议）
5. **免责声明**（“本回答基于民法典原文，不构成法律意见，具体案件请咨询专业律师”）
```
法律问答类场景尤其要强调边界：能回答的是基于资料的通用解释，不能把模型回答包装成正式法律意见。Prompt 中要求引用条文、说明不确定性、添加免责声明，目的都是让输出更可追溯，也更符合高风险知识问答的使用规范。
9. **配置开场白**
开场白可以内置几个示例问题，帮助用户快速理解这个助手的使用方式：
```text
你好！我是民法典问答助手 ⚖️
我基于《中华人民共和国民法典》原文，帮你解答法律问题。
你可以问我：
["租房合同没到期，房东要卖房，我该怎么办？"]
["网购商品收到后发现坏了，商家不给退，法律怎么规定？"]
["楼上漏水把我家的天花板泡了，能索赔吗？"]
⚠️ 提示：我的回答仅供参考，具体法律问题建议咨询专业律师。
```
如果在开场白里添加 `[问题内容]`，用户可以点击问题一键提问，适合用于演示和引导。
10. **验证问答效果**
提出一个民法典相关问题，检查回答是否包含法律结论、法条引用、通俗解读和免责声明。
验证时不要只看回答是否“像法律回答”，还要看它是否真的引用了知识库内容。建议同时测试资料内问题、资料外问题和模糊问题：资料内问题应能引用原文，资料外问题应说明无法直接确认，模糊问题应主动提示需要补充事实。
### 2.4 业务价值
* **降低资料检索门槛**：把长篇法规、制度、手册转成自然语言问答入口，让业务人员不用先知道关键词或目录位置，也能快速找到相关内容。
* **提升回答可信度**：通过知识库检索和原文引用，让答案具备来源依据，减少模型凭经验编造或泛泛而谈的风险。
* **沉淀组织知识**：企业内部制度、产品 FAQ、售后 SOP、合同模板等资料可以持续进入知识库，形成可维护、可复用的知识资产。
* **适配高频支持场景**：法务、HR、行政、客服、交付团队都可以使用类似模式，把重复咨询转成自助问答，提高响应效率。
## 案例三：工作流—内容审核与自动改写
### 3.1 适用场景
工作流适合步骤固定、逻辑清晰、需要分支判断或人工确认的任务。本案例将“内容合规审核”拆成知识库检索、AI 分类、条件判断、自动改写、拒绝说明和人工确认几个环节，用来模拟企业内容发布前的审核流程。
它的核心价值有两个：
1. **自动化**：一次触发后，系统可以按预设流程自动执行多个步骤。
2. **标准化**：同样的输入会经过同样的判断和处理，减少人工差异。
判断一个任务是否适合工作流，可以看它是否具备“步骤稳定、规则明确、可重复执行”三个特征。内容审核就是典型场景：输入是一段待发布内容，规则来自合规知识库，输出通常是通过、改写或拒绝，中间还可以加入人工确认，既提升处理效率，也保留风险控制。
### 3.2 准备内容
先创建一个“内容合规规则库”知识库，并上传一个简单的文本文件。可以直接使用以下规则模板：
```text
内容合规规则
安全内容（可直接发布）
- 客观事实陈述
- 正常的活动通知、会议安排
- 产品功能介绍（基于真实数据）
- 行业知识分享
敏感措辞（需改写）
- 绝对化用语：“最好的”“第一”“100%”“绝对”“唯一”
- 夸张宣传：“颠覆行业”“史无前例”“无人能比”
- 未证实数据：无来源的转化率、满意度、增长率
- 对比贬低：直接点名竞品并贬低
违规内容（禁止发布）
- 违法信息：涉及黄赌毒、诈骗、传销
- 人身攻击：针对个人或群体的侮辱、诽谤
- 虚假信息：伪造数据、虚构资质、冒充官方
- 敏感话题：政治敏感、宗教歧视、地域攻击
```
规则库不需要一开始就非常复杂。快速验证时，先把规则拆成“安全、需改写、禁止发布”三类即可；正式使用时，可以继续按行业、品牌、渠道、地区增加规则，例如广告法敏感词、医疗合规要求、金融营销禁用表达、品牌语气规范等。
### 3.3 流程设计
正式配置节点之前，建议先确认完整流程。这个案例可以按以下方式设计：
1. **用户输入**：作为工作流起点，接收待审核内容。
2. **知识库检索**：从内容合规规则库中召回相关规则，建议引用上限设置为 1-2 条。
3. **AI 内容合规分类**：结合用户输入和检索结果，将内容分为“安全 / 敏感可改 / 违规”。
4. **分支判断**：根据分类结果进入不同分支。
5. **安全分支**：直接输出原文，表示可发布。
6. **敏感可改分支**：调用 AI 改写内容，再交由用户确认。
7. **违规分支**：输出拒绝说明，并给出修改建议。
8. **最终输出**：返回原文、改写稿或拒绝说明。
工作流设计时要先确定每个节点的职责，避免让一个 AI 节点同时承担“检索规则、判断分类、改写内容、解释原因”等过多任务。职责拆清楚后，每个节点的 Prompt 会更短、更稳定，后续也更容易定位问题：是知识库没有召回规则，是审核节点分类不准，还是判断器条件没有匹配上。
### 3.4 配置步骤
1. **创建工作流**
进入工作流主页，点击新建工作流，名称填写为 `内容审核与自动改写`。
创建完成后进入工作流编辑页。
本案例的完整流程图如下：
2. **配置开场白**
在系统配置中填写开场白，说明助手的审核规则和使用方式。
```md
你好！我是内容合规审核助手 🛡️
请把需要审核的内容发给我，我会按规则自动判断：
- **✅ 安全** — 内容无敏感信息，可以直接发布
- **⚠️ 敏感可改** — 包含可修正的措辞，我会改写后发回你确认
- **🚫 违规** — 包含红线内容，直接拒绝并说明原因
支持单个文本审核，也可以批量发（多条用换行分隔）。
**开始吧。**
```
3. **调用知识库**
在工作流中添加知识库检索节点，选择前面创建的内容合规规则库。该节点的输入使用用户输入，输出供后续 AI 节点引用。
这个节点的目的不是让模型阅读完整规则库，而是把与当前内容最相关的规则片段召回给后续审核节点。引用上限可以先设置为 1-2 条，保证提示词上下文足够聚焦；如果规则库较大或分类较细，再逐步提高引用数量。
4. **配置内容审核节点**
添加 AI 对话节点，并重命名为“内容审核节点”。该节点负责根据用户输入和知识库规则输出分类结果。
```md
你是一个内容合规审核专家。结合知识库检索到的合规规则，判断用户输入内容的合规等级。
分类标准：
- 安全：内容无敏感信息，可以直接发布
- 敏感可改：包含可修正的敏感措辞，改写后可发布
- 违规：包含红线内容，不可发布
输出格式：
仅输出三个词之一：安全 / 敏感可改 / 违规
```
注意：知识库引用处必须选择前面创建的知识库，否则 AI 无法读取规则内容。
审核节点的输出要尽量稳定，因为它会直接影响判断器分支。快速演示时可以只输出“安全 / 敏感可改 / 违规”三个词；如果后续要做更严格的自动化集成，可以改成结构化输出，例如同时返回分类、原因和命中的规则，方便下游节点做精确匹配和日志记录。
5. **测试审核节点**
点击右上角运行，输入一段待审核内容，确认审核节点能够返回稳定的分类结果。
这一步建议单独测试节点，而不是等全部流程搭完再调试。可以分别输入正常活动通知、包含绝对化宣传的营销文案、明显违规的文本，观察分类是否符合预期。如果分类不稳定，优先调整规则库表达和审核 Prompt，再继续配置后续分支。
6. **隐藏中间输出**
点击模型右侧的设置按钮，调整节点基础设置。由于用户只需要最终结果，建议隐藏内容审核节点的中间输出。
7. **配置判断器**
添加判断器节点，根据内容审核节点输出的“安全 / 敏感可改 / 违规”进入不同分支。
判断器相当于流程中的分流开关。上一步输出越稳定，判断器越容易配置；如果审核节点输出包含解释性文字，判断条件就可能匹配失败。因此在分支类工作流中，通常要先约束上游节点的输出格式，再配置判断器条件。
8. **配置安全分支**
当审核结果为“安全”时，直接输出原文即可。生产场景中也可以增加抽样复核或人工确认。
输出效果如下：
9. **配置敏感可改分支**
当审核结果为“敏感可改”时，添加 AI 对话节点自动改写内容。可以使用以下 Prompt：
```md
你是一个内容改写专家。将用户输入的内容改写为合规版本。
改写原则：
- 保留原意和信息量，不改变核心表达
- 将绝对化用语替换为客观表述，例如“最好的”改为“行业领先的”
- 将未证实的数据表述替换为合理推测，例如“100% 有效”改为“多数用户反馈有效”
- 将敏感措辞替换为中性表达
- 保持原文风格和语气
```
改写完成后，可以添加用户选择节点，让用户选择接受改写、继续改写或放弃。
人工确认节点适合放在有风险但可修正的路径上。AI 可以负责提出改写建议，但是否发布仍交给业务人员确认。这样既能减少人工初筛和反复改稿的时间，也不会把最终发布权完全交给自动化流程。
如果用户接受改写，输出改写结果；如果用户选择继续改写，可连接回内容改写节点；如果用户放弃，则输出原文。
10. **配置违规分支**
当审核结果为“违规”时，添加 AI 对话节点输出拒绝说明。可以使用以下 Prompt：
```md
用户提交的内容因涉及违规信息无法发布。请用礼貌、专业的语气说明原因。
输出格式：
1. 一句话说明内容无法发布
2. 列举具体的违规点（1-3 条）
3. 提供替代建议（如：建议修改哪些方面后重新提交）
```
11. **验证完整流程**
分别输入安全内容、敏感内容和违规内容，确认三条分支都能返回预期结果。
完整流程验证时，建议记录每条测试内容的输入、审核分类、进入分支和最终输出。若输出不符合预期，按节点顺序排查：先看知识库是否召回正确规则，再看审核节点分类是否准确，最后看判断器条件和分支输出是否配置正确。
### 3.5 业务价值
* **把审核规则流程化**：将内容发布前的判断标准沉淀为知识库和节点配置，减少依赖个人经验口头传递。
* **提高处理效率**：安全内容可快速通过，敏感内容自动改写，违规内容直接说明原因，让审核人员把精力集中在需要判断的内容上。
* **保留人工控制点**：对“敏感可改”这类灰度场景加入用户确认，避免自动化流程直接替业务人员做发布决策。
* **便于复用和扩展**：同样的流程可以迁移到营销文案、客服话术、公告通知、活动页面、短视频脚本等内容审核场景，只需要替换规则库和部分 Prompt。
* **降低合规风险**：通过固定分支和拒绝说明，让高风险内容有明确拦截路径，减少误发、夸大宣传或不合规表达带来的风险。
## 案例四：Agent V2—智能数据分析 Agent
### 4.1 适用场景
Agent V2 适合开放式、多步骤、需要动态规划的任务。与工作流不同，工作流需要提前定义每一步；Agent V2 更适合“步骤不固定”的任务，例如数据分析、文件处理、多工具协作和需要追问澄清的复杂问题。
本案例模拟运营、产品或销售团队的日常数据分析需求：上传 Excel 文件后，直接用自然语言提出问题，让 Agent 自主读取文件、制定分析计划，并在虚拟机中执行分析。
案例三的工作流需要你先设计“检索规则 → 分类 → 分支 → 改写或拒绝”的固定路径；Agent V2 则更像一个可以自主规划的执行者。你不需要提前定义每一步，只需要提供目标和文件，Agent 会根据数据结构和问题复杂度决定先读取文件、再做统计、是否需要追问、是否需要运行代码。
数据分析很适合用来体验 Agent V2，因为它天然具备三个特点：分析路径不固定、经常需要多步推理、需求可能需要澄清。同一份 Excel，不同用户可能关心产品销量、渠道 ROI、区域趋势或异常订单，固定工作流很难提前覆盖所有路径，而 Agent V2 可以根据问题动态规划。
### 4.2 准备内容
* 示例文件：准备一份销售数据 Excel 或 CSV 表格。
* 一个支持 Agent V2 的对话模型。
* 虚拟机能力已在当前环境中可用。
### 4.3 配置步骤
1. **创建 Agent V2 应用**
工作台点击新建应用，选择 `对话 Agent V2`，名称填写为 `智能数据分析 Agent`。
2. **配置模型与 Prompt**
AI 配置继续使用 GLM-5.1 模型。系统提示词可以参考：
```md
你是一个资深数据分析师 Agent。你可以读取用户上传的数据文件、在沙箱中运行 Python 分析代码、并主动向用户追问澄清需求。
工具：
- 📄 **读取文件** — 读取用户上传的 Excel/CSV 数据
- 💻 **沙箱执行** — 运行 Python 脚本（pandas/matplotlib/numpy）
- ❓ **主动追问** — 分析需求不明确时向用户确认
工作方式：
1. 收到数据和问题后，先读取文件了解数据结构和内容
2. 制定分析计划，以步骤列表展示给用户
3. 按计划逐步执行，每步展示关键发现
4. 遇到模糊需求时主动追问，如指标定义不明确或缺少对比基准
5. 根据追问结果动态更新计划
6. 输出分析报告，包含数据概览、核心发现、可视化图表、业务建议
安全规则：
- 沙箱中只能做数据分析，禁止访问网络，禁止写文件到宿主机
- 数据仅用于本次分析，不在报告中暴露原始敏感数据
- 不确定的结论标注置信度
输出格式：
1. 📋 分析计划（根据数据自动生成）
2. 📊 数据概览（行数、列名、缺失值、基本统计）
3. 🔍 核心发现（3-5 个关键洞察，图表辅助）
4. 💡 业务建议（基于数据的可操作建议）
```
这段 Prompt 的重点是让 Agent 先规划再执行，而不是直接给结论。对于数据分析类任务，先读取数据结构、确认字段含义、制定分析计划，可以显著减少误解需求或误用指标的风险。正式使用时，可以继续补充企业内部指标定义，例如 GMV、ROI、转化率、有效客户、复购率等口径。
3. **配置开场白**
开场白用于引导用户上传数据文件并提出分析问题：
```text
你好！我是智能数据分析 Agent 📊
直接把 Excel 或 CSV 文件拖进来，告诉我你想分析什么。
例如：
- "分析这份销售数据，找出销量最好的产品和趋势"
- "帮我看看用户活跃度的变化，找出下降的原因"
- "对比三个渠道的转化率，哪个 ROI 最高？"
我会先了解你的数据，制定分析计划，然后在沙箱中运行分析代码。
需要确认的地方我会主动问你。
```
4. **开启虚拟机能力**
数据分析通常需要读取文件并执行代码，因此需要开启虚拟机配置。
虚拟机能力用于隔离代码执行环境。Agent 可以在其中运行数据分析脚本、读取上传文件、生成统计结果，但不会直接影响本地宿主环境。对于需要运行 Python、处理 Excel、绘制图表或做批量计算的场景，这是 Agent V2 区别于普通对话应用的重要能力。
5. **上传文件并测试**
上传销售数据示例文件，并输入问题：
```text
帮我分析这份销售数据，看看哪些产品卖得好，哪个渠道 ROI 最高
```
Agent 会先拆解任务，再逐步执行分析。
执行过程中可以看到任务在虚拟机中运行，不会影响本地环境。
测试时重点观察 Agent 是否具备完整的分析过程：是否先识别表格字段，是否解释分析计划，是否在需要时运行代码，是否根据结果给出业务建议。如果问题描述不清晰，理想行为不是强行分析，而是先向用户追问关键口径。
### 4.4 验证效果
最终结果应包含分析计划、数据概览、关键发现和业务建议。
结果验证时建议关注四个维度：结论是否来自实际数据，指标口径是否清楚，图表或统计是否能支撑结论，业务建议是否可执行。数据分析 Agent 的价值不只是输出一段总结，而是把“读数据、算指标、解释结果、提出建议”的过程串起来。
### 4.5 业务价值
* **降低数据分析门槛**：业务人员可以直接上传 Excel 或 CSV，用自然语言提出问题，不必先写 SQL、Python 或复杂公式。
* **支持开放式探索**：同一份数据可以围绕销量、渠道、区域、客户、趋势、异常值等方向反复追问，适合没有固定分析路径的场景。
* **提升分析透明度**：Agent 会展示分析计划和关键步骤，用户可以看到它如何理解数据、如何计算指标、如何得出结论。
* **隔离代码执行风险**：通过虚拟机执行分析脚本，降低本地环境污染、依赖冲突和权限误用风险。
* **沉淀业务分析能力**：销售复盘、运营周报、活动归因、产品指标诊断等场景都可以复用这一类 Agent，把数据分析从专家任务变成日常工作流。
## 四种类型选型回顾
完成四个案例后，可以把 FastGPT 的常见应用类型理解为从简单到复杂的能力递进：对话 Agent 解决“怎么回答和生成内容”，知识库解决“基于什么资料回答”，工作流解决“按什么固定流程处理”，Agent V2 解决“面对开放任务如何自主规划和执行”。
| 应用类型 | 适合场景 | 核心能力 |
| -------------- | ------------------- | ---------------- |
| 对话 Agent | 轻量问答、文案生成、标准化输出 | Prompt、模型配置、工具调用 |
| 知识库 + 对话 Agent | 基于资料、制度、法条、产品手册的问答 | 文件导入、知识库检索、引用原文 |
| 工作流 | 固定步骤、条件分支、审核流、自动化处理 | 节点编排、判断器、人工确认 |
| Agent V2 | 数据分析、复杂任务、多步推理、动态规划 | 自主规划、工具调用、虚拟机执行 |
选型时可以按任务复杂度判断：
1. 如果只是做轻量对话或标准化文案生成，优先选择对话 Agent。
2. 如果回答必须基于已有资料，选择知识库 + 对话 Agent。
3. 如果流程固定且需要条件分支、人工确认或自动化处理，选择工作流。
4. 如果任务开放、步骤不固定，并且需要自主分析、工具调用或代码执行，选择 Agent V2。
实际项目中也可以组合使用这些能力。例如客服助手可以使用知识库回答产品问题，再通过工具查询订单；内容审核可以用工作流固定审核路径，同时用知识库维护规则；数据分析场景可以先用 Agent V2 完成探索，再把稳定下来的分析步骤沉淀成工作流。
file: ./content/guide/workspace/customDomain.en.mdx
meta: {
"title": "Configure Custom Domain",
"description": "How to configure a custom domain in FastGPT"
}
FastGPT Cloud supports custom domain configuration starting from v4.14.4.
## How to Configure a Custom Domain
### 1. Open the "Custom Domain" Page
In the sidebar, go to "Account" -> "Custom Domain" to open the configuration page.
If your plan does not support this feature, follow the on-screen instructions to upgrade.
### 2. Add a Custom Domain
1. Have your domain ready. Your domain must have an ICP filing. Currently supported filing providers are Alibaba Cloud, Tencent Cloud, and Volcano Engine.
2. Click the "Edit" button to enter edit mode.
3. Enter your domain, e.g. [www.example.com](http://www.example.com)
4. In your domain provider's DNS management console, add the CNAME record shown on the screen.
5. After adding the DNS record, click "Save". The system will automatically verify the DNS configuration -- this usually takes less than a minute. If verification takes too long, try again.
6. Once the status shows "Active", click "Confirm" to finish.
You can now access FastGPT services and call FastGPT APIs using your own domain.
## DNS Resolution Failure
The system checks DNS resolution daily. If the DNS record becomes invalid, the custom domain will be disabled. You can re-verify it by clicking "Edit" on the "Custom Domain" management page.
To change your custom domain or switch providers, delete the existing configuration and set it up again.
## Use Cases
* [Integrate with WeCom Bot](../build/publish/wecom.en.mdx)
file: ./content/guide/workspace/customDomain.mdx
meta: {
"title": "配置自定义域名",
"description": "如何在 FastGPT 中配置自定义域名"
}
FastGPT 云服务版自 v4.14.4 后支持配置自定义域名。
## 如何配置自定义域名
### 1. 打开“自定义域名”页面
在侧边栏选择“账号” -> “自定义域名”，打开自定义域名配置页。
如果您的套餐等级不支持配置，请根据页面的指引升级套餐。
### 2. 添加自定义域名
1. 准备好您的域名。您的域名必须先经过备案，目前支持“阿里云”、“腾讯云”、“火山引擎”三家服务商的备案域名。
2. 点击“编辑”按钮，进入编辑状态。
3. 填入您的域名，例如 [www.example.com](http://www.example.com)
4. 在域名服务商的域名解析处，添加界面中提示的 DNS 记录，注意记录类型为 CNAME。
5. 添加解析记录后，点击"保存"按钮。系统将自动检查 DNS 解析情况，一般情况下，在一分钟内就可以获取到解析记录。如果长时间没有获取到记录，可以重试一次。
6. 待状态提示显示为“已生效”后，点击“确认”按钮即可。
现在您可以通过您自己的域名访问 fastgpt 服务、调用 fastgpt 的 API 了。
## 域名解析失效
系统会每天对 DNS 解析进行检查，如果发现 DNS 解析记录失效，则会停用该自定义域名，可以在"自定义域名"管理界面中点击"编辑"进行重新解析。
如果您需要修改自定义域名、或修改服务商，则需要删除自定义域名配置后进行重新配置。
## 使用案例
* [接入企业微信智能机器人](../build/publish/wecom.mdx)
file: ./content/self-host/config/env.en.mdx
meta: {
"title": "Environment Variables",
"description": "Environment variables for projects/app, projects/code-sandbox, and pro/admin"
}
This page describes the environment variables commonly used in a self-hosted FastGPT deployment. `projects/app` and `pro/admin` both reuse many settings from `packages/service/env.ts`, so database, secret, object storage, vector database, and service-level variables are documented together. Variables that are only read by `projects/app` or `pro/admin` are listed separately.
## Notes
* `projects/app`: the main Next.js application, including pages, API routes, workflows, Knowledge Bases, object storage, and vector storage.
* `pro/admin`: the commercial Admin service. Besides its own Admin variables, it also reuses App/Service settings such as database, secrets, object storage, models, and logging.
* `projects/code-sandbox`: the code execution sandbox service. It exposes the `/sandbox` endpoint and is called by App through `CODE_SANDBOX_URL`.
* `packages/service/env.ts` exports `serviceEnv`; `projects/app/src/env.ts` exports `appEnv`.
* Shared App/Admin boolean variables use `true`, `1`, `yes`, or `y` to enable a feature. Other values are treated as disabled.
* `FILE_TOKEN_KEY`, `AES256_SECRET_KEY`, and `INVOKE_TOKEN_SECRET` are required at runtime. Use strong random secrets and do not use the example values in production.
## Shared App/Admin Variables
These variables are mainly validated by `packages/service/env.ts` and apply to `projects/app` and to `pro/admin` when it imports `@fastgpt/service`. A few App-side switches are still defined in `packages/service/env.ts`; they are also called out in the App-specific section below.
### Basics and Secrets
| Variable | Default | Description |
| --------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_MAX_LINK` | `5` | Maximum connection pool size for MongoDB, PG, OceanBase, openGauss, and other databases. |
| `SYNC_INDEX` | `true` | Whether to create missing MongoDB indexes and remove explicitly declared deprecated indexes at startup. Maintain indexes manually when disabled. |
| `FILE_TOKEN_KEY` | None, **required** | Secret for file read and file authorization flows. Must be at least 6 characters. |
| `AES256_SECRET_KEY` | None, **required** | Secret used by AES encryption and decryption. Must be at least 6 characters. |
| `INVOKE_TOKEN_SECRET` | None, **required** | JWT secret for Invoke reverse calls. Must be at least 32 characters. |
| `ROOT_KEY` | `fastgpt_root_key` | Admin API key for the current system. It can call `/api/admin/**` APIs and must be at least 6 characters. |
| `PRO_TOKEN` | Empty | Token for FastGPT app server calls to pro/admin internal APIs. It must match the pro/admin configuration and is required when App configures `PRO_URL`. |
| `PRO_URL` | Empty | Commercial service URL. When set, App can call Pro APIs, and the domain is allowed by file URL validation. |
### Service URLs and Integrations
| Variable | Default | Description |
| ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `PLUGIN_BASE_URL` | `http://localhost:3004` | FastGPT Plugin service URL. Deployment templates usually set this to the internal Plugin service URL. |
| `PLUGIN_TOKEN` | `token` | Authentication token for calling the Plugin service. It must match the Plugin service configuration. |
| `CODE_SANDBOX_URL` | `http://localhost:3002` | Code Sandbox service URL. Deployment templates usually set this to the internal Code Sandbox service URL. |
| `CODE_SANDBOX_TOKEN` | `codesandbox` | Token used by App when calling Code Sandbox. It must match the sandbox service `SANDBOX_TOKEN`. |
| `AIPROXY_API_ENDPOINT` | Empty | AI Proxy service URL. When configured, model requests prefer AI Proxy. |
| `AIPROXY_API_TOKEN` | Empty | Token for calling AI Proxy. |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | Default OpenAI-compatible model endpoint when AI Proxy is not configured. |
| `CHAT_API_KEY` | Empty | Default OpenAI-compatible model API key when AI Proxy token is not configured. |
| `CRM_API_URL` | Empty | Lead attribution CRM API base URL (including `/api/v1`). Empty disables identity reporting. |
| `CRM_API_KEY` | Empty | CRM admin API key used to bind a FastGPT user to `visitor_id` after registration or login. |
| `MARKETPLACE_URL` | `https://v2.marketplace.fastgpt.cn` | Plugin marketplace API URL. |
| `FEISHU_BASE_URL` | `https://open.feishu.cn` | Lark Open Platform URL. Use your private Lark domain when self-hosting Lark. |
| `DINGTALK_BASE_URL` | `https://api.dingtalk.com` | DingTalk new API base URL. |
| `DINGTALK_OAPI_BASE_URL` | `https://oapi.dingtalk.com` | DingTalk OAPI base URL. |
| `YUQUE_DATASET_BASE_URL` | `https://www.yuque.com` | Yuque Knowledge Base URL. |
### Agent Sandbox
| Variable | Default | Description |
| ------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AGENT_SANDBOX_PROVIDER` | Empty | Agent Sandbox provider. Supported values are `sealosdevbox` and `opensandbox`. Empty disables Sandbox. Once set, the matching provider variables are required. `fastgpt-app` also requires all three proxy variables, while `fastgpt-pro` requires only the preview proxy URL. |
| `AGENT_SANDBOX_SEALOS_BASEURL` | Empty | Sealos Devbox service URL. |
| `AGENT_SANDBOX_SEALOS_TOKEN` | Empty | Sealos Devbox access token. |
| `AGENT_SANDBOX_SEALOS_WORK_DIRECTORY` | `/home/devbox/workspace` | Working directory inside the Sealos Devbox sandbox. |
| `AGENT_SANDBOX_SEALOS_IMAGE` | Empty | Runtime image used by Sealos Devbox. Required when `sealosdevbox` is enabled. |
| `AGENT_SANDBOX_OPENSANDBOX_BASEURL` | Empty | OpenSandbox service URL. |
| `AGENT_SANDBOX_OPENSANDBOX_API_KEY` | Empty | OpenSandbox API key. Required when OpenSandbox is enabled, and must match OpenSandbox server `[server].api_key`. |
| `AGENT_SANDBOX_OPENSANDBOX_RUNTIME` | `docker` | OpenSandbox runtime, either `docker` or `kubernetes`. |
| `AGENT_SANDBOX_OPENSANDBOX_IMAGE` | Empty | Full runtime image used by OpenSandbox. Required when `opensandbox` is enabled. |
| `AGENT_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY` | `true` | Whether OpenSandbox access goes through the server proxy. |
| `AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL` | Empty | Required in OpenSandbox mode. Volume Manager service URL. |
| `AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN` | Empty | Required in OpenSandbox mode. Volume Manager authentication token. |
| `AGENT_SANDBOX_OPENSANDBOX_VOLUME_NAME_PREFIX` | `fastgpt-session` | Prefix used by the FastGPT app when generating persistent OpenSandbox volume `claimName` values. When upgrading, reuse the previous `VM_VOLUME_NAME_PREFIX` value. |
| `AGENT_SANDBOX_PROXY_SECRET` | Empty | Shared HMAC secret for the app and agent-sandbox-proxy. Required by `fastgpt-app` when Agent Sandbox is enabled; must be at least 32 bytes. |
| `AGENT_SANDBOX_PROXY_URL` | Empty | Browser-accessible WebSocket URL for agent-sandbox-proxy. Required by `fastgpt-app` when Agent Sandbox is enabled; must start with `ws://` or `wss://`. |
| `AGENT_SANDBOX_PREVIEW_PROXY_URL` | Empty | Browser-accessible HTTP(S) URL for Sandbox file previews. You must add it to both `fastgpt-app` and `fastgpt-pro` when Agent Sandbox is enabled. Use an origin separate from the FastGPT application. |
| `AGENT_SANDBOX_FREE_TIP` | `false` | Whether the frontend shows the Agent Sandbox free-use hint. |
| `AGENT_SANDBOX_STORAGE_SIZE_GI` | `1` | Agent Sandbox storage size in Gi. FastGPT derives the archive, Skill, and single-file limits from this value. |
| `AGENT_SANDBOX_SUSPEND_MINUTES` | `60` | Number of inactive minutes before a running Agent Sandbox is automatically suspended. |
| `AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS` | `7` | Number of inactive days before a suspended Agent Sandbox is automatically archived. |
| `AGENT_SANDBOX_MAX_EDIT_DEBUG` | `100` | Limit for Agent edit/debug sandboxes. |
| `AGENT_SANDBOX_NPM_REGISTRY` | Empty | npm registry used by npm, yarn, pnpm, and bun inside Agent sandboxes. |
| `AGENT_SANDBOX_PYPI_INDEX_URL` | Empty | PyPI index URL used by pip, `python -m pip`, and uv inside Agent sandboxes. |
### Databases, Cache, and Vector Stores
| Variable | Default | Description |
| ---------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `REDIS_URL` | `redis://default:mypassword@localhost:6379` | Redis connection URL. |
| `STREAM_RESUME_TTL_SECONDS` | `300` | TTL for an active stream resume mirror, in seconds. |
| `STREAM_RESUME_POST_COMPLETE_TTL_SECONDS` | `30` | Shortened TTL after a stream completes, in seconds. |
| `STREAM_RESUME_REDIS_MAXMEMORY_RATIO` | `0.5` | When Redis used memory divided by `maxmemory` reaches this ratio, new stream resume mirrors are skipped. |
| `STREAM_RESUME_REDIS_MEMORY_CHECK_INTERVAL_MS` | `5000` | Redis memory watermark cache duration, in milliseconds. |
| `MONGODB_URI` | Local MongoDB example URL | Main business MongoDB connection URL. |
| `MONGODB_LOG_URI` | Same example as `MONGODB_URI` | MongoDB connection URL for logs. If unset, it can reuse the main database. |
| `VECTOR_VQ_LEVEL` | `32` | Vector quantization level. Supported ranges depend on the vector store. |
| `PG_URL` | Empty | PostgreSQL/pgvector connection URL. |
| `OCEANBASE_URL` | Empty | OceanBase vector store connection URL. |
| `SEEKDB_URL` | Empty | SeekDB vector store connection URL. |
| `MILVUS_ADDRESS` | Empty | Milvus/Zilliz address. |
| `MILVUS_TOKEN` | Empty | Milvus/Zilliz access token. |
| `OPENGAUSS_URL` | Empty | openGauss vector store connection URL. |
### Object Storage
| Variable | Default | Description |
| --------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `STORAGE_VENDOR` | `minio` | Object storage vendor. Supported values are `minio`, `aws-s3`, `r2`, `cos`, and `oss`. |
| `STORAGE_PUBLIC_BUCKET` | `fastgpt-public` | Public file bucket. |
| `STORAGE_PRIVATE_BUCKET` | `fastgpt-private` | Private file bucket. |
| `STORAGE_REGION` | `us-east-1` | Object storage region. |
| `STORAGE_EXTERNAL_ENDPOINT` | Empty | Externally reachable object storage endpoint for browsers or external services. |
| `STORAGE_R2_PUBLIC_ENDPOINT` | Empty | Public HTTPS domain for a Cloudflare R2 bucket; required when `STORAGE_VENDOR=r2`. |
| `STORAGE_S3_CDN_ENDPOINT` | Empty | CDN endpoint used for temporary `short-redirect` download URLs. Requires `STORAGE_EXTERNAL_ENDPOINT`. |
| `STORAGE_DOWNLOAD_URL_MODE` | `short-proxy` | Download mode: `short-proxy` or `short-redirect`. External URLs are always FastGPT short links. |
| `STORAGE_DOWNLOAD_REDIRECT_TTL_SECONDS` | `300` | Lifetime of the temporary object storage or CDN URL used by `short-redirect`, in seconds. |
| `STORAGE_S3_ENDPOINT` | `http://localhost:9000` | S3/MinIO-compatible API endpoint. |
| `STORAGE_PUBLIC_ACCESS_EXTRA_SUB_PATH` | Empty | Extra sub-path for public file access URLs. |
| `STORAGE_ACCESS_KEY_ID` | `minioadmin` | Object storage access key. |
| `STORAGE_SECRET_ACCESS_KEY` | `minioadmin` | Object storage secret key. |
| `STORAGE_S3_FORCE_PATH_STYLE` | `false` | Whether S3 path-style access is forced. MinIO usually requires this. |
| `STORAGE_S3_MAX_RETRIES` | `3` | Maximum S3 client retry count. |
| `STORAGE_COS_PROTOCOL` | `https:` | Tencent Cloud COS protocol, either `https:` or `http:`. |
| `STORAGE_COS_USE_ACCELERATE` | `false` | Whether Tencent Cloud COS acceleration domain is used. |
| `STORAGE_COS_CNAME_DOMAIN` | Empty | Tencent Cloud COS custom CNAME domain. |
| `STORAGE_COS_PROXY` | Empty | Tencent Cloud COS proxy URL. |
| `STORAGE_OSS_ENDPOINT` | Empty | Alibaba Cloud OSS endpoint. |
| `STORAGE_OSS_CNAME` | `false` | Whether Alibaba Cloud OSS uses CNAME. |
| `STORAGE_OSS_INTERNAL` | `false` | Whether Alibaba Cloud OSS uses an internal endpoint. |
| `STORAGE_OSS_SECURE` | `false` | Whether Alibaba Cloud OSS uses HTTPS. |
| `STORAGE_OSS_ENABLE_PROXY` | `true` | Whether Alibaba Cloud OSS proxy access is enabled. |
### Logging, Metrics, and Tracing
| Variable | Default | Description |
| --------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| `LOG_ENABLE_CONSOLE` | `true` | Whether console logging is enabled. |
| `LOG_CONSOLE_LEVEL` | `debug` | Console log level. Supported values are `trace`, `debug`, `info`, `warning`, `error`, and `fatal`. |
| `LOG_DEPTH` | `3` | Legacy template variable for log object depth. New structured logging mainly uses log-level settings. |
| `LOG_ENABLE_OTEL` | `false` | Whether OpenTelemetry log export is enabled. |
| `LOG_OTEL_LEVEL` | `info` | OTEL log level. |
| `LOG_OTEL_SERVICE_NAME` | `fastgpt-client` | OTEL log service name. |
| `LOG_OTEL_URL` | Empty | OTEL log export URL. |
| `METRICS_ENABLE_OTEL` | `false` | Whether OpenTelemetry metrics export is enabled. |
| `METRICS_EXPORT_INTERVAL` | `30000` | Metrics export interval, in milliseconds. |
| `METRICS_OTEL_SERVICE_NAME` | `fastgpt-client` | OTEL metrics service name. |
| `METRICS_OTEL_URL` | Empty | OTEL metrics export URL. |
| `TRACING_ENABLE_OTEL` | `false` | Whether OpenTelemetry tracing is enabled. |
| `TRACING_OTEL_SERVICE_NAME` | `fastgpt-client` | OTEL tracing service name. |
| `TRACING_OTEL_URL` | Empty | OTEL tracing export URL. |
| `TRACING_OTEL_SAMPLE_RATIO` | Empty | Trace sampling ratio from `0` to `1`. |
| `CHAT_LOG_URL` | Empty | Chat log push service URL. Empty disables pushing. |
| `CHAT_LOG_INTERVAL` | Empty | Chat log batch push interval, in milliseconds. |
| `CHAT_LOG_SOURCE_ID_PREFIX` | `fastgpt-` | Prefix for chat log source IDs. |
| `TRACK_BATCH_UPDATE_TIME` | `10000` | Event counter batch write interval, in milliseconds. |
### Domains, Frontend, and Runtime
| Variable | Default | Description |
| ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FE_DOMAIN` | Required | The origin clients use to access FastGPT, including the scheme, host, and optional port. It completes file and image URLs. Local development can use `http://localhost:3000`. |
| `FILE_DOMAIN` | Empty | File access domain. It usually points to FastGPT, but a separate domain can isolate file risk. |
| `NEXT_PUBLIC_BASE_URL` | Empty | Next.js sub-path deployment prefix, such as `/fastgpt`. It must be fixed when building the image. |
| `HOSTNAME` | `localhost` | Service host used for internal URLs and SSRF local-address detection. Containers commonly set it to `0.0.0.0`. |
| `PORT` | `3000` | Next.js listening port. Also used for local-address detection. |
| `NODE_ENV` | Empty | Standard Node/Next.js runtime environment. Production images set it to `production`. |
| `NEXT_TELEMETRY_DISABLED` | `1` | Disables Next.js Telemetry in production images. |
| `NODE_OPTIONS` | `--max-old-space-size=4096` | Node options used during production image builds to increase the build memory limit. |
### Security
| Variable | Default | Description |
| ----------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `USE_IP_LIMIT` | `false` | Whether IP rate limiting is enabled for selected APIs. |
| `CHECK_INTERNAL_IP` | `false` | Whether internal IP checks are enabled to reduce SSRF risk. |
| `AUTH_COOKIE_SECURE` | `false` | Whether login cookies use the `Secure` attribute. Enable only when the site is HTTPS-only. |
| `TRUSTED_PROXY_ENABLE` | `false` | Whether trusted reverse proxy client IP validation is enabled. Disabled keeps legacy behavior. |
| `TRUSTED_PROXY_IPS` | Empty | Trusted reverse proxy IP/CIDR list, separated by commas or whitespace. |
| `PASSWORD_LOGIN_MINUTE_LIMIT_COUNT` | `10` | Maximum password login requests per account per minute. |
| `MAX_LOGIN_SESSION` | `10` | Maximum login clients per account. |
| `ALLOWED_ORIGINS` | Empty | Allowed CORS origins. Use commas to separate multiple origins. Empty allows all origins by default. |
| `MULTIPLE_DATA_TO_BASE64` | `false` | Whether images are forced into base64 before being sent to models. |
| `DISABLE_CACHE` | `false` | Whether system cache hits are disabled, mainly for debugging. |
| `HTTP_PROXY` | Empty | Outbound HTTP proxy for Node and workers. |
| `HTTPS_PROXY` | Empty | Outbound HTTPS proxy for Node and workers. |
| `NO_PROXY` | Empty | Address list that bypasses proxies. |
| `ALL_PROXY` | Empty | General outbound proxy. |
### Feature Flags and Limits
| Variable | Default | Description |
| -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENT_ENGINE` | `fastAgent` | Agent engine. Supported values are `fastAgent` and `piAgent`. |
| `SKIP_FILE_TYPE_CHECK` | `false` | Whether upload file type checks are skipped. |
| `WECHAT_CHANNEL_CONCURRENCY` | `1000` | WeChat channel poll worker concurrency. Minimum value is `10`. |
| `PARSE_FILE_WORKERS` | `5` | Resident file parsing worker count. |
| `HTML_TO_MARKDOWN_WORKERS` | `10` | Resident HTML-to-Markdown worker count. |
| `TEXT_TO_CHUNKS_WORKERS` | `10` | Resident text chunking worker count. |
| `PARSE_FILE_TIMEOUT_SECONDS` | `600` | Timeout for one file parsing task, in seconds. |
| `WORKFLOW_MAX_RUN_TIMES` | `500` | Maximum workflow run count to avoid extreme infinite loops. |
| `WORKFLOW_MAX_LOOP_TIMES` | `100` | Maximum input array length for loop and parallel nodes. |
| `WORKFLOW_PARALLEL_MAX_CONCURRENCY` | `10` | Parallel node concurrency limit. It must not exceed `WORKFLOW_MAX_LOOP_TIMES`. |
| `SYSTEM_MAX_STRING_LENGTH_M` | `100` | Maximum character length for synchronous system string operations such as variable replacement, in M characters. `1` means `1,000,000` characters. Valid range: `1` to `100`. |
| `CHAT_MAX_QPM` | `5000` | Chat QPM limit. User plan limits take precedence when configured. |
| `SERVICE_REQUEST_MAX_CONTENT_LENGTH` | `10` | Maximum request body size accepted by the service, in MB. |
| `MAX_FOLDER_DEPTH` | `4` | Maximum folder depth. The default allows up to 4 folder levels under the root. Valid range: `2` to `20`. |
| `APP_FOLDER_MAX_AMOUNT` | `1000` | Maximum number of App folders. |
| `DATASET_FOLDER_MAX_AMOUNT` | `1000` | Maximum number of dataset folders. |
| `UPLOAD_FILE_MAX_SIZE` | `1000` | Maximum upload file size, in MB. |
| `UPLOAD_FILE_MAX_AMOUNT` | `1000` | Maximum upload file count. |
| `LLM_REQUEST_TRACKING_RETENTION_HOURS` | `6` | LLM request tracking retention, in hours. |
| `MAX_HTML_TRANSFORM_CHARS` | `1000000` | Maximum number of characters for HTML-to-Markdown conversion. Larger content is not converted. |
## Additional App Variables
These variables are mainly read by `projects/app`. Some are currently defined in `packages/service/env.ts` for shared validation, but their actual consumers are still App-side code.
| Variable | Default | Description |
| ------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `DEFAULT_ROOT_PSW` | `123456` | Default password for initializing the root user. |
| `SYSTEM_NAME` | `AI` | Default system name for the page title. |
| `SYSTEM_DESCRIPTION` | Empty | Page meta description. If unset, the default i18n text is used. |
| `SYSTEM_FAVICON` | Empty | Page favicon URL. If unset, the favicon from system config is used. |
| `CHINESE_IP_REDIRECT_URL` | Empty | China IP redirect URL in frontend config. |
| `PAY_FORM_URL` | Empty | Payment form URL in frontend config. |
| `SHOW_COUPON` | `false` | Whether redemption codes are shown. |
| `SHOW_DISCOUNT_COUPON` | `false` | Whether discount coupons are shown. |
| `HIDE_CHAT_COPYRIGHT_SETTING` | `false` | Whether copyright settings are hidden. |
| `WECOM_LOGIN_AUTO_REDIRECT` | `false` | Whether WeCom terminals automatically redirect to login. |
| `APP_REGISTRATION_URL` | Empty | App registration application URL. Currently kept mostly for compatibility. |
| `PASSWORD_EXPIRED_MONTH` | Empty | Password expiration period in months. Empty means passwords do not expire. |
| `OPENAPI_KEY_MAX_COUNT` | `100` | Maximum number of system API Keys one team member can create. Minimum is 1. |
| `SSE_MCP_SERVER_PROXY_ENDPOINT` | Empty | MCP SSE server proxy URL. Do not include a trailing slash. Required when publishing an SSE MCP App. |
### Open-Source Only
Starting with v4.15.0, the open-source edition no longer reads `config.json`. When upgrading from an earlier version, remove the file's volume mount and migrate the old settings to environment variables using the table below. If you did not use these optional settings, you do not need to add them.
| Former `config.json` field | Current environment variable | Default | Description |
| ------------------------------------------- | ---------------------------- | -------- | ------------------------------------------------------------------------------ |
| `systemEnv.customPdfParse.url` | `CUSTOM_PDF_PARSE_URL` | Empty | Custom PDF parsing service URL. |
| `systemEnv.customPdfParse.key` | `CUSTOM_PDF_PARSE_KEY` | Empty | Custom PDF parsing service key. |
| `systemEnv.customPdfParse.doc2xKey` | `DOC2X_KEY` | Empty | Doc2x PDF parsing service key. |
| `systemEnv.customPdfParse.textinAppId` | `TEXTIN_APP_ID` | Empty | TextIn service App ID. |
| `systemEnv.customPdfParse.textinSecretCode` | `TEXTIN_SECRET_CODE` | Empty | TextIn service Secret Code. |
| `systemEnv.hnswEfSearch` | `HNSW_EF_SEARCH` | `100` | The `hnsw.ef_search` vector search parameter for PG, OceanBase, and openGauss. |
| `systemEnv.hnswMaxScanTuples` | `HNSW_MAX_SCAN_TUPLES` | `100000` | Maximum number of tuples scanned during vector search. Applies only to PG. |
| `systemEnv.datasetParseMaxProcess` | `DATASET_PARSE_MAX_PROCESS` | `10` | Maximum concurrency for the Knowledge Base file parsing queue. |
| `systemEnv.vectorMaxProcess` | `VECTOR_MAX_PROCESS` | `10` | Maximum concurrency for the vector training queue. |
| `systemEnv.qaMaxProcess` | `QA_MAX_PROCESS` | `10` | Maximum concurrency for the Q\&A splitting queue. |
| `systemEnv.vlmMaxProcess` | `VLM_MAX_PROCESS` | `10` | Maximum concurrency for the image understanding model queue. |
#### Enhanced PDF Parsing
The open-source edition supports custom PDF parsing services, SoMark, TextIn, and Doc2x. Configure only one service. If you configure more than one, FastGPT uses this priority order: custom PDF parsing service, SoMark, TextIn, then Doc2x.
##### Use the Sealos PDF Parsing Service
1. Open [Sealos AI Proxy](https://hzh.sealos.run/?uid=fnWRt09fZP\&openapp=system-aiproxy) and create an API key.
2. Add the API key to FastGPT:
```dotenv
CUSTOM_PDF_PARSE_URL=https://aiproxy.hzh.sealos.run/v1/parse/pdf?model=parse-pdf
CUSTOM_PDF_PARSE_KEY=your-sealos-api-key
```
##### Use SoMark
1. Open [SoMark Studio](https://somark.ai/Studio/apikey) and create an API key.
2. Add the API key to FastGPT:
```dotenv
SOMARK_API_KEY=sk-your-api-key
```
The SoMark synchronous parsing endpoint accepts files up to 200 MB and 300 pages. See the [SoMark API documentation](https://docs.somark.ai/en/api-reference) for the complete limits and error codes.
##### Use Another Custom PDF Parsing Service
```dotenv
CUSTOM_PDF_PARSE_URL=https://your-pdf-parser.example.com/v2/parse/file
CUSTOM_PDF_PARSE_KEY=your-service-key
```
`CUSTOM_PDF_PARSE_KEY` is optional. When set, FastGPT sends it to the parsing service as `Authorization: Bearer 2. No ops or database management needed. | Half day | Starting at ¥10,000/month (3-month minimum)
or
Starting at ¥120,000/year
8C32G resources; additional resources billed separately. | | Sealos Fully Managed (Multi-node) | 1. Free upgrades during license period.
2. No ops or database management needed. | Half day | Starting at ¥22,000/month (3-month minimum)
or
Starting at ¥264,000/year
32C128G resources; additional resources billed separately. | | Self-hosted | 1. Free upgrade support for 6 versions. | Within 14 days | [Contact us for pricing](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc?prefill_S=doc\&hide_S=1) |
2. 免运维服务&数据库。 | 半天 | 10000 元起/月（3 个月起）
或
120000 元起/年
8C32G 资源，额外资源另外收费。 | | Sealos 全托管（多节点） | 1. 有效期内免费升级。
2. 免运维服务&数据库。 | 半天 | 22000 元起/月（3 个月起）
或
264000 元起/年
32C128G 资源，额外资源另外收费。 | | 自有服务器部署 | 1. 6 个版本免费升级支持。 | 14 天内 | 具体价格和优惠可[联系咨询](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc?prefill_S=doc\&hide_S=1) |
Click to view docker-compose config file download links for different databases
* **Pgvector** * China mirror (Alibaba Cloud): [docker-compose.pg.yml](/deploy/docker/v4.15/cn/docker-compose.pg.yml) * Global mirror (dockerhub, ghcr): [docker-compose.pg.yml](/deploy/docker/v4.15/global/docker-compose.pg.yml) * **Oceanbase** * China mirror (Alibaba Cloud): [docker-compose.oceanbase.yml](/deploy/docker/v4.15/cn/docker-compose.oceanbase.yml) * Global mirror (dockerhub, ghcr): [docker-compose.oceanbase.yml](/deploy/docker/v4.15/global/docker-compose.oceanbase.yml) * **Milvus** * China mirror (Alibaba Cloud): [docker-compose.milvus.yml](/deploy/docker/v4.15/cn/docker-compose.milvus.yml) * Global mirror (dockerhub, ghcr): [docker-compose.milvus.yml](/deploy/docker/v4.15/global/docker-compose.milvus.yml) * **Zilliz** * China mirror (Alibaba Cloud): [docker-compose.zilliz.yml](/deploy/docker/v4.15/cn/docker-compose.zilliz.yml) * Global mirror (dockerhub, ghcr): [docker-compose.zilliz.yml](/deploy/docker/v4.15/global/docker-compose.zilliz.yml) * **SeekDB** * China mirror (Alibaba Cloud): [docker-compose.seekdb.yml](/deploy/docker/v4.15/cn/docker-compose.seekdb.yml) * Global mirror (dockerhub, ghcr): [docker-compose.seekdb.yml](/deploy/docker/v4.15/global/docker-compose.seekdb.yml)点击展开查看不同数据库的 docker-compose 配置文件下载地址
* **Pgvector** * 中国大陆地区镜像源(阿里云)：[docker-compose.pg.yml](/deploy/docker/v4.15/cn/docker-compose.pg.yml) * 全球镜像源(dockerhub, ghcr)：[docker-compose.pg.yml](/deploy/docker/v4.15/global/docker-compose.pg.yml) * **Oceanbase** * 中国大陆地区镜像源(阿里云)：[docker-compose.oceanbase.yml](/deploy/docker/v4.15/cn/docker-compose.oceanbase.yml) * 全球镜像源(dockerhub, ghcr)：[docker-compose.oceanbase.yml](/deploy/docker/v4.15/global/docker-compose.oceanbase.yml) * **Milvus** * 中国大陆地区镜像源(阿里云)：[docker-compose.milvus.yml](/deploy/docker/v4.15/cn/docker-compose.milvus.yml) * 全球镜像源(dockerhub, ghcr)：[docker-compose.milvus.yml](/deploy/docker/v4.15/global/docker-compose.milvus.yml) * **Zilliz** * 中国大陆地区镜像源(阿里云)：[docker-compose.zilliz.yml](/deploy/docker/v4.15/cn/docker-compose.zilliz.yml) * 全球镜像源(dockerhub, ghcr)：[docker-compose.zilliz.yml](/deploy/docker/v4.15/global/docker-compose.zilliz.yml) * **SeekDB** * 中国大陆地区镜像源(阿里云)：[docker-compose.seekdb.yml](/deploy/docker/v4.15/cn/docker-compose.seekdb.yml) * 全球镜像源(dockerhub, ghcr)：[docker-compose.seekdb.yml](/deploy/docker/v4.15/global/docker-compose.seekdb.yml)
### Beijing Region
The Beijing region is hosted by Volcano Engine. Users in mainland China get stable access, but it can't reach OpenAI or other overseas services. Pricing is about 1/4 of the Singapore region. Click below to deploy 👇
### 1. Start Deployment
Since databases need to be deployed, wait 2–4 minutes after deployment before accessing. The default uses minimal resources, so the first access may be slow.
Follow the prompts to enter `root_password` and the `openai`/`oneapi` address and key.
After clicking deploy, you'll be redirected to the app management page. Click the details button on the right side of the `fastgpt` main app (named fastgpt-xxxx), as shown below.
After clicking details, you'll see the FastGPT deployment management page. Click the link in the external access address to open the FastGPT service.
To bind a custom domain or modify deployment parameters, click **Change** in the top right and follow Sealos' instructions.
### 2. Log In
Username: `root`
Password: the `root_password` you set during one-click deployment
### 3. Configure Models
### 4. Configure Models
You must configure at least one model set, or the system won't work properly.
[View model configuration tutorial](../config/model/intro.en.mdx)
## Pricing
Sealos uses pay-as-you-go billing based on allocated CPU, memory, and disk. For specific pricing, open the **Cost Center** in the Sealos control panel.
## Using Sealos
### Overview
FastGPT Commercial Edition includes 2 apps (fastgpt, fastgpt-plus) and 2 databases. When using multiple API keys, install OneAPI (1 app and 1 database), totaling 3 apps and 3 databases.
Click details on the right to view each app's information.
### Modifying Config Files and Environment Variables
In Sealos, open **App Launchpad** to see deployed FastGPT apps, and open **Database** to see corresponding databases.
In **App Launchpad**, select FastGPT, click **Change**, and you'll see environment variables and config files.
### 北京区
北京区服务提供商为火山云，国内用户可以稳定访问，但无法访问 OpenAI 等境外服务，价格约为新加坡区的 1/4。点击下面按键即可部署👇
### 1. 开始部署
由于需要部署数据库，部署完后需要等待 2\~4 分钟才能正常访问。默认用了最低配置，首次访问时会有些慢。
根据提示，输入 `root_password`，和 `openai` / `oneapi` 的地址和密钥。
点击部署后，会跳转到应用管理页面。可以点击 `fastgpt` 主应用右侧的详情按键（名字为 fastgpt-xxxx），如下图所示。
点击详情后，会跳转到 fastgpt 的部署管理页面，点击外网访问地址中的链接，即可打开 fastgpt 服务。
如需绑定自定义域名、修改部署参数，可以点击右上角变更，根据 sealos 的指引完成。
### 2. 登录
用户名：`root`
密码是刚刚一键部署时设置的 `root_password`
### 3. 配置模型
### 4. 配置模型
务必先配置至少一组模型，否则系统无法正常使用。
[点击查看模型配置教程](../config/model/intro.mdx)
## 收费
Sealos 采用按量计费的方式，也就是申请了多少 cpu、内存、磁盘，就按该申请量进行计费。具体的计费标准，可以打开 `sealos` 控制面板中的 `费用中心` 进行查看。
## Sealos 使用
### 简介
FastGPT 商业版共包含了 2 个应用（fastgpt, fastgpt-plus）和 2 个数据库，使用多 API Key 时候需要安装 OneAPI（一个应用和一个数据库），总计 3 个应用和 3 个数据库。
点击右侧的详情，可以查看对应应用的详细信息。
### 修改配置文件和环境变量
在 Sealos 中，你可以打开 `应用管理`（App Launchpad）看到部署的 FastGPT，可以打开 `数据库`（Database）看到对应的数据库。
在 `应用管理` 中，选中 FastGPT，点击变更，可以看到对应的环境变量和配置文件。
OpenAI-Compatible Enum and Default Budget Mapping
| FastGPT option | OpenAI-compatible value | Default budget | | -------------- | ----------------------------------------- | --------------------- | | Default | Do not explicitly send `reasoning_effort` | Use the model default | | None | `none` | `0` | | Minimal | `minimal` | `1024` | | Low | `low` | `2048` | | Medium | `medium` | `8192` | | High | `high` | `16384` | | Extra high | `xhigh` | `32768` | If an upstream provider only supports a token budget instead of discrete effort levels, ai-proxy uses the table above to convert effort to budget. When normalizing budget back to effort, `<=0` maps to `none`, `1-1024` maps to `minimal`, `1025-4096` maps to `low`, `4097-12288` maps to `medium`, `12289-24576` maps to `high`, and anything higher maps to `xhigh`.OpenAI / OpenAI Responses
| Target format | Output field | Mapping | | ------------------------- | ------------------ | ------------------------------------------------- | | OpenAI Chat / Completions | `reasoning_effort` | Writes `none/minimal/low/medium/high/xhigh` as-is | | OpenAI Responses | `reasoning.effort` | Writes `none/minimal/low/medium/high/xhigh` as-is | OpenAI Chat / Completions only parses `reasoning_effort`. When Gemini, Claude, or other request formats are converted to an OpenAI-compatible format, they are first normalized to this field.Google Gemini
Gemini native requests are parsed from `generationConfig.thinkingConfig`, including `thinkingLevel`, `thinkingBudget`, and `includeThoughts`. When writing to Gemini upstreams, ai-proxy chooses either `thinkingLevel` or `thinkingBudget` based on the model family. | OpenAI-compatible value | Gemini 3+ Pro | Gemini 3+ non-Pro | gemini-2.5-pro | gemini-2.5-flash | gemini-2.5-flash-lite | | ----------------------- | -------------------- | ----------------------- | ---------------------- | ---------------------- | ---------------------- | | `none` | `thinkingLevel=low` | `thinkingLevel=minimal` | `thinkingBudget=128` | `thinkingBudget=0` | `thinkingBudget=0` | | `minimal` | `thinkingLevel=low` | `thinkingLevel=minimal` | `thinkingBudget=1024` | `thinkingBudget=1024` | `thinkingBudget=1024` | | `low` | `thinkingLevel=low` | `thinkingLevel=low` | `thinkingBudget=2048` | `thinkingBudget=2048` | `thinkingBudget=2048` | | `medium` | `thinkingLevel=low` | `thinkingLevel=medium` | `thinkingBudget=8192` | `thinkingBudget=8192` | `thinkingBudget=8192` | | `high` | `thinkingLevel=high` | `thinkingLevel=high` | `thinkingBudget=16384` | `thinkingBudget=16384` | `thinkingBudget=16384` | | `xhigh` | `thinkingLevel=high` | `thinkingLevel=high` | `thinkingBudget=32768` | `thinkingBudget=24576` | `thinkingBudget=24576` | Gemini 2.5 models clamp the budget to the model's supported range. Some Gemini models cannot fully disable thinking, so `none` falls back to the minimum supported level or budget.Claude / Anthropic / Bedrock / Vertex AI
Claude native requests are parsed from `thinking` and `output_config`. When writing to Anthropic, AWS Bedrock Claude, or Vertex AI Claude, the payload still follows Claude's thinking format. | OpenAI-compatible value | Legacy / budget mode | Adaptive mode | | ----------------------- | ---------------------------------------------- | ---------------------------------------------------------------------- | | `none` | `thinking.type=disabled` | `thinking.type=disabled`; may be removed for some adaptive-only models | | `minimal` | `thinking.type=enabled`, `budget_tokens=1024` | `thinking.type=adaptive`, `output_config.effort=low` | | `low` | `thinking.type=enabled`, `budget_tokens=2048` | `thinking.type=adaptive`, `output_config.effort=low` | | `medium` | `thinking.type=enabled`, `budget_tokens=8192` | `thinking.type=adaptive`, `output_config.effort=medium` | | `high` | `thinking.type=enabled`, `budget_tokens=16384` | `thinking.type=adaptive`, `output_config.effort=high` | | `xhigh` | `thinking.type=enabled`, `budget_tokens=32768` | `thinking.type=adaptive`, `output_config.effort=max` | Budget mode ensures `budget_tokens < max_tokens` and raises too-small budgets to the minimum accepted by the upstream provider.Ali DashScope / Qwen / QwQ / GLM / Kimi-Compatible Models
| OpenAI-compatible value | Models with `thinking_budget` support | Models without budget support | | ----------------------- | ------------------------------------------------- | ----------------------------- | | `none` | `enable_thinking=false`; remove `thinking_budget` | `enable_thinking=false` | | `minimal` | `enable_thinking=true`, `thinking_budget=1024` | `enable_thinking=true` | | `low` | `enable_thinking=true`, `thinking_budget=2048` | `enable_thinking=true` | | `medium` | `enable_thinking=true`, `thinking_budget=8192` | `enable_thinking=true` | | `high` | `enable_thinking=true`, `thinking_budget=16384` | `enable_thinking=true` | | `xhigh` | `enable_thinking=true`, `thinking_budget=32768` | `enable_thinking=true` | ai-proxy currently treats `qwen3-*`, `qwq-*`, and Ali-compatible models whose names contain `glm` or `kimi` as supporting `thinking_budget`. Non-streaming `qwen3-*` requests are forced to disable thinking, while `qwq-*` requests are forced to streaming mode.Zhipu / DeepSeek / Doubao / Moonshot Kimi
These providers currently preserve only the on/off meaning. They do not preserve budget or fine-grained effort levels. | Provider | OpenAI-compatible value | Upstream field | | --------------------------------------------- | ------------------------------- | --------------------------------------------------- | | Zhipu / DeepSeek / Doubao | `none` | `thinking.type=disabled` | | Zhipu / DeepSeek / Doubao | `minimal/low/medium/high/xhigh` | `thinking.type=enabled` | | Moonshot / Kimi models with switch support | `none` | `thinking.type=disabled`; remove `reasoning_effort` | | Moonshot / Kimi models with switch support | `minimal/low/medium/high/xhigh` | `thinking.type=enabled`; remove `reasoning_effort` | | Moonshot / Kimi models without switch support | Any value | Remove `reasoning_effort` and omit `thinking` | For Moonshot / Kimi, whether `thinking.type` can be written depends on the actual upstream model name after channel mapping.OpenAI 兼容枚举与默认 budget 映射
| FastGPT 选项 | OpenAI 兼容值 | 默认 budget | | ---------- | ------------------------ | --------- | | 默认 | 不显式传递 `reasoning_effort` | 使用模型默认值 | | 不思考 | `none` | `0` | | 极简思考 | `minimal` | `1024` | | 轻量思考 | `low` | `2048` | | 标准思考 | `medium` | `8192` | | 深度思考 | `high` | `16384` | | 极致思考 | `xhigh` | `32768` | 如果某个平台只支持 token budget，不支持离散档位，ai-proxy 会按上表把 effort 转成 budget。反向归一化时，`<=0` 会被视为 `none`，`1~1024` 视为 `minimal`，`1025~4096` 视为 `low`，`4097~12288` 视为 `medium`，`12289~24576` 视为 `high`，更高则视为 `xhigh`。OpenAI / OpenAI Responses
| 目标格式 | 写入字段 | 映射方式 | | ------------------------- | ------------------ | ----------------------------------------- | | OpenAI Chat / Completions | `reasoning_effort` | `none/minimal/low/medium/high/xhigh` 原样写入 | | OpenAI Responses | `reasoning.effort` | `none/minimal/low/medium/high/xhigh` 原样写入 | OpenAI Chat / Completions 模式只解析 `reasoning_effort`。当 Gemini、Claude 等请求被转换为 OpenAI 兼容格式时，也会先归一化为该字段。Google Gemini
Gemini 原生请求会从 `generationConfig.thinkingConfig` 中解析 `thinkingLevel`、`thinkingBudget` 和 `includeThoughts`。写给 Gemini 上游时，ai-proxy 会根据模型系列选择 `thinkingLevel` 或 `thinkingBudget`。 | OpenAI 兼容值 | Gemini 3+ Pro | Gemini 3+ 非 Pro | gemini-2.5-pro | gemini-2.5-flash | gemini-2.5-flash-lite | | ---------- | -------------------- | ----------------------- | ---------------------- | ---------------------- | ---------------------- | | `none` | `thinkingLevel=low` | `thinkingLevel=minimal` | `thinkingBudget=128` | `thinkingBudget=0` | `thinkingBudget=0` | | `minimal` | `thinkingLevel=low` | `thinkingLevel=minimal` | `thinkingBudget=1024` | `thinkingBudget=1024` | `thinkingBudget=1024` | | `low` | `thinkingLevel=low` | `thinkingLevel=low` | `thinkingBudget=2048` | `thinkingBudget=2048` | `thinkingBudget=2048` | | `medium` | `thinkingLevel=low` | `thinkingLevel=medium` | `thinkingBudget=8192` | `thinkingBudget=8192` | `thinkingBudget=8192` | | `high` | `thinkingLevel=high` | `thinkingLevel=high` | `thinkingBudget=16384` | `thinkingBudget=16384` | `thinkingBudget=16384` | | `xhigh` | `thinkingLevel=high` | `thinkingLevel=high` | `thinkingBudget=32768` | `thinkingBudget=24576` | `thinkingBudget=24576` | Gemini 2.5 系列会按模型允许范围 clamp budget。部分 Gemini 模型不能真正关闭 thinking，`none` 会退化为模型允许的最小 level 或 budget。Claude / Anthropic / Bedrock / Vertex AI
Claude 原生请求会解析 `thinking` 和 `output_config`。写给 Anthropic 官方、AWS Bedrock Claude 或 Vertex AI Claude 时，字段形态仍遵循 Claude 的 thinking 规则。 | OpenAI 兼容值 | 旧式 / budget 模式 | adaptive 模式 | | ---------- | ----------------------------------------------- | -------------------------------------------------------- | | `none` | `thinking.type=disabled` | `thinking.type=disabled`，部分 adaptive-only 模型可能移除该字段 | | `minimal` | `thinking.type=enabled` , `budget_tokens=1024` | `thinking.type=adaptive` , `output_config.effort=low` | | `low` | `thinking.type=enabled` , `budget_tokens=2048` | `thinking.type=adaptive` , `output_config.effort=low` | | `medium` | `thinking.type=enabled` , `budget_tokens=8192` | `thinking.type=adaptive` , `output_config.effort=medium` | | `high` | `thinking.type=enabled` , `budget_tokens=16384` | `thinking.type=adaptive` , `output_config.effort=high` | | `xhigh` | `thinking.type=enabled` , `budget_tokens=32768` | `thinking.type=adaptive` , `output_config.effort=max` | budget 模式会保证 `budget_tokens < max_tokens`，并把过小的 budget 提升到上游可接受的最小值。Ali DashScope / Qwen / QwQ / GLM / Kimi 兼容模型
| OpenAI 兼容值 | 支持 `thinking_budget` 的模型 | 不支持 budget 的模型 | | ---------- | ------------------------------------------------ | ----------------------- | | `none` | `enable_thinking=false`，移除 `thinking_budget` | `enable_thinking=false` | | `minimal` | `enable_thinking=true` , `thinking_budget=1024` | `enable_thinking=true` | | `low` | `enable_thinking=true` , `thinking_budget=2048` | `enable_thinking=true` | | `medium` | `enable_thinking=true` , `thinking_budget=8192` | `enable_thinking=true` | | `high` | `enable_thinking=true` , `thinking_budget=16384` | `enable_thinking=true` | | `xhigh` | `enable_thinking=true` , `thinking_budget=32768` | `enable_thinking=true` | 当前 ai-proxy 会把 `qwen3-*`、`qwq-*`、模型名包含 `glm` 或 `kimi` 的 Ali-compatible 模型视为支持 `thinking_budget`。`qwen3-*` 非流式请求会被强制关闭 thinking，`qwq-*` 请求会被强制改为流式。Zhipu / DeepSeek / Doubao / Moonshot Kimi
这些平台当前主要保留开关语义，不保留 budget 或细粒度 effort。 | 平台 | OpenAI 兼容值 | 写给上游的字段 | | ------------------------- | ------------------------------- | ----------------------------------------------- | | Zhipu / DeepSeek / Doubao | `none` | `thinking.type=disabled` | | Zhipu / DeepSeek / Doubao | `minimal/low/medium/high/xhigh` | `thinking.type=enabled` | | Moonshot / Kimi 支持开关的模型 | `none` | `thinking.type=disabled`，并移除 `reasoning_effort` | | Moonshot / Kimi 支持开关的模型 | `minimal/low/medium/high/xhigh` | `thinking.type=enabled`，并移除 `reasoning_effort` | | Moonshot / Kimi 不支持开关的模型 | 任意值 | 移除 `reasoning_effort`，不发送 `thinking` | Moonshot / Kimi 是否能写入 `thinking.type` 取决于渠道映射后的实际上游模型名。| Resource | Manageable Permissions | Description |
|---|---|---|
| Team | Create Apps | Create, delete, and other basic operations |
| Create Knowledge Bases | Create, delete, and other basic operations | |
| Create Team APIKey | Create, delete, and other basic operations | |
| Manage Members | Invite/remove users, create groups, etc. | |
| App | Can Use | Allows conversation interaction |
| Can Edit | Modify basic info, workflow orchestration, etc. | |
| Can Manage | Add or remove collaborators | |
| Knowledge Base | Can Use | Can call this knowledge base in apps |
| Can Edit | Modify knowledge base content | |
| Can Manage | Add or remove collaborators |
| 资源 | 可管理权限 | 说明 |
|---|---|---|
| 团队 | 创建应用 | 创建，删除等基础操作 |
| 创建知识库 | 创建，删除等基础操作 | |
| 创建团队 APIKey | 创建，删除等基础操作 | |
| 管理成员 | 邀请、移除用户，创建群组等 | |
| 应用 | 可使用 | 允许进行对话交互 |
| 可编辑 | 修改基本信息，进行流程编排等 | |
| 可管理 | 添加或删除协作者 | |
| 知识库 | 可使用 | 可以在应用中调用该知识库 |
| 可编辑 | 修改知识库的内容 | |
| 可管理 | 添加或删除协作者 |
Notes:
- Only one speech recognition model can be active at a time, so you only need to configure one.
- The system requires at least one language model and one embedding model to function properly.
注意事项：
- 目前语音识别模型仅会生效一个，所以配置时候，只需要配置一个即可。
- 系统至少需要一个语言模型和一个索引模型才能正常使用。
国际版：
SANDBOX_TOKEN=
# New
CODE_SANDBOX_URL=
CODE_SANDBOX_TOKEN=
```
2. Internal-network security checks are now disabled by default. To re-enable them, set the environment variable `CHECK_INTERNAL_IP=true` (applies to fastgpt, fastgpt-pro, and fastgpt-sandbox).
### 2. Update Images
* FastGPT image tag: v4.14.9.1
* FastGPT Commercial Edition image tag: v4.14.9.1
* fastgpt-plugin image tag: v0.5.5
* mcp\_server — no update required
* sandbox image tag: v4.14.9.1
* AIProxy — no update required
## API Changes
The `/api/core/chat/getPaginationRecords` endpoint now returns a `useAgentSandbox: boolean` field indicating whether the AI sandbox tool was used in the current conversation turn. The `llmModuleAccount` and `historyPreviewLength` fields will be removed soon — please migrate away from them as soon as possible.
## New Features
1. Added AI Sandbox — attach a sandbox tool to the AI for richer operations. (Currently available on the cloud service only; a lightweight self-hosted deployment will ship in the next release.)
2. Publish channels now support WeChat personal accounts.
3. AgentV2 context now adapts to the paused state.
4. Introduced a logger SDK with Metrics tracking.
5. Updating a single Knowledge Base entry now also refreshes the collection's update timestamp.
6. Form file inputs now support opening files for preview.
## Improvements
1. API-based Knowledge Base sync now has additional fallback methods for retrieving file names.
2. Added SSRF protection to the HTTP tool.
3. Improved compatibility with more MCP JsonSchema fields — older versions could not handle mixed-type fields.
4. Optimized parts of the workflow runtime pool logic to reduce computational complexity.
5. Replaced DFS with Tarjan's SCC algorithm for edge grouping in the workflow runtime, resolving issues where complex cyclic workflows failed to run.
6. System toolsets no longer display a version number (since they have no selectable versions).
## Bug Fixes
1. When a workflow nested a plugin, plugin execution details were not properly preserved. Also cleaned up all tool-type prefixes.
2. Updating and saving an MCP toolset could prevent it from being called correctly (due to an incorrect toolId lookup).
3. The search box was missing from the API Knowledge Base file list.
4. Workflow variable values containing special characters (`$.`) caused incorrect value substitution.
5. Referencing an agent tool in a workflow caused a version retrieval error.
6. When switching from a model that supports certain parameters to one that does not, the unsupported parameters were not removed, causing model invocation failures.
7. Closing a shared link's display status caused AI responses in the chat history to render incorrectly.
8. Re-opening the preview dialog in workflow preview mode lost form input content.
9. Custom fields in subscription plans were not applied.
10. The login endpoint had an async session issue that produced error logs.
11. The condition evaluator was missing selectable conditions for the `arrayAny` type.
12. Video/audio custom file type workflows were missing file link variables at the start node.
13. User input messages were not escaped to Markdown format.
14. Fixed partial context concatenation errors in AgentV2.
## Code Improvements
1. Fixed a monorepo issue in Commercial Edition development where different React references required a full package reinstall.
file: ./content/self-host/upgrading/4-14/4149.mdx
meta: {
"title": "V4.14.9（环境变量变更）",
"description": "FastGPT V4.14.9 更新说明"
}
## 升级指南
### 1. 环境变量更新
1. 修改 FastGPT 环境变量：SANDBOX\_URL 和 SANDBOX\_TOKEN，改名成 CODE\_SANDBOX\_URL 和 CODE\_SANDBOX\_TOKEN：
```bash
# 旧的
SANDBOX_URL=代码运行沙盒的地址
SANDBOX_TOKEN=代码运行沙盒的凭证（可以为空，4.14.8 新增加了鉴权）
# 新的
CODE_SANDBOX_URL=代码运行沙盒的地址
CODE_SANDBOX_TOKEN=代码运行沙盒的凭证
```
2. 默认关闭内网安全检查，如需开启，需设置环境变量 `CHECK_INTERNAL_IP=true`（fastgpt,fastgpt-pro,fastgpt-sandbox 通用变量）
### 2. 更新镜像
* 更新 FastGPT 镜像 tag: v4.14.9.5
* 更新 FastGPT 商业版镜像 tag: v4.14.9.5
* 更新 fastgpt-plugin 镜像 tag: v0.5.5
* mcp\_server 无需更新
* 更新 sandbox 镜像 tag: v4.14.9.1
* AIProxy 无需更新
## 接口变更
`/api/core/chat/getPaginationRecords` 接口，增加返回 `useAgentSandbox:boolean` 字段，代表本轮对话，是否使用了虚拟机工具。即将移除 `llmModuleAccount` 和 `historyPreviewLength` 字段，如使用该字段，请尽快适配。
## 🚀 新增内容
1. 新增 AI 虚拟机功能，可以给 AI 挂载一个虚拟机工具进行更丰富的操作。（目前仅云服务开放使用,下个版本会推出轻量部署方案）
2. 发布渠道支持微信个人号。
3. AgentV2 上下文适配暂停态。
4. 封装 logger sdk。增加 Metrics 追踪。
5. 更新知识库单个数据时，同步更新 collection 更新时间。
6. 表单输入文件时，支持打开文件进行预览。
## ⚙️ 优化
1. API 知识库同步时，增加更多 fallback 获取文件名方式。
2. HTTP 工具，增加 SSRF 防御。
3. 兼容更多 MCP JsonSchema 字段，旧版无法适配混合类型字段。
4. 优化部分工作流运行池逻辑，减少计算复杂度
5. 调整工作流 runtime，用 Tarjan SCC 算法替代 DSC 进行 edges 分组，解决工作流复杂循环无法运行问题。
6. 系统工具集不显示版本（因为其无版本可选）。
## 🐛 修复
1. 工作流嵌套插件时，未成功保留插件运行详情。同时整理所有 tool 类型前缀。
2. 更新并保存 MCP toolset 后可能无法正常调用（由于 toolId 获取错误）。
3. API 知识库，文件列表搜索框丢失。
4. 工作流变量值，包含特殊值($.)的时候，导致值替换异常。
5. 工作流引用 agent 工具时，获取版本异常。
6. 不支持某些属性的参数的模型，从支持该参数的模型切换过来时，该模型未被去掉，导致模型调用失败。
7. 分享链接关闭状态显示后，会导致历史记录里的 AI 回复内容无法正常展示。
8. 修复工作流预览模式下，重新打开预览弹窗，会丢失表单输入内容。
9. 修复订阅套餐自定义字段未生效
10. login 接口，存在异步 session 问题，会出现报错日志。
11. 修复判断器 arrayAny 类型无判断条件可选
12. 修复视频音频自定义文件类型流程开始无文件链接变量
13. 用户输入框消息不转义成 Markdown 格式
14. 修复 AgentV2 部分上下文拼接错误。
15. login 接口安全风险。
16. 工作流工具未按预期连接到结束节点时，嵌套调用工作流工具会导致父工作流无法停止。
## 🛠️ 代码优化
1. 商业版开发时，monorepo 指向不同 react 导致需重装包。
file: ./content/self-host/upgrading/4-14/41930.en.mdx
meta: {
"title": "V4.14.30",
"description": "FastGPT V4.14.30 release notes"
}
## Upgrade Guide
### 1. Update image tags
* Update the fastgpt-app image tag (FastGPT main service): v4.14.30
* Update the fastgpt-pro image tag (FastGPT commercial edition): v4.14.30
## Changes
1. Fixed the issue with incorrect handling of MCP authentication header errors.
file: ./content/self-host/upgrading/4-14/41930.mdx
meta: {
"title": "V4.14.30",
"description": "FastGPT V4.14.30 更新说明"
}
## 升级指南
### 1. 更新镜像 tag
* 更新 fastgpt-app(fastgpt 主服务) 镜像 tag: v4.14.30
* 更新 fastgpt-pro(fastgpt 商业版) 镜像 tag: v4.14.30
## 变更说明
1. 修复 mcp 鉴权头错误处理的问题
file: ./content/self-host/upgrading/4-16/41601.en.mdx
meta: {
"title": "V4.16.0-beta1 (Environment Variable Changes and Upgrade Scripts)",
"description": "FastGPT V4.16.0-beta1 release notes"
}
## 📦 Upgrade Guide
### 1. Update the Agent Sandbox Proxy environment variables (optional)
Version 4.16.0 requires the proxy for static resource access. If your gateway supports WebSocket and HTTP traffic on the same port, you only need to expose one port. Otherwise, set `PREVIEW_PORT` to configure the HTTP port.
```dotenv
# Port for the WebSocket and HTTP services
PORT=1006
# HTTP service port; overrides PORT when set
PREVIEW_PORT=1007
```
The access URL must start with `http://` or `https://`. With a single-port deployment, it can use the same host and port as `AGENT_SANDBOX_PROXY_URL`, while the protocols remain HTTP(S) and WebSocket(S), respectively. We strongly recommend using a different origin from the main FastGPT site. A same-origin deployment places user-generated scripts inside the main site's security boundary, where they may access site credentials or APIs. FastGPT does not currently enforce origin isolation.
Visit `https://{{host}}/health` to verify that the service is accessible.
### 2. Update the fastgpt-app environment variables (required when Sandbox is enabled)
Update the variables in both `fastgpt-app` and `fastgpt-pro`.
1. Add the following environment variables
```dotenv
# HTTP(S) URL used by browsers to preview Sandbox files. Use the URL configured in step 1.
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com
# Required for OpenSandbox. Sets the full storage name prefix (previously configured on the volume image).
VM_VOLUME_NAME_PREFIX=fastgpt-session
```
2. Deprecated Sandbox environment variables
`AGENT_SANDBOX_DISK_MB` and all E2B-related variables.
3. New optional Sandbox environment variables
| Variable | Default | Description |
| ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENT_SANDBOX_CPU_COUNT` | `1` | Maximum CPU cores per Agent Sandbox instance. |
| `AGENT_SANDBOX_MEMORY_MIB` | `2048` | Memory limit per Agent Sandbox instance, in MiB. |
| `AGENT_SANDBOX_STORAGE_SIZE_GI` | `1` | Agent Sandbox storage capacity, in Gi. Used as the Sealos Devbox storage limit and to create new PVCs in OpenSandbox Kubernetes mode. |
| `AGENT_SANDBOX_SUSPEND_MINUTES` | `60` | Number of minutes an active Sandbox can remain idle before it is automatically suspended. |
| `AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS` | `7` | Number of days a suspended Sandbox can remain inactive before it is automatically archived. |
The E2B Sandbox Provider has been removed. Environments previously configured for E2B must switch to `opensandbox` or `sealosdevbox` and remove `AGENT_SANDBOX_E2B_API_KEY`.
> The preview protocols have changed for FastGPT, `fastgpt-agent-sandbox-proxy`, and `fastgpt-agent-sandbox`. When Agent Sandbox is enabled, use the images released with this version. Mixing old and new versions is not supported.
### 3. Update images
* Update the fastgpt-app (FastGPT main service) image tag to `v4.16.0-beta1`
* Update the fastgpt-pro (FastGPT commercial edition) image tag to `v4.16.0-beta1`
* Update the fastgpt-plugin image tag to `v1.1.0-beta1`
* Update the agent-sandbox-volumn image tag to `v0.3.0-beta4` (for OpenSandbox only)
* Update the agent-sandbox-proxy image tag to `v0.3.0-beta4` (for Sandbox only)
### 4. Migrate Agent Sandbox data
This release changes App Chat's Agent Sandbox from “one instance per conversation” to “one shared instance per App and user.” Files from different conversations remain isolated under `sessions/`. Published Skills are stored in the shared `projects` directory.
If Agent Sandbox was previously enabled, migrate the existing Workspaces in the following order. You can skip this section if Agent Sandbox has never been enabled.
Run a dry run first to see how many beta6 Sandbox fields require normalization and how many legacy Skill Debug Chats require cleanup. The dry run does not create resources, access object storage, or modify data:
```bash
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
```
After reviewing the dry-run result, run the migration. The migration first performs the beta6 normalization and continues to Workspace archiving in the same request only when no pending normalization work remains:
```bash
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
```
If every item in `failures` reports `Sandbox source is missing or deleted`, and you have confirmed that the corresponding Apps or Skills no longer exist, you can explicitly skip those stale Sandboxes:
```bash
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false,"skipError":true}'
```
`skipError` defaults to `false`, so omitting it preserves strict migration behavior. The switch only skips an entire source group when that source is missing or soft-deleted. Sandboxes in the group are not archived, deleted, or migrated, and are reported through `skippedCount` and `skipped`. Archive, object storage, provider, concurrency-control, and all other errors remain blocking.
The migration first runs all V4.15.0-beta6 normalization steps. It fills in `sourceType/sourceId` for legacy Sandboxes, removes obsolete fields, deletes orphaned resources that cannot be associated, and cleans up the three legacy Skill Debug Chat collections and old private/public Bucket prefixes when `sourceType` is missing. A Skill whose ID matches an App ID is excluded from Chat cleanup. After recounting, the two categories are combined into `normalization.pendingCount`; Workspace archiving does not begin while the count is non-zero. Once normalization is complete, all legacy Workspaces are archived, old compute resources are cleaned up, Skills are migrated, and records are aggregated into user-level Sandboxes by App and user. Installation does not start if any archive operation fails. New Sandboxes are suspended after Workspace installation and start normally on first use. The script is safe to retry: completed archive and migration operations are not repeated. Old archives and MongoDB records are retained as backups after migration.
Check `normalization.pendingCount`, `normalizationBlocked`, `failedCount`, `failures`, `skippedCount`, and `skipped` in the response. When both `normalization.pendingCount` and `failedCount` are `0` and `normalizationBlocked` is `false`, every non-skipped Sandbox has been migrated. Legacy records listed in `skipped` remain in place and are not migrated.
### 5. Migrate HTTP tool data
This release changes array parameters in manually configured HTTP tools to standard JSON Schema. Environments with manual HTTP tools created before the upgrade must run this migration. OpenAPI-mode HTTP tools do not require migration and are skipped automatically.
Run a dry run first to inspect pending data in current Apps and historical versions. The dry run does not modify data:
```bash
curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
```
After confirming the result, run the migration:
```bash
curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
```
The script first filters Apps by HTTP tool type, then migrates historical versions associated with those `appId` values. Only manual-mode tools without `apiSchemaStr` are processed; other Apps and OpenAPI-mode tools are left unchanged. The migration runs in batches and is safe to retry. `total.changedDocumentCount` in the response shows how many documents require processing. Run another dry run after the migration and confirm that this value is `0`.
### 6. Other changes (optional)
1. `PASSWORD_LOGIN_LOCK_SECONDS` is deprecated. Use `PASSWORD_LOGIN_MINUTE_LIMIT_COUNT` to control the maximum number of password login attempts allowed per account per minute.
## 🚀 New
1. Agent Sandbox now runs at the App-user level. Multiple conversations from the same user and App share a Sandbox while keeping files isolated in separate session directories.
2. Sandbox HTML and files can be previewed directly through short-lived, read-only links without being uploaded to object storage again.
3. App Workflow automatically archives and restores Workspaces when the Sandbox Provider or runtime image changes. The upgrade completes silently during the current run.
4. Workflow tool nodes can delegate selected input parameters to the Agent for generation while preserving fixed values, references, and user inputs.
5. ChatAgent tool selection supports explicitly choosing whether parameters should be generated by AI.
6. Knowledge Base data supports custom `metadata`, which can be imported as JSON through the API, CSV templates, or Excel templates. Search results and backup exports preserve this field. Template and backup imports accept both `.csv` and `.xlsx` files with `q`, `a`, `index`, and `metadata` headers. `q`, `a`, and `metadata` each use one column, while `index` may use multiple columns in any order. Excel files must contain a single worksheet with no merged cells. FastGPT reports an invalid file format when it cannot parse a CSV or Excel file correctly.
7. Large-file chunked uploads.
8. System tool keys configured by administrators are now encrypted, with backward compatibility for existing keys.
9. Added empty-state guidance to the Skill list and linked Skill creation from the Skill selector.
## ⚙️ Improvements
1. Refactored the Agent Sandbox lifecycle and migration flow with concurrency protection, resumable execution, and idempotent retries for creation, suspension, archiving, restoration, deletion, and Provider changes.
2. When Agent Sandbox is unavailable or unsupported by the current team plan, App Chat disables Sandbox automatically. Other models, tools, Knowledge Bases, and Workflow nodes remain available.
3. OpenSandbox can retain persistent volumes after stopping and reuse them on later runs. Suspension and archive thresholds can be configured through environment variables.
4. App and Skill now share runtime image upgrade status, and the Skill editor can continuously poll for upgrade results.
5. Sandbox file writes now create parent directories automatically, preventing failures when writing to nested paths.
6. Improved compatibility handling for legacy Workflow data and tool parameters.
7. Updated the Agent Ask UI.
## 🐛 Fixes
1. Fixed OpenSandbox resources not being released or reused correctly after stopping.
2. Fixed state races and duplicate operations during Agent Sandbox creation, restoration, and runtime upgrades.
3. Fixed Sandbox writes to nested directories failing when the parent directory did not exist.
4. Fixed number inputs becoming regular text fields after switching between Agent-generated and manual input.
5. Fixed string inputs being rendered incorrectly as dropdowns.
6. Fixed JSON Editor being incorrectly included in Workflow tool configuration.
7. Fixed tool execution errors being displayed incorrectly in Agent and Workflow tool interfaces.
8. Fixed uninstalled tools still appearing in the system tool list.
9. Fixed the default Agent/Agent V2 version selection so it chooses the latest version by default.
10. Fixed images embedded in S3-hosted files with spaces failing to parse because of malformed keys and returning 404 errors.
11. Fixed duplicate headers in MCP SSE mode.
12. Fixed unencrypted Agent V2 system tool keys.
## 🛠️ Code Improvements
1. Split Sandbox Adapter by lifecycle, filesystem, command execution, and Provider contracts, and removed the E2B Adapter.
2. Added direct Workspace preview, Range requests, path traversal protection, and session authentication to Agent Sandbox Proxy and IDE Agent.
3. Optimized Workflow schemas and unified tool calls with form rendering.
4. Extended tool JSON Schema support for additional data types.
5. Unified service file-read timeouts.
6. Hardened system tool permissions in multi-process deployments.
7. Refactored login and authentication code.
8. Refactored the rate-limiting module.
file: ./content/self-host/upgrading/4-16/41601.mdx
meta: {
"title": "V4.16.0-beta1（环境变量变更、升级脚本）",
"description": "FastGPT V4.16.0-beta1 更新说明"
}
## 📦 升级指南
### 1. 更新 Agent-sandbox-proxy 环境变量（可选）
4.16.0 需要依赖 proxy 进行静态资源代理访问，如果网关支持 ws 和 http 在同一个端口，则可以只开放一个端口。如果不支持，可以通过设置 `PREVIEW_PORT` 来设置 http 访问端口。
```dotenv
# ws和http服务的端口
PORT=1006
# http服务的端口，可以覆盖 PORT
PREVIEW_PORT=1007
```
访问地址以 `http://` 或 `https://` 开头。单端口部署时，它可以与 `AGENT_SANDBOX_PROXY_URL` 指向同一域名和端口，但协议分别使用 HTTP(S) 和 WebSocket(S)。强烈建议配置的域名与 FastGPT 主站使用不同的 origin。同源部署会让这些脚本进入主站的同源安全边界，可能访问主站凭证或接口。系统当前不会强制检查 origin 是否隔离。
可以通过访问: `https://{{host}}/health` 来确认是否可访问。
### 2. 更新 fastgpt-app 环境变量(启用沙盒的需更新)
在 `fastgpt-app` 和 `fastgpt-pro` 同时修改变量。
1. 增加环境变量
```dotenv
# 浏览器访问 Sandbox 文件预览的 HTTP(S) 地址，这个地址从第一步取。
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com
# opensandbox 需配置，存储全前缀名（之前是配置在 volumn 镜像环境变量里）
VM_VOLUME_NAME_PREFIX=fastgpt-session
```
2. 弃用的沙盒环境变量
`AGENT_SANDBOX_DISK_MB`，E2B 相关变量。
3. 新增的可选的沙盒配置变量
| 变量 | 默认值 | 说明 |
| ------------------------------------- | ------ | ------------------------------------------------------------------------------------ |
| `AGENT_SANDBOX_CPU_COUNT` | `1` | Agent Sandbox 单实例 CPU 核数上限。 |
| `AGENT_SANDBOX_MEMORY_MIB` | `2048` | Agent Sandbox 单实例内存上限，单位 MiB。 |
| `AGENT_SANDBOX_STORAGE_SIZE_GI` | `1` | Agent Sandbox 存储容量，单位 Gi；用于 Sealos Devbox 存储上限，以及 OpenSandbox Kubernetes 模式下创建新 PVC。 |
| `AGENT_SANDBOX_SUSPEND_MINUTES` | `60` | 运行中的 Sandbox 未活跃多久后自动暂停，单位分钟。 |
| `AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS` | `7` | 已暂停 Sandbox 未活跃多久后自动归档，单位天。 |
E2B Sandbox Provider 已移除。此前配置过 E2B 的环境需要切换为 `opensandbox` 或 `sealosdevbox`，并删除 `AGENT_SANDBOX_E2B_API_KEY`。
> FastGPT、`fastgpt-agent-sandbox-proxy` 和 `fastgpt-agent-sandbox` 的预览协议已同步变更。启用 Agent Sandbox 时必须使用本版本配套镜像，不支持新旧版本混合部署。
### 3. 镜像更新
* 更新 fastgpt-app(fastgpt 主服务) 镜像 tag: v4.16.0-beta1
* 更新 fastgpt-pro(fastgpt 商业版) 镜像 tag: v4.16.0-beta1
* 更新 fastgpt-plugin 镜像 tag: v1.1.0-beta1
* 更新 agent-sandbox-volumn 镜像 tag: v0.3.0-beta4 (Opensandbox 专属)
* 更新 agent-sandbox-proxy 镜像 tag: v0.3.0-beta4 (沙盒专属)
### 4. 迁移 Agent Sandbox 数据
本版本将 App Chat 的 Agent Sandbox 从“每个对话一个实例”调整为“同一 App、同一用户共享一个实例”。不同对话的文件仍分别保存在 `sessions/` 目录中，已发布 Skill 则统一保存在共享的 `projects` 目录中。
如果此前启用过 Agent Sandbox，必须按以下顺序完成旧 Workspace 迁移。未启用过 Agent Sandbox 的环境可以跳过本节。
先执行 dry-run，查看 beta6 Sandbox 字段归一化和旧 Skill Debug Chat 清理的待处理数。dry-run 不会创建资源、访问对象存储或修改数据：
```bash
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
```
查看 dry-run 结果后执行正式迁移。正式迁移会先执行 beta6 归一化，并且只在剩余待处理数归零时，才在同一请求中继续 Workspace 归档：
```bash
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
```
如果 `failures` 中仅包含 `Sandbox source is missing or deleted`，并且已确认对应 App 或 Skill 确实不再存在，可以显式跳过这些残留 Sandbox：
```bash
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false,"skipError":true}'
```
`skipError` 默认为 `false`，省略时保持严格迁移。该开关只跳过 source 已缺失或已软删除的整个分组，不会归档、删除或迁移其中的 Sandbox；跳过明细通过 `skippedCount` 和 `skipped` 返回。归档、对象存储、Provider 和并发控制等其他错误仍会阻断迁移。
迁移会先执行 V4.15.0-beta6 的完整前置逻辑：补齐旧 Sandbox 的 `sourceType/sourceId`、清理遗留字段、删除无法归属的孤立资源，并清理缺失 `sourceType` 的旧 Skill Debug Chat 三表数据及私有、公开 Bucket 旧前缀。与 App 同 ID 的 Skill 会跳过 Chat 清理。两类数据重新统计后合计为 `normalization.pendingCount`；数量不为 `0` 时不会进入 Workspace 归档。归零后直接归档全部旧 Workspace 并清理旧计算资源，再迁移 Skill，最后按 App、用户聚合到用户级 Sandbox。只要归档阶段存在失败，安装阶段就不会开始。新的 Sandbox 会在 Workspace 安装完成后暂停，首次使用时再按正常流程启动。脚本可安全重试，已完成的归档和迁移不会重复执行；迁移完成后会保留旧归档和旧 MongoDB 记录作为备份。
请检查返回结果中的 `normalization.pendingCount`、`normalizationBlocked`、`failedCount`、`failures`、`skippedCount` 和 `skipped`。只有 `normalization.pendingCount` 和 `failedCount` 均为 `0`，且 `normalizationBlocked` 为 `false` 时，才表示所有未跳过的 Sandbox 迁移完成；`skipped` 中的 Legacy 记录会保留且不会迁移。
### 5. 迁移 HTTP 工具数据
本版本将手动模式 HTTP 工具的数组参数改为标准 JSON Schema。升级前创建过手动 HTTP 工具的环境需要执行此迁移；OpenAPI 模式的 HTTP 工具无需迁移，脚本会自动跳过。
先执行 dry-run，查看当前应用及历史版本中的待处理数据。dry-run 不会修改数据：
```bash
curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
```
确认结果后执行正式迁移：
```bash
curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
```
脚本会先按 HTTP 工具类型筛选应用，再根据这些应用的 `appId` 迁移对应的历史版本。仅 `apiSchemaStr` 不存在的手动模式会被处理，其他应用及 OpenAPI 模式不会修改。迁移按批次执行且可安全重试；返回结果中 `total.changedDocumentCount` 表示发现的待处理文档数，正式执行后可再次 dry-run，确认该值为 `0`。
### 6. 其他变更（可选）
1. 弃用 `PASSWORD_LOGIN_LOCK_SECONDS` 变量，改成 `PASSWORD_LOGIN_MINUTE_LIMIT_COUNT` , 用于控制每分钟登录频率控制。
## 🚀 新增内容
1. Agent Sandbox 改为 App 用户级实例，同一 App、同一用户的多个对话复用 Sandbox，并通过独立 session 目录隔离各对话文件。
2. Sandbox HTML 和文件支持通过短期只读链接直接预览，不再为预览重复上传到对象存储。
3. App Workflow 在 Sandbox Provider 或运行时镜像变化时自动归档并恢复 Workspace，升级过程在当前运行中静默完成。
4. 工作流工具节点支持将指定输入参数交由 Agent 自动生成，并保留固定值、引用和用户输入等既有配置。
5. ChatAgent 选择工具时，支持手动指定是否为 AI 生成参数。
6. 知识库数据支持自定义 `metadata`，可通过 API、CSV 或 Excel 模板导入 JSON 元数据；检索结果和备份导出会保留该字段。模板导入和备份导入均支持 `.csv` 和 `.xlsx` 文件，使用 `q`、`a`、`index`、`metadata` 表头；`q`、`a`、`metadata` 各一列，`index` 可多列且顺序任意。Excel 文件仅支持单个工作表且不能包含合并单元格，无法正确解析的 CSV 或 Excel 文件会提示文件格式异常。
7. 大文件分块上传。
8. 管理员配置系统工具密钥时，加密（兼容已配置的密钥）。
9. 技能列表空状态引导，以及选择技能时联动。
## ⚙️ 优化
1. 重构 Agent Sandbox 生命周期和迁移流程，创建、暂停、归档、恢复、删除及 Provider 切换支持并发保护、断点续跑和幂等重试。
2. Agent Sandbox 不可用或当前团队套餐不支持时，App Chat 自动禁用 Sandbox 能力，其他模型、工具、知识库和 Workflow 节点仍可继续运行。
3. OpenSandbox 停止后可保留持久卷并在后续运行时复用；暂停和归档阈值支持通过环境变量配置。
4. App 与 Skill 统一运行时镜像升级状态，Skill 编辑页可持续轮询升级结果。
5. Sandbox 文件写入前自动创建父目录，避免写入嵌套路径失败。
6. 优化工作流旧数据、工具参数等兼容问题。
7. Agent Ask UI。
## 🐛 修复
1. 修复 OpenSandbox 资源停止后未正确释放或复用的问题。
2. 修复 Agent Sandbox 创建、恢复或运行时升级期间的状态竞争和重复操作问题。
3. 修复 Sandbox 向嵌套目录写入文件时因父目录不存在而失败的问题。
4. 修复 number 输入在 Agent 生成和手动输入之间切换后变成普通文本框的问题。
5. 修复字符串文本输入被错误渲染为下拉选择的问题。
6. 修复 JSON Editor 被错误加入工作流工具配置的问题。
7. 修复工具运行错误在 Agent/工作流工具界面中被错误展示的问题。
8. 修复系统工具列表中已卸载工具的展示问题。
9. 修复 Agent/Agent V2 默认版本选择逻辑，使其默认选择最新版本。
10. S3 文件如果有空格时，解析其文件内的图片，会因 key 异常 404。
11. MCP SSE 模式，header 重复。
12. Agent V2 系统工具密钥未加密。
## 🛠️ 代码优化
1. Sandbox Adapter 按生命周期、文件系统、命令执行和 Provider 契约重新拆分，并移除 E2B Adapter。
2. Agent Sandbox Proxy 和 IDE Agent 增加 Workspace 直连预览、Range 请求、路径逃逸防护及会话鉴权。
3. 工作流 schema 优化，统一工具调用和表单渲染。
4. 扩展工具 JSON Schema，支持更多数据类型。
5. 统一服务文件读取超时时间。
6. 优化系统工具多进程权限安全问题。
7. 重构登录与身份验证代码。
8. 重构限流模块。
file: ./content/self-host/upgrading/4-16/41602.en.mdx
meta: {
"title": "V4.16.0-beta2 (In Progress)",
"description": "FastGPT V4.16.0-beta2 release notes"
}
## ⚠️ Upgrade notes
### Clean up legacy system model configurations
This release applies strict schemas when system models are initialized or saved. Numeric strings, serialized price tiers, and missing fields saved by earlier releases may fail initialization validation. After upgrading, run a dry run first to inspect the model configurations that require cleanup. A dry run does not modify data or reload the model cache:
```bash
curl -X POST 'https://your-domain/api/admin/dataClean/cleanSystemModelConfigs' \
-H 'Content-Type: application/json' \
-H 'rootkey: YOUR_ROOT_KEY' \
-d '{"dryRun":true}'
```
After confirming that `invalidSamples` contains no records that require manual correction, run the cleanup:
```bash
curl -X POST 'https://your-domain/api/admin/dataClean/cleanSystemModelConfigs' \
-H 'Content-Type: application/json' \
-H 'rootkey: YOUR_ROOT_KEY' \
-d '{"dryRun":false}'
```
The cleanup converts valid numeric strings to numbers, parses serialized `priceTiers` arrays, and removes invalid optional numeric fields. Invalid or missing required numeric fields use system defaults: LLM `maxContext/maxResponse/quoteMaxToken` default to `16000/16000/13000`, Embedding `defaultToken/maxToken` default to `500/3000`, and price fields default to `0`. `functionCall` remains optional, and a missing Embedding `weight` defaults to `0`.
The write operation updates all matching records in one operation and immediately reloads the system model cache. The runtime cache is rebuilt even when no database record needs an update. The endpoint is safe to run repeatedly; a follow-up dry run should report `wouldUpdate` as `0`. Records that still fail the complete current model schema are not written, and all of them are listed in `invalidSamples`.
## 🚀 New
1. Moved Workflow app system settings to a dedicated panel in the canvas toolbar. The panel opens automatically when a new Workflow app is created.
2. Added support for configuring multiple preset questions separately, with drag-and-drop reordering.
## ⚙️ Improvements
1. Redesigned the Publish Channels page with separate native and third-party channel groups and a count of configured connections for each channel.
2. Improved batch updates in the Tool Marketplace. Partially failed updates now remain visible and can be retried or uninstalled individually, with clearer installed-version and update-status information.
3. Limited portal quick apps to three while preserving compatibility with existing configurations that exceed the limit.
4. Replaced fixed PDF edge cropping with dynamic edge detection to prevent valid content near page boundaries from being removed.
## 🐛 Fixes
1. Fixed legacy Workflow HTTP tools not restoring the correct default input mode for dynamic parameters.
2. Fixed incorrect initial configuration labels caused by Workflow translations not being preloaded when an app was created.
3. Fixed duplicate rendering of Workflow tool parameters.
4. Fixed file variables not accepting uploads after an app was published.
5. Fixed file uploads failing for shared Workflow tool parameters.
6. Fixed upload, parsing, preview, or download failures when S3 object keys or filenames contained spaces or special characters such as `%`, `#`, `?`, or slashes.
file: ./content/self-host/upgrading/4-16/41602.mdx
meta: {
"title": "V4.16.0-beta2（进行中）",
"description": "FastGPT V4.16.0-beta2 更新说明"
}
## 📦 升级指南
### 1. 清洗历史系统模型配置
本版本开始在系统模型初始化及保存时使用严格 Schema。此前版本保存的数字字符串、字符串形式的价格梯度或缺失字段可能导致初始化校验失败。升级后请先执行 dry-run，查看需要处理的模型配置；dry-run 不会修改数据或刷新缓存：
```bash
curl -X POST 'https://你的域名/api/admin/dataClean/cleanSystemModelConfigs' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
```
确认 `invalidSamples` 中没有需要人工处理的数据后，执行正式清洗：
```bash
curl -X POST 'https://你的域名/api/admin/dataClean/cleanSystemModelConfigs' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
```
清洗会将合法数字字符串转换为 number、将字符串形式的 `priceTiers` 转换为数组，并删除非法的可选数字。非法或缺失的必填数字使用系统默认值：LLM 的 `maxContext/maxResponse/quoteMaxToken` 分别为 `16000/16000/13000`，Embedding 的 `defaultToken/maxToken` 分别为 `500/3000`，价格为 `0`。`functionCall` 保持可选，Embedding 缺失的 `weight` 补为 `0`。
正式执行会统一写入数据并立即刷新系统模型缓存；即使没有记录需要更新，也会重新构建运行时缓存。接口可安全重复执行；再次 dry-run 时，`wouldUpdate` 应为 `0`。无法通过当前完整模型 Schema 的记录不会写入，详情会全部返回在 `invalidSamples` 中。
## 🚀 新增内容
1. 工作流应用的系统配置移至画布左侧工具栏中的独立配置面板，新建工作流应用时会自动打开。
2. 开场白支持独立配置多个预设问题，并可拖拽排序。
## ⚙️ 优化
1. 重构发布渠道页面，按原生渠道和第三方渠道分组展示，并显示各渠道已配置数量。
2. 工具市场批量更新支持展示部分失败项、单独重试或卸载，并完善已安装版本和更新状态的展示。
3. 门户页快捷应用数量上限调整为 3 个，并兼容已超出上限的历史配置。
4. PDF 解析器动态边缘裁剪，而不是固定边缘裁剪，避免裁剪掉真实内容。
## 🐛 修复
1. 修复旧版工作流 HTTP 工具的动态参数未正确恢复默认输入方式的问题。
2. 修复新建工作流应用时，国际化资源未预加载导致初始配置文案异常的问题。
3. 修复工作流工具参数可能被重复渲染的问题。
4. 修复应用发布后，文件变量无法上传文件的问题。
5. 修复共享工作流工具的文件参数无法上传文件的问题。
6. 修复 S3 对象键和文件名包含空格、`%`、`#`、`?`、斜杠等特殊字符时，可能导致上传、解析、预览或下载异常的问题。
## 🛠️ 代码优化
1. 审计日志归档，不再删除，改成转存到 S3 冷归档。
2. 增加对 admin 配置的数据校验和清洗。
file: ./content/self-host/upgrading/outdated/40.en.mdx
meta: {
"title": "V4.0 (Upgrade Script)",
"description": "Upgrade guide from older versions to FastGPT V4.0"
}
import { Alert } from '@/components/docs/Alert';
If you are **upgrading from an older version to V4**, the MongoDB schema has changed significantly. You'll need to run the initialization scripts described below.
## Rename Collections
Connect to your MongoDB database and run these two commands:
```js
db.models.renameCollection('apps');
db.sharechats.renameCollection('outlinks');
```
Note: When upgrading from an older version to V4, MongoDB will automatically create empty collections with these names. You need to manually drop those empty collections first before running the commands above.
## Initialize Fields in Several Collections
Run the following 3 commands sequentially. They may take a while to complete. If a command fails, you can safely re-run it (already-initialized records will be skipped) until all data has been updated.
```js
db.chats.find({ appId: { $exists: false } }).forEach(function (item) {
db.chats.updateOne(
{
_id: item._id
},
{ $set: { appId: item.modelId } }
);
});
db.collections.find({ appId: { $exists: false } }).forEach(function (item) {
db.collections.updateOne(
{
_id: item._id
},
{ $set: { appId: item.modelId } }
);
});
db.outlinks.find({ shareId: { $exists: false } }).forEach(function (item) {
db.outlinks.updateOne(
{
_id: item._id
},
{ $set: { shareId: item._id.toString(), appId: item.modelId } }
);
});
```
## Initialization APIs
Deploy the new version, then send 3 HTTP requests (remember to include `headers.rootkey` — this value comes from your environment variables):
1. [https://xxxxx/api/admin/initv4](https://xxxxx/api/admin/initv4)
2. [https://xxxxx/api/admin/initChat](https://xxxxx/api/admin/initChat)
3. [https://xxxxx/api/admin/initOutlink](https://xxxxx/api/admin/initOutlink)
Requests 1 and 2 may crash due to insufficient memory. If that happens, simply re-run them.
file: ./content/self-host/upgrading/outdated/40.mdx
meta: {
"title": "V4.0（升级脚本）",
"description": "FastGPT 从旧版本升级到 V4.0 操作指南"
}
import { Alert } from '@/components/docs/Alert';
如果您是**从旧版本升级到 V4**，由于新版 MongoDB 表变更比较大，需要按照本文档的说明执行一些初始化脚本。
## 重命名表名
需要连接上 MongoDB 数据库，执行两条命令：
```js
db.models.renameCollection('apps');
db.sharechats.renameCollection('outlinks');
```
注意：从旧版更新到 V4， MongoDB 会自动创建空表，你需要先手动删除这两个空表，再执行上面的操作。
## 初始化几个表中的字段
依次执行下面 3 条命令，时间比较长，不成功可以重复执行（会跳过已经初始化的数据），直到所有数据更新完成。
```js
db.chats.find({ appId: { $exists: false } }).forEach(function (item) {
db.chats.updateOne(
{
_id: item._id
},
{ $set: { appId: item.modelId } }
);
});
db.collections.find({ appId: { $exists: false } }).forEach(function (item) {
db.collections.updateOne(
{
_id: item._id
},
{ $set: { appId: item.modelId } }
);
});
db.outlinks.find({ shareId: { $exists: false } }).forEach(function (item) {
db.outlinks.updateOne(
{
_id: item._id
},
{ $set: { shareId: item._id.toString(), appId: item.modelId } }
);
});
```
## 初始化 API
部署新版项目，并发起 3 个 HTTP 请求（记得携带 `headers.rootkey`，这个值是环境变量里的）
1. [https://xxxxx/api/admin/initv4](https://xxxxx/api/admin/initv4)
2. [https://xxxxx/api/admin/initChat](https://xxxxx/api/admin/initChat)
3. [https://xxxxx/api/admin/initOutlink](https://xxxxx/api/admin/initOutlink)
1 和 2 有可能会因为内存不足挂掉，可以重复执行。
file: ./content/self-host/upgrading/outdated/41.en.mdx
meta: {
"title": "V4.1 (Environment Changes, Upgrade Script)",
"description": "Upgrade guide from older versions to FastGPT V4.1"
}
If you are **upgrading from an older version to V4.1**, the chat storage structure has been redesigned. You'll need to initialize the existing stored data.
## Update Environment Variables
V4.1 simplified the PostgreSQL and MongoDB connection variables — you now only need a single URL for each:
Note: `/fastgpt` and `/postgres` refer to database names and must match the values from your previous configuration.
```bash
# MongoDB config — no changes needed. If connection fails, try removing ?authSource=admin
- MONGODB_URI=mongodb://username:password@mongo:27017/fastgpt?authSource=admin
# PostgreSQL config — no changes needed
- PG_URL=postgresql://username:password@pg:5432/postgres
```
## Initialization API
Deploy the new version, then send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables):
* [https://xxxxx/api/admin/initChatItem](https://xxxxx/api/admin/initChatItem)
file: ./content/self-host/upgrading/outdated/41.mdx
meta: {
"title": "V4.1（环境变量变更、升级脚本）",
"description": "FastGPT 从旧版本升级到 V4.1 操作指南"
}
如果您是**从旧版本升级到 V4.1**，由于新版重新设置了对话存储结构，需要初始化原来的存储内容。
## 更新环境变量
V4.1 优化了 PostgreSQL 和 MongoDB 的连接变量，只需要填 1 个 URL 即可：
注意：/fastgpt 和 /postgres 是指数据库名称，需要和旧版的变量对应。
```bash
# mongo 配置，不需要改. 如果连不上，可能需要去掉 ?authSource=admin
- MONGODB_URI=mongodb://username:password@mongo:27017/fastgpt?authSource=admin
# pg配置. 不需要改
- PG_URL=postgresql://username:password@pg:5432/postgres
```
## 初始化 API
部署新版项目，并发起 1 个 HTTP 请求（记得携带 `headers.rootkey`，这个值是环境变量里的）
* [https://xxxxx/api/admin/initChatItem](https://xxxxx/api/admin/initChatItem)
file: ./content/self-host/upgrading/outdated/4100.en.mdx
meta: {
"title": "V4.10.0 (Environment Changes)",
"description": "FastGPT V4.10.0 Update Notes"
}
## Upgrade Guide
### Docker Deployment
* Refer to the latest [docker-compose.yml](https://github.com/labring/FastGPT/blob/main/document/public/deploy/docker/main/global/docker-compose.pg.yml) file to add the `fastgpt-plugin` and `minio` services.
* Set the `fastgpt-plugin` environment variable `AUTH_TOKEN` to a sufficiently complex value.
* Set the `fastgpt-plugin` environment variable `MINIO_CUSTOM_ENDPOINT` to `http://ip:port` or a relevant domain name that is accessible to FastGPT users.
* Update the environment variables for the `fastgpt` and `fastgpt-pro` (commercial edition) containers:
```
PLUGIN_BASE_URL=http://fastgpt-plugin:3000
PLUGIN_TOKEN=the AUTH_TOKEN value you just set
```
* Update the `fastgpt` and `fastgpt-pro` image tags to: v4.10.0-fix
* Run `docker-compose up -d` to start/update all services.
### Sealos Deployment
* In the Sealos desktop `Object Storage`, create a new bucket with `publicRead` permissions and obtain the relevant credentials:
* Deploy the `fastgpt-plugin` service using the image `registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-plugin:v0.1.0`. Expose internal port 3000 (no public access required) and set the following environment variables:
```
AUTH_TOKEN=authentication token
# Log level: debug, info, warn, error
LOG_LEVEL=info
# S3 configuration
MINIO_CUSTOM_ENDPOINT=External
MINIO_ENDPOINT=Internal address
MINIO_PORT=80
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=Access Key
MINIO_SECRET_KEY=Secret Key
MINIO_BUCKET=bucket name
```
* Update the environment variables and image tags for the `fastgpt` and `fastgpt-pro` (commercial edition) containers to: v4.10.0-fix
```
PLUGIN_BASE_URL=internal address of the fastgpt-plugin service
PLUGIN_TOKEN=the AUTH_TOKEN value you just set
```
## New Features
1. Standalone system tool service with support for independent development and debugging of system tools.
2. Updated [System Tool Development Guide](../../../plugin/system-tool-development.en.mdx).
3. Updated [Plugin System Overview](../../../plugin/intro.en.mdx).
file: ./content/self-host/upgrading/outdated/4100.mdx
meta: {
"title": "V4.10.0（环境变量变更）",
"description": "FastGPT V4.10.0 更新说明"
}
## 更新指南
### Docker 版本
* 参考最新的 [docker-compose.yml](https://github.com/labring/FastGPT/blob/main/document/public/deploy/docker/main/global/docker-compose.pg.yml) 文件，加入 `fastgpt-plugin` 和 `minio` 服务。
* 修改 `fastgpt-plugin` 环境变量 `AUTH_TOKEN` 为较复杂的值。
* 修改 `fastgpt-plugin` 环境变量 `MINIO_CUSTOM_ENDPOINT` 为 `http://ip:port` 或相关域名，要求 fastgpt 用户可访问。
* 更新 `fastgpt` 和 `fastgpt-pro` (商业版)容器的环境变量:
```
PLUGIN_BASE_URL=http://fastgpt-plugin:3000
PLUGIN_TOKEN=刚修改的 AUTH_TOKEN 值
```
* 更新 `fastgpt` 和 `fastgpt-pro` 镜像 tag: v4.10.0-fix
* `docker-compose up -d` 启动/更新所有服务。
### Sealos 版本
* 在 Sealos 桌面的 `对象存储` 中，新建一个存储桶，设置 `publicRead` 权限。并获取相关密钥：
* 部署 `fastgpt-plugin` 服务，镜像 `registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-plugin:v0.1.0`，内网暴露端口 3000，无需公网访问，设置环境变量:
```
AUTH_TOKEN=鉴权 token
# 日志等级: debug,info,warn,error
LOG_LEVEL=info
# S3 配置
MINIO_CUSTOM_ENDPOINT=External
MINIO_ENDPOINT=Internal地址
MINIO_PORT=80
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=Access Key
MINIO_SECRET_KEY=Secret Key
MINIO_BUCKET=存储桶名
```
* 更新 `fastgpt` 和 `fastgpt-pro` (商业版)容器的环境变量以及镜像 tag: v4.10.0-fix
```
PLUGIN_BASE_URL=fastgpt-plugin 服务的内网地址
PLUGIN_TOKEN=刚修改的 AUTH_TOKEN 值
```
## 🚀 新增内容
1. 独立系统工具服务，支持系统工具独立开发和调试。
2. 更新系统工具开发指南[系统工具开发指南](../../../plugin/system-tool-development.mdx)。
3. 更新[插件系统说明](../../../plugin/intro.mdx)。
file: ./content/self-host/upgrading/outdated/4101.en.mdx
meta: {
"title": "V4.10.1 (Upgrade Script)",
"description": "FastGPT V4.10.1 Update Notes"
}
## Upgrade Guide
### 1. Update Images:
* Update FastGPT image tag: v4.10.1-fix3
* Update FastGPT commercial edition image tag: v4.10.1
* Update fastgpt-plugin image tag: v0.1.3
* mcp\_server: no update required
* Sandbox: no update required
* AIProxy: no update required
### 2. Run the Migration Script
This script only needs to be run by commercial edition users.
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4101' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
* Adds new scheduled tasks for auto-synced knowledge bases.
## New Features
1. System tools now support streaming output.
2. Commercial edition: scheduled sync for third-party knowledge bases now supports full sync, including entire directories.
## Improvements
1. Scheduled task error logs are now recorded in the chat logs.
2. Encapsulated dynamic form rendering component for apps.
3. Directory breadcrumb navigation now truncates on overflow.
## Bug Fixes
1. Search-type system tools were not displaying correctly.
2. Backward compatibility issues with some system tools.
3. AI node: manually selecting chat history caused duplicate system records.
4. Knowledge base tags could not scroll to the bottom.
5. When importing files via API to an API-based knowledge base, custom API parsing parameters were not applied.
## Tool Updates
1. New: Flux official image generation tool.
2. New: JinaAI toolset.
3. New: Alibaba Cloud Bailian Flux and Tongyi Wanxiang image generation.
4. Fixed incorrect output value type for SiliconFlow image generation tool.
file: ./content/self-host/upgrading/outdated/4101.mdx
meta: {
"title": "V4.10.1（升级脚本）",
"description": "FastGPT V4.10.1 更新说明"
}
## 更新指南
### 1. 更新镜像：
* 更新 FastGPT 镜像tag: v4.10.1-fix3
* 更新 FastGPT 商业版镜像tag: v4.10.1
* 更新 fastgpt-plugin 镜像 tag: v0.1.3
* mcp\_server 无需更新
* Sandbox 无需更新
* AIProxy 无需更新
### 2. 执行升级脚本
该脚本仅需商业版用户执行。
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**。
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4101' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
* 给自动同步的知识库加入新的定时任务。
## 🚀 新增内容
1. 系统工具支持流输出。
2. 商业版第三方知识库定时同步，支持全量同步，可以同步整个目录。
## ⚙️ 优化
1. 定时任务报错日志记录到对话日志。
2. 封装应用动态form渲染组件。
3. 目录面包屑导航溢出省略。
## 🐛 修复
1. 搜索类型系统工具无法正常显示。
2. 部分系统工具向下兼容问题。
3. AI 节点，手动选择历史记录时，会导致 system 记录重复。
4. 知识库 tag 无法滚动到底。
5. API 知识库通过 API 导入文件时，自定义 API 解析参数未生效。
## 🔨 工具更新
1. 新增 Flux 官方绘图工具。
2. 新增 JinaAI 工具集。
3. 新增阿里百炼 Flux 和通义万相绘图。
4. 纠正硅基流动画图工具输出值类型。
file: ./content/self-host/upgrading/outdated/4110.en.mdx
meta: {
"title": "V4.11.0 (Environment Changes)",
"description": "FastGPT V4.11.0 Update Notes"
}
## Upgrade Guide
### 1. Update Environment Variables
Commercial edition users can add the following evaluation-related environment variables, then click Save once in the admin panel after updating.
```
EVAL_CONCURRENCY=3 # Evaluation single-node concurrency
EVAL_LINE_LIMIT=1000 # Maximum lines per evaluation file
```
### 2. Update Images:
* Update FastGPT image tag: v4.11.0
* Update FastGPT commercial edition image tag: v4.11.0
* Update fastgpt-plugin image tag: v0.1.5
* mcp\_server: no update required
* Sandbox: no update required
* AIProxy: no update required
## Project Changes
1. Removed all restrictions on **open-source features**, including limits on the number of apps and knowledge bases.
2. Updated the roadmap to include `Context Management`, `AI-Generated Workflows`, `Advanced Orchestration Debug Mode`, and more.
3. The international domain has been changed from `fastgpt.io` to `fastgpt.io`.
## New Features
1. Commercial edition: added **App Evaluation (Beta)** for supervised scoring of apps.
2. Workflow nodes now support error-catching branches.
3. Chat page: independent tab UX.
4. Support for Signoz traces and logs system monitoring.
5. Added model configurations for Gemini 2.5, Grok 4, and Kimi.
6. Model invocation logs now include time-to-first-token and request IP.
## Improvements
1. Optimized code to prevent memory buildup from recursion, significantly reducing memory consumption during high-concurrency knowledge base preprocessing.
2. Knowledge base training: support for retrying all failed data in a collection at once.
3. Workflow valueTypeFormat to prevent data type inconsistencies.
4. Knowledge base list search now properly escapes special characters in regex.
## Bug Fixes
1. Question classification and content extraction nodes: default model failed frontend validation, preventing workflow execution and publishing.
## Tool Updates
1. Markdown text to Docx and Xlsx file conversion.
file: ./content/self-host/upgrading/outdated/4110.mdx
meta: {
"title": "V4.11.0（环境变量变更）",
"description": "FastGPT V4.11.0 更新说明"
}
## 升级说明
### 1. 修改环境变量
FastGPT 商业版用户，可以增加评估相关环境变量，并在更新后，在管理端点击一次保存。
```
EVAL_CONCURRENCY=3 # 评估单节点并发数
EVAL_LINE_LIMIT=1000 # 评估文件最大行数
```
### 2. 更新镜像：
* 更新 FastGPT 镜像tag: v4.11.0
* 更新 FastGPT 商业版镜像tag: v4.11.0
* 更新 fastgpt-plugin 镜像 tag: v0.1.5
* mcp\_server 无需更新
* Sandbox 无需更新
* AIProxy 无需更新
## 项目调整
1. 移除所有**开源功能**的限制，包括：应用数量和知识库数量上限。
2. 调整 RoadMap，增加`上下文管理`,`AI 生成工作流`,`高级编排 DeBug 调试模式`等计划。
3. 国际版域名将`fastgpt.io`调整成`fastgpt.io`。
## 🚀 新增内容
1. 商业版增加**应用评测(Beta 版)**，可对应用进行有监督评分。
2. 工作流部分节点支持报错捕获分支。
3. 对话页独立 tab 页面UX。
4. 支持 Signoz traces 和 logs 系统追踪。
5. 新增 Gemini2.5, grok4, kimi 模型配置。
6. 模型调用日志增加首字响应时长和请求 IP。
## ⚙️ 优化
1. 优化代码，避免递归造成的内存堆积，尤其在高并发连续的进行知识库预处理时，可显著降低内存消耗。
2. 知识库训练：支持全部重试当前集合异常数据。
3. 工作流 valueTypeFormat，避免数据类型不一致。
4. 知识库列表搜索时，正则未进行特殊词替换。
## 🐛 修复
1. 问题分类和内容提取节点，默认模型无法通过前端校验，导致工作流无法运行和保存发布。
## 🔨 工具更新
1. Markdown 文本转 Docx 和 Xlsx 文件。
file: ./content/self-host/upgrading/outdated/4111.en.mdx
meta: {
"title": "V4.11.1",
"description": "FastGPT V4.11.1 Update Notes"
}
## Upgrade Guide
### 1. Update Images:
* Update FastGPT image tag: v4.11.1-fix2
* Update FastGPT commercial edition image tag: v4.11.1-fix
* Update fastgpt-plugin image tag: v0.1.7
* mcp\_server: no update required
* Sandbox: no update required
* AIProxy: no update required
## New Features
1. System tools: toolsets can now be used directly for tool calls.
2. MCP architecture rewrite — after updating MCP, all active MCP components are automatically updated without needing to remove and re-add them.
3. Chat log dashboard now supports custom field display.
4. Account deletion.
5. New documentation framework.
6. GLM 4.5 series model configurations.
## Improvements
1. Redemption code feature now supports specifying corporate payment mode.
2. Optimized payment plan mode.
3. Renaming a global variable no longer causes referenced values in nodes to be lost.
4. Moved model preset configurations to the FastGPT Plugin project.
## Bug Fixes
1. MCP object-type data was passed incorrectly.
2. Login page UI misalignment.
3. Excel files with line break characters caused chunking errors.
4. Doc2x PDF parsing: removed extraneous tags.
5. 404 page translations were not applied.
## Tool Updates
1. New: libulibu drawing tool.
2. New: Metaso search tool.
3. New: Signoz system monitoring integration.
4. Fixed: incorrect data type in the math expression tool.
file: ./content/self-host/upgrading/outdated/4111.mdx
meta: {
"title": "V4.11.1",
"description": "FastGPT V4.11.1 更新说明"
}
## 升级说明
### 1. 更新镜像：
* 更新 FastGPT 镜像tag: v4.11.1-fix2
* 更新 FastGPT 商业版镜像tag: v4.11.1-fix
* 更新 fastgpt-plugin 镜像 tag: v0.1.7
* mcp\_server 无需更新
* Sandbox 无需更新
* AIProxy 无需更新
## 🚀 新增内容
1. 系统工具，工具集支持直接给工具调用使用。
2. MCP 结构重写，更新 MCP后，会自动更新所有在用的 MCP 组件，无需重新删除再添加。
3. 对话日志看板，支持自定义字段展示。
4. 账号注销。
5. 新文档框架。
6. GLM 4.5 系列模型配置。
## ⚙️ 优化
1. 兑换码功能支持指定对公支付模式。
2. 优化支付套餐模式。
3. 全局变量修改变量名后，节点中的引用值不会丢失。
4. 将模型预设配置移动到 FastGPT Plugin 项目中。
## 🐛 修复
1. MCP object 类型数据传递错误。
2. 登录页 UI 偏移。
3. Excel 表带有换行符号时，导致分块异常。
4. Doc2x PDF 识别去除多余标签。
5. 404 页面翻译失效。
## 🔨 工具更新
1. 新增：libulibu 绘图工具。
2. 新增：秘塔搜索工具。
3. 新增：支持 Signoz 系统监控接入。
4. 修复：数学表达式工具数据类型错误。
file: ./content/self-host/upgrading/outdated/42.en.mdx
meta: {
"title": "V4.2",
"description": "Upgrade guide from older versions to FastGPT V4.2"
}
99.9% of users are unaffected. The V4.2 upgrade primarily changes the `QAModel` format in the configuration file, converting it from an array to an object:
```json
"QAModel": {
"model": "gpt-3.5-turbo-16k",
"name": "GPT35-16k",
"maxToken": 16000,
"price": 0
}
```
The rationale behind this change is that there's no need to offer multiple choices — just pick the most suitable model for the task.
file: ./content/self-host/upgrading/outdated/42.mdx
meta: {
"title": "V4.2",
"description": "FastGPT 从旧版本升级到 V4.2 操作指南"
}
99.9%用户不影响，升级 4.2 主要是修改了配置文件中 QAModel 的格式。从原先的数组改成对象：
```json
"QAModel": {
"model": "gpt-3.5-turbo-16k",
"name": "GPT35-16k",
"maxToken": 16000,
"price": 0
}
```
改动目的是，我们认为不需要留有选择余地，选择一个最合适的模型去进行任务即可。
file: ./content/self-host/upgrading/outdated/421.en.mdx
meta: {
"title": "V4.2.1",
"description": "Upgrade guide from older versions to FastGPT V4.2.1"
}
For self-hosted deployments with a custom configuration file, you need to update the `VectorModels` field. Add `defaultToken` and `maxToken` — these correspond to the default token count for direct chunking and the maximum token limit supported by the model (generally recommended not to exceed 3000).
```json
"VectorModels": [
{
"model": "text-embedding-ada-002",
"name": "Embedding-2",
"price": 0,
"defaultToken": 500,
"maxToken": 3000
}
]
```
The rationale behind this change is that there's no need to offer multiple choices — just pick the most suitable model for the task.
file: ./content/self-host/upgrading/outdated/421.mdx
meta: {
"title": "V4.2.1",
"description": "FastGPT 从旧版本升级到 V4.2.1 操作指南"
}
私有部署，如果添加了配置文件，需要在配置文件中修改 `VectorModels` 字段。增加 defaultToken 和 maxToken，分别对应直接分段时的默认 token 数量和该模型支持的 token 上限 (通常不建议超过 3000)
```json
"VectorModels": [
{
"model": "text-embedding-ada-002",
"name": "Embedding-2",
"price": 0,
"defaultToken": 500,
"maxToken": 3000
}
]
```
改动目的是，我们认为不需要留有选择余地，选择一个最合适的模型去进行任务即可。
file: ./content/self-host/upgrading/outdated/43.en.mdx
meta: {
"title": "V4.3 (Environment Changes, Upgrade Script)",
"description": "Upgrade guide from older versions to FastGPT V4.3"
}
## Run the Initialization API
Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables):
1. [https://xxxxx/api/admin/initv43](https://xxxxx/api/admin/initv43)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv43' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This will add a new `file_id` column to the `modeldata` table in PostgreSQL, used for storing file IDs.
## Add Environment Variable
Add a `FILE_TOKEN_KEY` environment variable, used to generate file preview links with a 30-minute expiration.
```
FILE_TOKEN_KEY=filetokenkey
```
file: ./content/self-host/upgrading/outdated/43.mdx
meta: {
"title": "V4.3（环境变量变更、升级脚本）",
"description": "FastGPT 从旧版本升级到 V4.3 操作指南"
}
## 执行初始化 API
发起 1 个 HTTP 请求 (记得携带 `headers.rootkey`，这个值是环境变量里的)
1. [https://xxxxx/api/admin/initv43](https://xxxxx/api/admin/initv43)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv43' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会给 PG 数据库的 modeldata 表插入一个新列 file\_id，用于存储文件 ID。
## 增加环境变量
增加一个 `FILE_TOKEN_KEY` 环境变量，用于生成文件预览链接，过期时间为 30 分钟。
```
FILE_TOKEN_KEY=filetokenkey
```
file: ./content/self-host/upgrading/outdated/44.en.mdx
meta: {
"title": "V4.4 (Upgrade Script)",
"description": "Upgrade guide from older versions to FastGPT V4.4"
}
## Run the Initialization API
Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables):
1. [https://xxxxx/api/admin/initv44](https://xxxxx/api/admin/initv44)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv44' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This will initialize certain fields in MongoDB.
file: ./content/self-host/upgrading/outdated/44.mdx
meta: {
"title": "V4.4（升级脚本）",
"description": "FastGPT 从旧版本升级到 V4.4 操作指南"
}
## 执行初始化 API
发起 1 个 HTTP 请求 (记得携带 `headers.rootkey`，这个值是环境变量里的)
1. [https://xxxxx/api/admin/initv44](https://xxxxx/api/admin/initv44)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv44' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会给初始化 Mongo 的部分字段。
file: ./content/self-host/upgrading/outdated/441.en.mdx
meta: {
"title": "V4.4.1 (Upgrade Script)",
"description": "Upgrade guide from older versions to FastGPT V4.4.1"
}
## Run the Initialization API
Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables):
1. [https://xxxxx/api/admin/initv441](https://xxxxx/api/admin/initv441)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv441' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This will initialize the `dataset.files` collection in MongoDB, marking all data as available.
file: ./content/self-host/upgrading/outdated/441.mdx
meta: {
"title": "V4.4.1（升级脚本）",
"description": "FastGPT 从旧版本升级到 V4.4.1 操作指南"
}
## 执行初始化 API
发起 1 个 HTTP 请求（记得携带 `headers.rootkey`，这个值是环境变量里的）
1. [https://xxxxx/api/admin/initv441](https://xxxxx/api/admin/initv441)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv441' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会给初始化 Mongo 的 dataset.files，将所有数据设置为可用。
file: ./content/self-host/upgrading/outdated/442.en.mdx
meta: {
"title": "V4.4.2 (Upgrade Script)",
"description": "Upgrade guide from older versions to FastGPT V4.4.2"
}
## Run the Initialization API
Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables):
1. [https://xxxxx/api/admin/initv442](https://xxxxx/api/admin/initv442)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv442' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This will reinitialize the indexes on the MongoDB `Bill` collection, as the previous TTL expiration was incorrect.
file: ./content/self-host/upgrading/outdated/442.mdx
meta: {
"title": "V4.4.2（升级脚本）",
"description": "FastGPT 从旧版本升级到 V4.4.2 操作指南"
}
## 执行初始化 API
发起 1 个 HTTP 请求 (记得携带 `headers.rootkey`，这个值是环境变量里的)
1. [https://xxxxx/api/admin/initv442](https://xxxxx/api/admin/initv442)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv442' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会给初始化 Mongo 的 Bill 表的索引，之前过期时间有误。
file: ./content/self-host/upgrading/outdated/445.en.mdx
meta: {
"title": "V4.4.5 (Upgrade Script)",
"description": "FastGPT V4.4.5 Update"
}
## Run the Initialization API
Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables):
1. [https://xxxxx/api/admin/initv445](https://xxxxx/api/admin/initv445)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv445' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This initializes the variable module by merging it into the user guide module.
## What's New
### FastGPT V4.4.5
1. Added — Next-step suggestions: the model can now generate 3 predicted follow-up questions.
2. Commercial edition — Share link restrictions and hook-based identity verification (can integrate with your existing user system).
3. Commercial edition — API Key management: added alias, quota limits, and expiration. Includes a built-in appId, so no additional connection is needed.
4. Improved — Global variables and opening message merged into a single module.
file: ./content/self-host/upgrading/outdated/445.mdx
meta: {
"title": "V4.4.5（升级脚本）",
"description": "FastGPT V4.4.5 更新"
}
## 执行初始化 API
发起 1 个 HTTP 请求（记得携带 `headers.rootkey`，这个值是环境变量里的）
1. [https://xxxxx/api/admin/initv445](https://xxxxx/api/admin/initv445)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv445' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化了 variable 模块，将其合并到用户引导模块中。
## 功能介绍
### Fast GPT V4.4.5
1. 新增 - 下一步指引选项，可以通过模型生成 3 个预测问题。
2. 商业版新增 - 分享链接限制及 hook 身份校验（可对接已有的用户系统）。
3. 商业版新增 - Api Key 使用。增加别名、额度限制和过期时间。自带 appId，无需额外连接。
4. 优化 - 全局变量与开场白合并成同一模块。
file: ./content/self-host/upgrading/outdated/446.en.mdx
meta: {
"title": "V4.4.6",
"description": "FastGPT V4.4.6 Update"
}
## What's New
1. Advanced orchestration — New "App Call" module that lets you invoke other apps.
2. Added — Required connection validation.
3. Fixed — Identity issue with next-step suggestions in anonymous (no-login) mode.
file: ./content/self-host/upgrading/outdated/446.mdx
meta: {
"title": "V4.4.6",
"description": "FastGPT V4.4.6 更新"
}
## 功能介绍
1. 高级编排新增模块 - 应用调用，可调用其他应用。
2. 新增 - 必要连接校验
3. 修复 - 下一步指引在免登录中身份问题。
file: ./content/self-host/upgrading/outdated/447.en.mdx
meta: {
"title": "V4.4.7 (Upgrade Script)",
"description": "FastGPT V4.4.7 Update (includes upgrade script)"
}
## Run the Initialization API
Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain):
1. [https://xxxxx/api/admin/initv447](https://xxxxx/api/admin/initv447)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv447' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This initializes PostgreSQL indexes and converts empty `file_id` objects to `manual` objects. If you have a large dataset, this may take a while — you can monitor progress via logs.
## What's New
### FastGPT V4.4.7
1. Improved Knowledge Base file CRUD operations.
2. Added support for reading links as a data source.
3. Differentiated between manual entries and annotations, enabling data traceability back to a specific file.
4. Upgraded the OpenAI SDK.
file: ./content/self-host/upgrading/outdated/447.mdx
meta: {
"title": "V4.4.7（升级脚本）",
"description": "FastGPT V4.4.7 更新（包含升级脚本）"
}
## 执行初始化 API
发起 1 个 HTTP 请求（`{{rootkey}}` 替换成环境变量里的`rootkey`，`{{host}}`替换成自己域名）
1. [https://xxxxx/api/admin/initv447](https://xxxxx/api/admin/initv447)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv447' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化 pg 索引以及将 file\_id 中空对象转成 manual 对象。如果数据多，可能需要较长时间，可以通过日志查看进度。
## 功能介绍
### Fast GPT V4.4.7
1. 优化了数据库文件 crud。
2. 兼容链接读取，作为 source。
3. 区分手动录入和标注，可追数据至某个文件。
4. 升级 openai sdk。
file: ./content/self-host/upgrading/outdated/45.en.mdx
meta: {
"title": "V4.5 (Complex Update Required)",
"description": "FastGPT V4.5 Update"
}
FastGPT V4.5 introduces PgVector 0.5's HNSW index, which dramatically improves knowledge base search performance — roughly 3x to 10x faster than the `IVFFlat` index, easily achieving millisecond-level searches across millions of records. The downside is that index building is very slow: on a 4C16G machine with 5 million records, a `parallel build` took about 48 hours. For detailed parameter configuration, refer to the [PgVector official documentation](https://github.com/pgvector/pgvector).
The following database operations are required for the upgrade:
## PgVector Upgrade: Sealos Deployment
1. Open the Database app from the [Sealos Desktop](https://cloud.sealos.io?uid=fnWRt09fZP).
2. Click on the details of the **pg** database.
3. Click Restart in the upper-right corner and wait for it to complete.
4. Click "One-Click Connect" on the left sidebar and wait for the Terminal to open.
5. Run the following SQL commands in order:
```sql
-- Upgrade the extension
ALTER EXTENSION vector UPDATE;
-- Verify the upgrade was successful — the vector extension version should be 0.5.0 (previously 0.4.1)
\dx
-- The following two statements set the memory available to PG during index building. Adjust based on your database specs — a good rule of thumb is 1/4 of total memory.
alter system set maintenance_work_mem = '2400MB';
select pg_reload_conf();
-- Rebuild database indexes and collation
REINDEX DATABASE postgres;
-- Start building the index. This takes a very long time — just close the Terminal by clicking the X in the upper-right corner.
CREATE INDEX CONCURRENTLY vector_index ON modeldata USING hnsw (vector vector_ip_ops) WITH (m = 16, ef_construction = 64);
-- You can reconnect to the Terminal and run the command below. If you see "vector_index" hnsw (vector vector_ip_ops) WITH (m='16', ef_construction='64'), the build is complete (make sure there is no INVALID at the end).
\d modeldata
```
| | |
| -------------------------------------- | -------------------------------------- |
|  |  |
|  |  |
## PgVector Upgrade: Docker Compose Deployment
The commands below are based on the provided docker-compose template. If you've changed the database username or password, adjust accordingly.
1. Update the PG image version in `docker-compose.yml` to `ankane/pgvector:v0.5.0` or `registry.cn-hangzhou.aliyuncs.com/fastgpt/pgvector:v0.5.0`.
2. Restart the PG container (`docker-compose pull && docker-compose up -d`) and wait for it to complete.
3. Enter the container: `docker exec -it pg bash`
4. Connect to the database: `psql 'postgresql://username:password@localhost:5432/postgres'`
5. Run the following SQL commands:
```sql
-- Upgrade the extension
ALTER EXTENSION vector UPDATE;
-- Verify the upgrade was successful — the vector extension version should be 0.5.0 (previously 0.4.2)
\dx
-- The following two statements set the memory available to PG during index building. Adjust based on your database specs — a good rule of thumb is 1/4 of total memory.
alter system set maintenance_work_mem = '2400MB';
select pg_reload_conf();
-- Rebuild database indexes and collation
REINDEX DATABASE postgres;
ALTER DATABASE postgres REFRESH COLLATION VERSION;
-- Start building the index. This takes a very long time — just close the terminal window. Do NOT use ctrl+c to cancel.
CREATE INDEX CONCURRENTLY vector_index ON modeldata USING hnsw (vector vector_ip_ops) WITH (m = 16, ef_construction = 64);
-- You can reconnect to the database and run the command below. If you see "vector_index" hnsw (vector vector_ip_ops) WITH (m='16', ef_construction='64'), the build is complete (make sure there is no INVALID at the end).
\d modeldata
```
## New Features
### Fast GPT V4.5
1. New - Upgraded PgVector extension with HNSW index, dramatically improving knowledge base search speed.
2. New - AI Chat node now includes a "Return AI Content" option, allowing you to prevent AI responses from being sent directly to the browser.
3. New - Support for selecting models in the Question Classifier.
4. Improved - TextSplitter now uses a recursive splitting approach.
5. Improved - Advanced orchestration UX performance.
6. Fixed - Share link authentication issue.
## Configuration File Changes Required
The legacy `config.json` guide is no longer maintained. For current versions, see [Model Configuration](../../config/model/intro.en.mdx).
file: ./content/self-host/upgrading/outdated/45.mdx
meta: {
"title": "V4.5(需进行较为复杂更新)",
"description": "FastGPT V4.5 更新"
}
FastGPT V4.5 引入 PgVector0.5 版本的 HNSW 索引，极大的提高了知识库检索的速度，比起 `IVFFlat` 索引大致有 3\~10 倍的性能提升，可轻松实现百万数据毫秒级搜索。缺点在于构建索引的速度非常慢，4c16g 500w 组数据使用 `并行构建` 大约花了 48 小时。具体参数配置可参考 [PgVector 官方](https://github.com/pgvector/pgvector)
下面需要对数据库进行一些操作升级：
## PgVector 升级：Sealos 部署方案
1. 点击 [Sealos 桌面](https://cloud.sealos.io?uid=fnWRt09fZP)的数据库应用。
2. 点击【pg】数据库的详情。
3. 点击右上角的重启，等待重启完成。
4. 点击左侧的一键链接，等待打开 Terminal。
5. 依次输入下方 sql 命令
```sql
-- 升级插件名
ALTER EXTENSION vector UPDATE;
-- 插件是否升级成功，成功的话，vector插件版本为 0.5.0，旧版的为 0.4.1
\dx
-- 下面两个语句会设置 pg 在构建索引时可用的内存大小，需根据自身的数据库规格来动态配置，可配置为 1/4 的内存大小
alter system set maintenance_work_mem = '2400MB';
select pg_reload_conf();
-- 重构数据库索引和排序
REINDEX DATABASE postgres;
-- 开始构建索引，该索引构建时间非常久，直接点击右上角的叉，退出 Terminal 即可
CREATE INDEX CONCURRENTLY vector_index ON modeldata USING hnsw (vector vector_ip_ops) WITH (m = 16, ef_construction = 64);
-- 可以再次点击一键链接，进入 Terminal，输入下方命令，如果看到 "vector_index" hnsw (vector vector_ip_ops) WITH (m='16', ef_construction='64') 则代表构建完成（注意，后面没有 INVALID）
\d modeldata
```
| | |
| -------------------------------------- | -------------------------------------- |
|  |  |
|  |  |
## PgVector 升级：Docker-compose.yml 部署方案
下面的命令是基于给的 docker-compose 模板，如果数据库账号密码更换了，请自行调整。
1. 修改 `docker-compose.yml` 中 pg 的镜像版本，改成 `ankane/pgvector:v0.5.0` 或 `registry.cn-hangzhou.aliyuncs.com/fastgpt/pgvector:v0.5.0`
2. 重启 pg 容器(docker-compose pull && docker-compose up -d)，等待重启完成。
3. 进入容器: `docker exec -it pg bash`
4. 连接数据库: `psql 'postgresql://username:password@localhost:5432/postgres'`
5. 执行下面 sql 命令
```sql
-- 升级插件名
ALTER EXTENSION vector UPDATE;
-- 插件是否升级成功，成功的话，vector插件版本为 0.5.0，旧版的为 0.4.2
\dx
-- 下面两个语句会设置 pg 在构建索引时可用的内存大小，需根据自身的数据库规格来动态配置，可配置为 1/4 的内存大小
alter system set maintenance_work_mem = '2400MB';
select pg_reload_conf();
-- 重构数据库索引和排序
REINDEX DATABASE postgres;
ALTER DATABASE postgres REFRESH COLLATION VERSION;
-- 开始构建索引，该索引构建时间非常久，直接关掉终端即可，不要使用 ctrl+c 关闭
CREATE INDEX CONCURRENTLY vector_index ON modeldata USING hnsw (vector vector_ip_ops) WITH (m = 16, ef_construction = 64);
-- 可以再次连接数据库，输入下方命令。如果看到 "vector_index" hnsw (vector vector_ip_ops) WITH (m='16', ef_construction='64') 则代表构建完成（注意，后面没有 INVALID）
\d modeldata
```
## 版本新功能介绍
### Fast GPT V4.5
1. 新增 - 升级 PgVector 插件，引入 HNSW 索引，极大加快的知识库搜索速度。
2. 新增 - AI 对话模块，增加【返回 AI 内容】选项，可控制 AI 的内容不直接返回浏览器。
3. 新增 - 支持问题分类选择模型
4. 优化 - TextSplitter，采用递归拆解法。
5. 优化 - 高级编排 UX 性能
6. 修复 - 分享链接鉴权问题
## 该版本需要修改 `config.json` 文件
旧版 `config.json` 配置说明已不再维护，当前版本请参考[模型配置方案](../../config/model/intro.mdx)。
file: ./content/self-host/upgrading/outdated/451.en.mdx
meta: {
"title": "V4.5.1 (Upgrade Script)",
"description": "FastGPT V4.5.1 Update"
}
## Run the Initialization API
Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain).
1. [https://xxxxx/api/admin/initv451](https://xxxxx/api/admin/initv451)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv451' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
What the initialization does:
1. Renames database fields.
2. Initializes knowledge base-related fields in the Mongo APP collection.
3. Initializes PG and Mongo content — creates a collection in Mongo for each file and assigns the references back to PG.
**This initialization endpoint may be very slow. If the request times out, don't worry — just check the logs.**
## What's New
### Fast GPT V4.5.1
1. New - Knowledge base folder management.
2. Fixed - OpenAI 4.x SDK incompatibility with OneAPI's Zhipu and Alibaba interfaces.
3. Fixed - Some nodes failing to trigger completion events.
file: ./content/self-host/upgrading/outdated/451.mdx
meta: {
"title": "V4.5.1（升级脚本）",
"description": "FastGPT V4.5.1 更新"
}
## 执行初始化 API
发起 1 个 HTTP 请求（`{{rootkey}}` 替换成环境变量里的`rootkey`，`{{host}}`替换成自己域名）
1. [https://xxxxx/api/admin/initv451](https://xxxxx/api/admin/initv451)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv451' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化内容：
1. rename 数据库字段
2. 初始化 Mongo APP 表中知识库的相关字段
3. 初始化 PG 和 Mongo 的内容，为每个文件创建一个集合（存储 Mongo 中），并反馈赋值给 PG。
**该初始化接口可能速度很慢，返回超时不用管，注意看日志即可**
## 功能介绍
### Fast GPT V4.5.1
1. 新增知识库文件夹管理
2. 修复了 openai4.x sdk 无法兼容 oneapi 的智谱和阿里的接口。
3. 修复部分模块无法触发完成事件
file: ./content/self-host/upgrading/outdated/452.en.mdx
meta: {
"title": "V4.5.2",
"description": "FastGPT V4.5.2 Update"
}
## What's New
### Fast GPT V4.5.2
1. New - Module plugins, allowing you to assemble custom plugins for module reuse.
2. Improved - Knowledge base citation prompts.
file: ./content/self-host/upgrading/outdated/452.mdx
meta: {
"title": "V4.5.2",
"description": "FastGPT V4.5.2 更新"
}
## 功能介绍
### Fast GPT V4.5.2
1. 新增 - 模块插件，允许自行组装插件进行模块复用。
2. 优化 - 知识库引用提示。
file: ./content/self-host/upgrading/outdated/46.en.mdx
meta: {
"title": "V4.6 (Upgrade Script)",
"description": "FastGPT V4.6 Update"
}
**V4.6 introduces basic team functionality, allowing you to invite other users to manage resources collaboratively. After upgrading to this version, older migration scripts cannot be run, and the upgrade cannot be rolled back.**
## 1. Update Images and Modify Configuration
Update the image to the latest or V4.6 version. For the commercial edition, update to V0.2.1.
The legacy `config.json` guide is no longer maintained. For current versions, see [Model Configuration](../../config/model/intro.en.mdx) and [Environment Variables](../../config/env.en.mdx). The commercial edition configuration file has also been updated — refer to the latest Lark documentation.
## 2. Run the Initialization APIs
Send 2 HTTP requests (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain).
**These initialization endpoints may be very slow. If the request times out, don't worry — just check the logs. Important: Make sure initv46 completes successfully before running initv46-2.**
1. [https://xxxxx/api/admin/initv46](https://xxxxx/api/admin/initv46)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv46' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
2. [https://xxxxx/api/admin/initv46-2](https://xxxxx/api/admin/initv46-2)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv46-2' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
What the initialization does:
1. Creates the default team.
2. Initializes team fields for all resources in Mongo.
3. Initializes PG fields.
4. Initializes Mongo Data.
## V4.6 New Features
1. New - Team workspace.
2. New - Multi-vector support (multiple vectors mapped to a single dataset).
3. New - TTS (text-to-speech).
4. New - Support for configuring text preprocessing models in knowledge bases.
5. New (Online environment) - ReRank vector recall for improved retrieval accuracy.
6. Improved - Knowledge base export now triggers a streaming download instead of showing a loading spinner.
## V4.6 Bug Fix
The initial V4.6 release was missing a field, which caused knowledge base data to not display during file imports. Run the following script to fix this:
[https://xxxxx/api/admin/initv46-fix](https://xxxxx/api/admin/initv46-fix)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv46-fix' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
file: ./content/self-host/upgrading/outdated/46.mdx
meta: {
"title": "V4.6（升级脚本）",
"description": "FastGPT V4.6 更新"
}
**V4.6 版本加入了简单的团队功能，可以邀请其他用户进来管理资源。该版本升级后无法执行旧的升级脚本，且无法回退。**
## 1。更新镜像并变更配置文件
更新镜像至 latest 或者 v4.6 版本。商业版镜像更新至 V0.2.1
旧版 `config.json` 配置说明已不再维护，当前版本请参考[模型配置方案](../../config/model/intro.mdx)和[环境变量说明](../../config/env.mdx)，商业镜像配置文件也更新，参考最新的飞书文档。
## 2。执行初始化 API
发起 2 个 HTTP 请求 ( `{{rootkey}}` 替换成环境变量里的 `rootkey`，`{{host}}` 替换成自己域名)
**该初始化接口可能速度很慢，返回超时不用管，注意看日志即可，需要注意的是，需确保 initv46 成功后，在执行 initv46-2**
1. [https://xxxxx/api/admin/initv46](https://xxxxx/api/admin/initv46)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv46' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
2. [https://xxxxx/api/admin/initv46-2](https://xxxxx/api/admin/initv46-2)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv46-2' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化内容：1。创建默认团队
2。初始化 Mongo 所有资源的团队字段
3。初始化 Pg 的字段
4。初始化 Mongo Data
## V4.6 功能介绍
1. 新增 - 团队空间
2. 新增 - 多路向量 (多个向量映射一组数据)
3. 新增 - tts 语音
4. 新增 - 支持知识库配置文本预处理模型
5. 线上环境新增 - ReRank 向量召回，提高召回精度
6. 优化 - 知识库导出，可直接触发流下载，无需等待转圈圈
## 4.6 缺陷修复
旧的 4.6 版本由于缺少一个字段，导致文件导入时知识库数据无法显示，可执行下面的脚本：
[https://xxxxx/api/admin/initv46-fix](https://xxxxx/api/admin/initv46-fix)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv46-fix' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
file: ./content/self-host/upgrading/outdated/461.en.mdx
meta: {
"title": "V4.6.1",
"description": "FastGPT V4.6.1"
}
## V4.6.1 New Features
1. New - GPT-4V model support.
2. New - Whisper voice input.
3. Improved - TTS streaming.
4. Improved - TTS caching.
file: ./content/self-host/upgrading/outdated/461.mdx
meta: {
"title": "V4.6.1",
"description": "FastGPT V4.6 .1"
}
## V4.6.1 功能介绍
1. 新增 - GPT4-v 模型支持
2. 新增 - whisper 语音输入
3. 优化 - TTS 流传输
4. 优化 - TTS 缓存
file: ./content/self-host/upgrading/outdated/462.en.mdx
meta: {
"title": "V4.6.2 (Upgrade Script)",
"description": "FastGPT V4.6.2"
}
## 1. Run the Initialization API
Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain).
1. [https://xxxxx/api/admin/initv462](https://xxxxx/api/admin/initv462)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv462' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
What the initialization does:
1. Initializes full-text indexing.
## V4.6.2 New Features
1. New - Full-text indexing (requires a ReRank model; working on making it available in the community edition — the model API is somewhat specialized).
2. New - Plugin sources (expected to be officially used in V4.7/V4.8).
3. Improved - PDF parsing.
4. Improved - DOCX file parsing, now converts to Markdown while preserving images.
5. Fixed and improved the TextSplitter function.
file: ./content/self-host/upgrading/outdated/462.mdx
meta: {
"title": "V4.6.2（升级脚本）",
"description": "FastGPT V4.6.2"
}
## 1。执行初始化 API
发起 1 个 HTTP 请求 (`{{rootkey}}` 替换成环境变量里的 `rootkey`，`{{host}}` 替换成自己域名)
1. [https://xxxxx/api/admin/initv462](https://xxxxx/api/admin/initv462)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv462' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化说明：
1. 初始化全文索引
## V4.6.2 功能介绍
1. 新增 - 全文索引（需配合 Rerank 模型，在看怎么放到社区版，模型接口比较特殊）
2. 新增 - 插件来源（预计4.7/4.8版本会正式使用）
3. 优化 - PDF读取
4. 优化 - docx文件读取，转成 markdown 并保留其图片内容
5. 修复和优化 TextSplitter 函数
file: ./content/self-host/upgrading/outdated/463.en.mdx
meta: {
"title": "V4.6.3 (Upgrade Script)",
"description": "FastGPT V4.6.3"
}
## 1. Run the Initialization API
Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain).
1. [https://xxxxx/api/admin/initv463](https://xxxxx/api/admin/initv463)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv463' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
What the initialization does:
1. Initializes certain fields in the Mongo dataset, collection, and data documents.
## V4.6.3 New Features
1. New (Commercial edition) - Web site sync.
2. New - Collection metadata tracking.
3. Improved - URL content fetching.
4. Improved - Streaming file reads to prevent memory overflow.
5. Improved - Vision models now automatically convert URLs to base64, enabling local debugging.
6. Improved - Image compression quality levels.
7. Fixed - Image compression failure errors that could cause file reading to hang.
file: ./content/self-host/upgrading/outdated/463.mdx
meta: {
"title": "V4.6.3（升级脚本）",
"description": "FastGPT V4.6.3"
}
## 1。执行初始化 API
发起 1 个 HTTP 请求 (`{{rootkey}}` 替换成环境变量里的 `rootkey`，`{{host}}` 替换成自己域名)
1. [https://xxxxx/api/admin/initv463](https://xxxxx/api/admin/initv463)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv463' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化说明：
1. 初始化Mongo 中 dataset，collection 和 data 的部分字段
## V4.6.3 功能介绍
1. 商业版新增 - web站点同步
2. 新增 - 集合元数据记录
3. 优化 - url 读取内容
4. 优化 - 流读取文件，防止内存溢出
5. 优化 - 4v模型自动将 url 转 base64，本地也可调试
6. 优化 - 图片压缩等级
7. 修复 - 图片压缩失败报错，防止文件读取过程卡死。
file: ./content/self-host/upgrading/outdated/464.en.mdx
meta: {
"title": "V4.6.4 (Upgrade Script)",
"description": "FastGPT V4.6.4"
}
## 1. Run the Initialization API
Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain).
1. [https://xxxxx/api/admin/initv464](https://xxxxx/api/admin/initv464)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv464' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
What the initialization does:
1. Initializes the createTime field in PG.
2. Initializes the feedback field for chats in Mongo.
## V4.6.4 New Features
1. Rewritten - Share link identity logic, now using localID to track user IDs.
2. New (Commercial edition) - Share link SSO support. With just 3 API endpoints via an authentication URL, you can fully integrate your existing user system. See [Share Link Authentication](../../../guide/build/publish/link.en.mdx#share-link-authentication) for details.
3. New - More embedding options for share links, with additional DIY customization.
4. Improved - History module. The old history module has been deprecated — simply enter the value directly in the relevant field.
5. Adjusted - Knowledge base search module topK logic now uses MaxToken calculation, accommodating text chunks of varying lengths.
6. Adjusted - Authentication order to prioritize API keys, preventing cookies from overriding API key authentication.
7. Link fetching now supports multiple selectors. See [Web Site Sync Usage](../../../guide/dataset/websync.en.mdx).
8. Fixed - Image upload authentication issue in share links.
9. Fixed - Mongo connection pool not being released.
10. Fixed - Dataset description (Intro) not updating.
11. Fixed - Markdown code block rendering issue.
12. Fixed - Root permission issue.
13. Optimized Dockerfile.
file: ./content/self-host/upgrading/outdated/464.mdx
meta: {
"title": "V4.6.4（升级脚本）",
"description": "FastGPT V4.6.4"
}
## 1。执行初始化 API
发起 1 个 HTTP 请求 ( `{{rootkey}}` 替换成环境变量里的 `rootkey`，`{{host}}` 替换成自己域名)
1. [https://xxxxx/api/admin/initv464](https://xxxxx/api/admin/initv464)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv464' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化说明：
1. 初始化 PG 的 createTime 字段
2. 初始化 Mongo 中 chat 的 feedback 字段
## V4.6.4 功能介绍
1. 重写 - 分享链接身份逻辑，采用 localID 记录用户的 ID。
2. 商业版新增 - 分享链接 SSO 方案，通过 `身份鉴权` 地址，仅需 `3个接口` 即可完全接入已有用户系统。具体参考[分享链接身份鉴权](../../../guide/build/publish/link.mdx#分享链接身份鉴权)
3. 新增 - 分享链接更多嵌入方式提示，更多 DIY 方式。
4. 优化 - 历史记录模块。弃用旧的历史记录模块，直接在对应地方填写数值即可。
5. 调整 - 知识库搜索模块 topk 逻辑，采用 MaxToken 计算，兼容不同长度的文本块
6. 调整鉴权顺序，提高 apikey 的优先级，避免 cookie 抢占 apikey 的鉴权。
7. 链接读取支持多选择器。参考 [Web 站点同步用法](../../../guide/dataset/websync.mdx)
8. 修复 - 分享链接图片上传鉴权问题
9. 修复 - Mongo 连接池未释放问题。
10. 修复 - Dataset Intro 无法更新
11. 修复 - md 代码块问题
12. 修复 - root 权限问题
13. 优化 docker file
file: ./content/self-host/upgrading/outdated/465.en.mdx
meta: {
"title": "V4.6.5 (Configuration Changes)",
"description": "FastGPT V4.6.5"
}
## Configuration Changes
Since OpenAI has begun deprecating function calls in favor of tool choice, FastGPT has updated its configuration and invocation methods accordingly. You'll need to make some changes to your configuration file:
The legacy `config.json` guide is no longer maintained. For current versions, see [Model Configuration](../../config/model/intro.en.mdx).
1. The main change is renaming the `functionCall` field to `toolChoice` in your model configuration. Models with this set to `true` will use OpenAI's tools mode by default; models without it or with it set to `false` will use prompt-based generation.
The question optimization model and content extraction model now share the same configuration.
2. Add `"ReRankModels": []` to your configuration.
## V4.6.5 New Features
1. New - [Question Optimization node](../../../guide/build/workflow/nodes/coreferenceResolution.en.mdx)
2. New - [Text Editor node](../../../guide/build/workflow/nodes/text_editor.en.mdx)
3. New - [Classifier node](../../../guide/build/workflow/nodes/tfswitch.en.mdx)
4. New - [Custom Feedback node](../../../guide/build/workflow/nodes/custom_feedback.en.mdx)
5. New - The Content Extraction node now supports model selection and field enumerations.
6. Improved - DOCX parsing with table support (tables are converted to Markdown).
7. Improved - Advanced orchestration connection line interactions.
8. Improved - Fixed CPU-intensive computation caused by html2md that was blocking the thread.
9. Fixed - Prompt extraction descriptions in advanced orchestration.
file: ./content/self-host/upgrading/outdated/465.mdx
meta: {
"title": "V4.6.5（配置变更）",
"description": "FastGPT V4.6.5"
}
## 配置文件变更
由于 openai 已开始弃用 function call，改为 toolChoice。FastGPT 同步的修改了对于的配置和调用方式，需要对配置文件做一些修改：
旧版 `config.json` 配置说明已不再维护，当前版本请参考[模型配置方案](../../config/model/intro.mdx)。
1. 主要是修改模型的 `functionCall` 字段，改成 `toolChoice` 即可。设置为 `true` 的模型，会默认走 openai 的 tools 模式；未设置或设置为 `false` 的，会走提示词生成模式。
问题优化模型与内容提取模型使用同一组配置。
2. 增加 `"ReRankModels": []`
## V4.6.5 功能介绍
1. 新增 - [问题优化模块](../../../guide/build/workflow/nodes/coreferenceResolution.mdx)
2. 新增 - [文本编辑模块](../../../guide/build/workflow/nodes/text_editor.mdx)
3. 新增 - [判断器模块](../../../guide/build/workflow/nodes/tfswitch.mdx)
4. 新增 - [自定义反馈模块](../../../guide/build/workflow/nodes/custom_feedback.mdx)
5. 新增 -【内容提取】模块支持选择模型，以及字段枚举
6. 优化 - docx 读取，兼容表格（表格转 markdown）
7. 优化 - 高级编排连接线交互
8. 优化 - 由于 html2md 导致的 cpu 密集计算，阻断线程问题
9. 修复 - 高级编排提示词提取描述
file: ./content/self-host/upgrading/outdated/466.en.mdx
meta: {
"title": "V4.6.6 (Configuration Changes, Environment Changes)",
"description": "FastGPT V4.6.6"
}
## Configuration Changes
To reduce code duplication, we've made some changes to the configuration file. The legacy `config.json` guide is no longer maintained. For current versions, see [Model Configuration](../../config/model/intro.en.mdx) and [Environment Variables](../../config/env.en.mdx).
## Commercial Edition Changes
1. Update the commercial edition image to version 4.6.6.
2. Move `SystemParams.pluginBaseUrl` from the old configuration file to an environment variable:
PRO\_URL=commercial edition image address (no longer needs to end with /api), for example:
PRO\_URL=[http://fastgpt-plugin.ns-hsss5d.svc.cluster.local:3000](http://fastgpt-plugin.ns-hsss5d.svc.cluster.local:3000)
3. The `FeConfig` section has been removed from the configuration file. You can now configure it directly through the commercial edition's web interface. All FastGPT parameters and models can be configured from the commercial edition dashboard — no need to modify `config.json` anymore.
## V4.6.6 Release Notes
1. Check out the [FastGPT 2024 RoadMap](https://github.com/labring/FastGPT?tab=readme-ov-file#-%E5%9C%A8%E7%BA%BF%E4%BD%BF%E7%94%A8).
2. New - HTTP node now supports a JSON editor for request headers.
3. New - [ReRank Model Deployment](../../custom-models/bge-rerank.en.mdx)
4. New - Search modes: separated vector semantic search, full-text search, and reranking, with RRF (Reciprocal Rank Fusion) for merging results.
5. Improved - Question classifier prompts with ID-guided classification. Tested with Chinese commercial API models (Baidu, Alibaba, Zhipu, iFlytek) — all work correctly in Prompt mode.
6. UI improvements — the interface will be gradually updated with a new design going forward.
7. Code optimization: Icons extracted and auto-generated.
8. Fixed - Link-based datasets not saving selectors, causing syncs to run without them.
file: ./content/self-host/upgrading/outdated/466.mdx
meta: {
"title": "V4.6.6（配置变更、环境变量变更）",
"description": "FastGPT V4.6.6"
}
## 配置文件变更
为了减少代码重复度，我们对配置文件做了一些修改。旧版 `config.json` 配置说明已不再维护，当前版本请参考[模型配置方案](../../config/model/intro.mdx)和[环境变量说明](../../config/env.mdx)。
## 商业版变更
1. 更新商业版镜像到 4.6.6 版本。
2. 将旧版配置文件中的 `SystemParams.pluginBaseUrl` 放置到环境变量中:
PRO\_URL=商业版镜像地址（此处不再需要以 /API 结尾），例如:\
PRO\_URL= [http://fastgpt-plugin.ns-hsss5d.svc.cluster.local:3000](http://fastgpt-plugin.ns-hsss5d.svc.cluster.local:3000)
3. 原本在配置文件中的 `FeConfig` 已被移除，可以直接打开新的商业版镜像外网地址进行配置。包括 FastGPT 的各个参数和模型都可以直接在商业版镜像中配置，无需再变更 `config.json` 文件。
## V4.6.6 更新说明
1. 查看 [FastGPT 2024 RoadMap](https://github.com/labring/FastGPT?tab=readme-ov-file#-%E5%9C%A8%E7%BA%BF%E4%BD%BF%E7%94%A8)
2. 新增 - Http 模块请求头支持 Json 编辑器。
3. 新增 - [ReRank 模型部署](../../custom-models/bge-rerank.mdx)
4. 新增 - 搜索方式：分离向量语义检索，全文检索和重排，通过 RRF 进行排序合并。
5. 优化 - 问题分类提示词，ID 引导。测试国产商用 API 模型（百度阿里智谱讯飞）使用 Prompt 模式均可分类。
6. UI 优化，未来将逐步替换新的 UI 设计。
7. 优化代码：Icon 抽离和自动化获取。
8. 修复 - 链接读取的数据集，未保存选择器，导致同步时不使用选择器。
file: ./content/self-host/upgrading/outdated/467.en.mdx
meta: {
"title": "V4.6.7 (Upgrade Script)",
"description": "FastGPT V4.6.7"
}
## 1. Run the Initialization API
Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain).
1. [https://xxxxx/api/admin/initv467](https://xxxxx/api/admin/initv467)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv467' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
What the initialization does:
1. Re-associates images with their datasets.
2. Sets null values in the PG table.
## V4.6.7 Release Notes
1. Redesigned knowledge base UI with a new import workflow.
2. Optimized knowledge base and chat data indexing.
3. Knowledge base OpenAPI — you can now [manage knowledge bases via API](../../../openapi/dataset.en.mdx).
4. New - Input field variable hints. After typing `{`, you'll see available variable suggestions. Based on community feedback on advanced orchestration, we plan to improve variable handling in the February release, adding support for node-scoped local variables and more global variables.
5. Improved - Switching teams now saves your selection, so you'll automatically log into that team on your next visit.
6. Fixed - chatId conflicts when using the API for conversations.
7. Fixed - Potential window\.onLoad conflicts when embedding via iframe.
file: ./content/self-host/upgrading/outdated/467.mdx
meta: {
"title": "V4.6.7（升级脚本）",
"description": "FastGPT V4.6.7"
}
## 1。执行初始化 API
发起 1 个 HTTP 请求 (`{{rootkey}}` 替换成环境变量里的 `rootkey`，`{{host}}` 替换成自己域名)
1. [https://xxxxx/api/admin/initv467](https://xxxxx/api/admin/initv467)
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv467' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化说明：
1. 将 images 重新关联到数据集
2. 设置 pg 表的 null 值。
## V4.6.7 更新说明
1. 修改了知识库UI及新的导入交互方式。
2. 优化知识库和对话的数据索引。
3. 知识库 openAPI，支持通过 [API 操作知识库](../../../openapi/dataset.mdx)。
4. 新增 - 输入框变量提示。输入 `{` 号后将会获得可用变量提示。根据社区针对高级编排的反馈，我们计划于 2 月份的版本中，优化变量内容，支持模块的局部变量以及更多全局变量写入。
5. 优化 - 切换团队后会保存记录，下次登录时优先登录该团队。
6. 修复 - API 对话时，chatId 冲突问题。
7. 修复 - Iframe 嵌入网页可能导致的 window\.onLoad 冲突。
file: ./content/self-host/upgrading/outdated/468.en.mdx
meta: {
"title": "V4.6.8 (Upgrade Script)",
"description": "FastGPT V4.6.8 Release Notes"
}
## Docker Deployment - Manually Update MongoDB
1. Modify the mongo section in docker-compose.yml by adding the `command` and `entrypoint` fields:
```yml
mongo:
image: mongo:5.0.18
# image: registry.cn-hangzhou.aliyuncs.com/fastgpt/mongo:5.0.18 # Alibaba Cloud
container_name: mongo
ports:
- 27017:27017
networks:
- fastgpt
command: mongod --keyFile /data/mongodb.key --replSet rs0
environment:
# Make sure the password matches your previous configuration
- MONGO_INITDB_ROOT_USERNAME=username
- MONGO_INITDB_ROOT_PASSWORD=password
volumes:
- ./mongo/data:/data/db
entrypoint:
- bash
- -c
- |
openssl rand -base64 128 > /data/mongodb.key
chmod 400 /data/mongodb.key
chown 999:999 /data/mongodb.key
echo 'const isInited = rs.status().ok === 1
if(!isInited){
rs.initiate({
_id: "rs0",
members: [
{ _id: 0, host: "mongo:27017" }
]
})
}' > /data/initReplicaSet.js
# Start MongoDB service
exec docker-entrypoint.sh "$@" &
# Wait for MongoDB to start
until mongo -u myusername -p mypassword --authenticationDatabase admin --eval "print('waited for connection')" > /dev/null 2>&1; do
echo "Waiting for MongoDB to start..."
sleep 2
done
# Run the replica set initialization script
mongo -u myusername -p mypassword --authenticationDatabase admin /data/initReplicaSet.js
# Wait for the MongoDB process started by docker-entrypoint.sh
wait $!
```
2. Restart MongoDB
```bash
# Restart Mongo
docker-compose down
docker-compose up -d
```
## Sealos Deployment - No MongoDB Update Required
## Update Configuration File
Removed duplicate model configurations. All LLM models are now consolidated into a single property. The legacy `config.json` guide is no longer maintained. For current versions, see [Model Configuration](../../config/model/intro.en.mdx).
## Commercial Edition Initialization
Commercial edition users need to run an initialization to format team information.
Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your commercial edition domain):
```bash
curl --location --request POST 'https://{{host}}/api/init/v468' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This will initialize the billing system. For internal use, you can increase the free storage quota.
## V4.6.8 Release Notes
1. New - Knowledge Base search merge module.
2. New - Redesigned HTTP module with more flexible parameter input. Supports automatic input/output data type conversion (e.g., JSON output is automatically converted to string type for use by other modules). Additional examples are available in the documentation.
3. Improved - Query completion. Query completion is now built into the Knowledge Base Search module, enabling both "reference resolution" and "query expansion" in a single pass. See [Knowledge Base Search Introduction](../../../guide/build/workflow/nodes/dataset_search.en.mdx) for details.
4. Improved - LLM model configuration no longer distinguishes between chat, classification, and extraction models. Default parameters per model are now supported via `defaultConfig` to avoid parameter conflicts between different models.
5. Improved - Streaming response, inspired by `ChatNextWeb`'s streaming implementation for smoother output. This may also fix previously reported issues with garbled text and interruptions that resolved after refreshing.
6. Fixed - Voice input file upload failure.
7. Fixed - Chat box regeneration not working.
file: ./content/self-host/upgrading/outdated/468.mdx
meta: {
"title": "V4.6.8（升级脚本）",
"description": "FastGPT V4.6.8更新说明"
}
## docker 部署 - 手动更新 Mongo
1. 修改 docker-compose.yml 的 mongo 部分，补上 `command` 和 `entrypoint`
```yml
mongo:
image: mongo:5.0.18
# image: registry.cn-hangzhou.aliyuncs.com/fastgpt/mongo:5.0.18 # 阿里云
container_name: mongo
ports:
- 27017:27017
networks:
- fastgpt
command: mongod --keyFile /data/mongodb.key --replSet rs0
environment:
# 这里密码注意要和以前的一致
- MONGO_INITDB_ROOT_USERNAME=username
- MONGO_INITDB_ROOT_PASSWORD=password
volumes:
- ./mongo/data:/data/db
entrypoint:
- bash
- -c
- |
openssl rand -base64 128 > /data/mongodb.key
chmod 400 /data/mongodb.key
chown 999:999 /data/mongodb.key
echo 'const isInited = rs.status().ok === 1
if(!isInited){
rs.initiate({
_id: "rs0",
members: [
{ _id: 0, host: "mongo:27017" }
]
})
}' > /data/initReplicaSet.js
# 启动MongoDB服务
exec docker-entrypoint.sh "$@" &
# 等待MongoDB服务启动
until mongo -u myusername -p mypassword --authenticationDatabase admin --eval "print('waited for connection')" > /dev/null 2>&1; do
echo "Waiting for MongoDB to start..."
sleep 2
done
# 执行初始化副本集的脚本
mongo -u myusername -p mypassword --authenticationDatabase admin /data/initReplicaSet.js
# 等待docker-entrypoint.sh脚本执行的MongoDB服务进程
wait $!
```
2. 重启 MongoDB
```bash
# 重启 Mongo
docker-compose down
docker-compose up -d
```
## Sealos 部署 - 无需更新 Mongo
## 修改配置文件
去除了重复的模型配置，LLM 模型都合并到一个属性中。旧版 `config.json` 配置说明已不再维护，当前版本请参考[模型配置方案](../../config/model/intro.mdx)。
## 商业版初始化
商业版用户需要执行一个初始化，格式化团队信息。
发起 1 个 HTTP 请求 ( `{{rootkey}}` 替换成环境变量里的 `rootkey`，`{{host}}` 替换成商业版域名)
```bash
curl --location --request POST 'https://{{host}}/api/init/v468' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会初始化计费系统，内部使用可把免费的存储拉大。
## V4.6.8 更新说明
1. 新增 - 知识库搜索合并模块。
2. 新增 - 新的 Http 模块，支持更加灵活的参数传入。同时支持了输入输出自动数据类型转化，例如：接口输出的 JSON 类型会自动转成字符串类型，直接给其他模块使用。此外，还补充了一些例子，可在文档中查看。
3. 优化 - 内容补全。将内容补全内置到【知识库搜索】中，并实现了一次内容补全，即可完成“指代消除”和“问题扩展”。FastGPT 知识库搜索详细流程可查看：[知识库搜索介绍](../../../guide/build/workflow/nodes/dataset_search.mdx)
4. 优化 - LLM 模型配置，不再区分对话、分类、提取模型。同时支持模型的默认参数，避免不同模型参数冲突，可通过 `defaultConfig` 传入默认的配置。
5. 优化 - 流响应，参考了 `ChatNextWeb` 的流，更加丝滑。此外，之前提到的乱码、中断，刷新后又正常了，可能会修复。
6. 修复 - 语音输入文件无法上传。
7. 修复 - 对话框重新生成无法使用。
file: ./content/self-host/upgrading/outdated/469.en.mdx
meta: {
"title": "V4.6.9 (Environment Changes, Upgrade Script)",
"description": "FastGPT V4.6.9 Release Notes"
}
## Update Commercial Edition Environment Variables
Add the OneAPI address and token:
```
OPENAI_BASE_URL=http://oneapi:3000/v1
CHAT_API_KEY=sk-fastgpt
```
## Initialization Script
From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv469' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
1. Resets the usage tracking table.
2. Runs stale data cleanup (removes invalid files, images, Knowledge Base collections, and vectors).
## External API Updates
1. Due to billing system changes, the [share link chat reporting endpoint](../../../guide/build/publish/link.en.mdx#5-implement-the-chat-result-reporting-endpoint-optional) requires some adjustments. The `price` field has been replaced by `totalPoints`. The `inputToken` and `outputToken` fields are no longer provided — only a `token` field (total token count) is returned.
## V4.6.9 Release Notes
1. Commercial Edition - Knowledge Base now supports an "Enhanced Processing" training mode that generates additional index types.
2. New - Improved variable hints for the HTTP module.
3. New - HTTP module supports OpenAI single-endpoint import.
4. New - Global variables now support external variables, which can be passed via share link query parameters or the API `variables` parameter.
5. New - Content extraction module now supports default values.
6. Improved - Query completion now includes English language support. It can also be configured as a standalone module for reuse.
7. Improved - Rewrote the usage tracking system.
8. Improved - Token-based history filtering now keeps an even number of messages to prevent errors with certain models.
9. Improved - Share link SEO now displays the app name and avatar directly.
10. Fixed - Annotation feature.
11. Fixed - QA generation thread count error.
12. Fixed - Question classification connection type error.
file: ./content/self-host/upgrading/outdated/469.mdx
meta: {
"title": "V4.6.9（环境变量变更、升级脚本）",
"description": "FastGPT V4.6.9更新说明"
}
## 修改商业版环境变量
增加 oneapi 地址和令牌。
```
OPENAI_BASE_URL=http://oneapi:3000/v1
CHAT_API_KEY=sk-fastgpt
```
## 初始化脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成自己域名
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv469' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
1. 重置计量表。
2. 执行脏数据清理（清理无效的文件、清理无效的图片、清理无效的知识库集合、清理无效的向量）
## 外部接口更新
1. 由于计费系统变更，[分享链接对话上报接口](../../../guide/build/publish/link.mdx#5-编写对话结果上报接口可选)需要做一些调整，price 字段被 totalPoints 字段取代。inputToken 和 outputToken 不再提供，只提供 `token` 字段（总 token 数量）。
## V4.6.9 更新说明
1. 商业版新增 - 知识库新增“增强处理”训练模式，可生成更多类型索引。
2. 新增 - 完善了 HTTP 模块的变量提示。
3. 新增 - HTTP 模块支持 OpenAI 单接口导入。
4. 新增 - 全局变量支持增加外部变量。可通过分享链接的 Query 或 API 的 variables 参数传入。
5. 新增 - 内容提取模块增加默认值。
6. 优化 - 问题补全。增加英文类型。同时可以设置为单独模块，方便复用。
7. 优化 - 重写了计量模式
8. 优化 - Token 过滤历史记录，保持偶数条，防止部分模型报错。
9. 优化 - 分享链接 SEO，可直接展示应用名和头像。
10. 修复 - 标注功能。
11. 修复 - qa 生成线程计数错误。
12. 修复 - 问题分类连线类型错误
file: ./content/self-host/upgrading/outdated/47.en.mdx
meta: {
"title": "V4.7 (Upgrade Script)",
"description": "FastGPT V4.7 Release Notes"
}
## 1. Update Configuration File
Added Boolean values to control which models are available for different feature modules, and added model logos. The legacy `config.json` guide is no longer maintained. For current versions, see [Model Configuration](../../config/model/intro.en.mdx).
## 2. Initialization Script
After upgrading the image, send 1 HTTP request from any terminal. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv47' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
Script functions:
1. Initializes the parentId for plugins.
## 3. Upgrade ReRank Model
V4.7 changed the ReRank model format to be compatible with Cohere's format, allowing direct use of Cohere's API. If you're using a local ReRank model, update the image to: `registry.cn-hangzhou.aliyuncs.com/fastgpt/bge-rerank-base:v0.1`.
Cohere's reranking model doesn't perform as well with Chinese text compared to BGE. To integrate Cohere:
1. Apply for a Cohere API key: [https://dashboard.cohere.com/api-keys](https://dashboard.cohere.com/api-keys)
2. Update the FastGPT configuration file:
```json
{
"reRankModels": [
{
"model": "rerank-multilingual-v2.0", // The model name must match a Cohere model
"name": "Rerank", // Any display name
"requestUrl": "https://api.cohere.ai/v1/rerank",
"requestAuth": "Your Cohere API key"
}
]
}
```
## V4.7 Release Notes
1. New - Tool calling module that allows LLM models to dynamically select other modules or plugins based on user intent.
2. New - Classification and content extraction now support functionCall mode. Models that support functionCall but not toolCall can now be used. Set `functionCall` to `true` and `toolChoice` to `false` in the LLM model configuration. If `toolChoice` is true, tool mode will be used instead.
3. New - HTTP plugin for quickly generating plugins via OpenAPI.
4. New - ReRank model now compatible with [Cohere's format](https://docs.cohere.com/reference/rerank-1), enabling direct use of Cohere's rerank models.
5. New - Helm chart installation support.
6. Improved - Advanced workflow editor performance.
7. Improved - Extracted Flow controller to packages.
8. Improved - AI model selection.
9. Improved - Manual Knowledge Base input dialog.
10. Improved - Variable input dialog.
11. Improved - Docker deployment now auto-initializes replica sets.
12. Improved - Browser file reading now auto-detects encoding to reduce garbled text.
13. Fixed - Community edition rerank model selection not working.
14. Fixed - HTTP request body sending `undefined` when not in use (caused some GET requests to fail).
15. New - HTTP URL now supports variables.
16. Fixed - V4.6.9 extraction prompts prone to hallucination.
17. Fixed - PG HNSW index not actually taking effect. After this update, search speed is significantly improved (though there may be some precision loss — refer to the PgVector documentation for index tuning). Details: [https://github.com/pgvector/pgvector?tab=readme-ov-file#troubleshooting](https://github.com/pgvector/pgvector?tab=readme-ov-file#troubleshooting)
18. Fixed - Safari browser voice input issue.
19. Fixed - Custom split rules now accept regex special characters (previously caused frontend crashes).
file: ./content/self-host/upgrading/outdated/47.mdx
meta: {
"title": "V4.7（升级脚本）",
"description": "FastGPT V4.7更新说明"
}
## 1. 修改配置文件
增加一些 Boolean 值，用于决定不同功能块可以使用哪些模型，同时增加了模型的 logo。旧版 `config.json` 配置说明已不再维护，当前版本请参考[模型配置方案](../../config/model/intro.mdx)。
## 2. 初始化脚本
升级完镜像后。从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成自己域名
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv47' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
脚本功能：
1. 初始化插件的 parentId
## 3. 升级 ReRank 模型
4.7 对 ReRank 模型进行了格式变动，兼容 cohere 的格式，可以直接使用 cohere 提供的 API。如果是本地的 ReRank 模型，需要修改镜像为：`registry.cn-hangzhou.aliyuncs.com/fastgpt/bge-rerank-base:v0.1`。
cohere 的重排模型对中文不是很好，感觉不如 bge 的好用，接入教程如下：
1. 申请 Cohere 官方 Key: [https://dashboard.cohere.com/api-keys](https://dashboard.cohere.com/api-keys)
2. 修改 FastGPT 配置文件
```json
{
"reRankModels": [
{
"model": "rerank-multilingual-v2.0", // 这里的 model 需要对应 cohere 的模型名
"name": "检索重排", // 随意
"requestUrl": "https://api.cohere.ai/v1/rerank",
"requestAuth": "Coherer上申请的key"
}
]
}
```
## V4.7 更新说明
1. 新增 - 工具调用模块，可以让 LLM 模型根据用户意图，动态的选择其他模型或插件执行。
2. 新增 - 分类和内容提取支持 functionCall 模式。部分模型支持 functionCall 不支持 ToolCall，也可以使用了。需要把 LLM 模型配置文件里的 `functionCall` 设置为 `true`，`toolChoice` 设置为 `false`。如果 `toolChoice` 为 true，会走 tool 模式。
3. 新增 - HTTP 插件，可实现 OpenAPI 快速生成插件。
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](https://github.com/pgvector/pgvector?tab=readme-ov-file#troubleshooting)
18. 修复 Safari 浏览器语音输入问题。
19. 修复 - 自定义分割规则可输入正则特殊字符（之前输入的话，会导致前端崩溃）
file: ./content/self-host/upgrading/outdated/471.en.mdx
meta: {
"title": "V4.7.1 (Environment Changes, Upgrade Script)",
"description": "FastGPT V4.7.1 Release Notes"
}
## Initialization Script
From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your FastGPT domain.
```bash
curl --location --request POST 'https://{{host}}/api/admin/clearInvalidData' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This request runs stale data cleanup (removes invalid files, images, Knowledge Base collections, and vectors).
## Update Configuration File
Added Laf environment configuration. The legacy `config.json` guide is no longer maintained. For current versions, see [Environment Variables](../../config/env.en.mdx).
## V4.7.1 Release Notes
1. New - Full voice input configuration. Supports toggling voice input on/off (including on share pages), auto-send after voice input, and auto voice playback after input (streaming).
2. New - PPTX and XLSX file reading. Note that all file reading now happens server-side, which consumes more server resources and prevents content preview during upload.
3. New - Laf cloud function integration. You can use cloud functions from your Laf account as HTTP modules.
4. New - Scheduled cleanup timer for stale data. Uses incremental cleanup (cleans data from the last N hours), so keep the service running continuously. For a full cleanup after extended downtime, use the `clearInvalidData` endpoint.
5. Commercial Edition - Admin panel system notification configuration.
6. Improved - Knowledge Base export now supports IP-based mode.
7. Changed - CSV import template no longer validates headers; automatically reads the first two columns.
8. Fixed - Tool calling module connection data type validation error.
9. Fixed - Custom index input data destructuring failure.
10. Fixed - ReRank model data format.
11. Fixed - Query completion history bug.
12. Fixed - Share page slow loading in certain edge cases (caused by database connections not being triggered during SSR).
file: ./content/self-host/upgrading/outdated/471.mdx
meta: {
"title": "V4.7.1（环境变量变更、升级脚本）",
"description": "FastGPT V4.7.1 更新说明"
}
## 初始化脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成 FastGPT 的域名。
```bash
curl --location --request POST 'https://{{host}}/api/admin/clearInvalidData' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
该请求会执行脏数据清理（清理无效的文件、清理无效的图片、清理无效的知识库集合、清理无效的向量）
## 修改配置文件
增加了 Laf 环境配置。旧版 `config.json` 配置说明已不再维护，当前版本请参考[环境变量说明](../../config/env.mdx)。
## V4.7.1 更新说明
1. 新增 - 语音输入完整配置。支持选择是否打开语音输入（包括分享页面），支持语音输入后自动发送，支持语音输入后自动语音播放（流式）。
2. 新增 - pptx 和 xlsx 文件读取。但所有文件读取都放服务端，会消耗更多的服务器资源，以及无法在上传时预览更多内容。
3. 新增 - 集成 Laf 云函数，可以读取 Laf 账号中的云函数作为 HTTP 模块。
4. 新增 - 定时器，清理垃圾数据。（采用小范围清理，会清理最近 n 个小时的，所以请保证服务持续运行，长时间不允许，可以继续执行 clearInvalidData 的接口进行全量清理。）
5. 商业版新增 - 后台配置系统通知。
6. 优化 - 支持 ip 模式导出知识库。
7. 修改 - csv 导入模板，取消 header 校验，自动获取前两列。
8. 修复 - 工具调用模块连线数据类型校验错误。
9. 修复 - 自定义索引输入时，解构数据失败。
10. 修复 - rerank 模型数据格式。
11. 修复 - 问题补全历史记录 BUG
12. 修复 - 分享页面特殊情况下加载缓慢问题（由于 ssr 时候数据库不会触发连接）
file: ./content/self-host/upgrading/outdated/48.en.mdx
meta: {
"title": "V4.8",
"description": "FastGPT V4.8 Release Notes"
}
import { Alert } from '@/components/docs/Alert';
## New Workflow
FastGPT Workflow V2 is here, with a cleaner and more streamlined workflow experience.
**Due to significant workflow changes, many parts need to be manually rebuilt. Please rebuild plugins first, then apps.**
We recommend updating your workflows as soon as possible to avoid future compatibility issues as the platform continues to evolve.
A `version` field has been added to apps and plugins to distinguish between old and new workflows. After upgrading to V4.8, all saved and newly created workflows use the new version. Old workflows will show a reset prompt dialog. Workflows called via API or share links will continue to work until you save them again.
## Commercial Edition Configuration Update
Commercial edition users who have configured email verification codes need to update the admin panel: go to Admin Panel -> Project Settings -> Login Settings -> Email Login Settings -> update the **Email SMTP Server Address**. Previously only aliases were supported; now you can configure custom addresses. Here are some alias-to-address mappings:
qq: smtp.qq.com
gmail: smtp.gmail.com
## V4.8 Release Notes
1. Refactored - Workflow engine.
2. New - If/ElseIf/Else conditional node. @newfish-cmyk (If/Else nodes from the preview version need to be deleted and recreated)
3. New - Variable update node for modifying workflow output variables or global variables at runtime. @newfish-cmyk
4. New - Workflow auto-save and version management.
5. New - Workflow Debug mode for testing individual nodes or stepping through the workflow.
6. New - Scheduled app execution for easy cron-like tasks.
7. New - Improved plugin custom input with rendered input components.
8. New - Share link pre-chat hook. [https://github.com/labring/FastGPT/pull/1252](https://github.com/labring/FastGPT/pull/1252) @gaord
9. Improved - Workflow connections now support 4-directional linking for easier loop construction.
10. Improved - Workflow context passing performance.
11. Improved - Ctrl+Enter and Alt+Enter line break cursor positioning.
12. Improved - Variable configuration storage in chat to prevent edits from affecting existing conversations.
13. Improved - Simple mode now auto-updates the debug panel after config changes without saving.
14. Improved - Worker process management; token calculation is now delegated to worker processes.
15. Improved - Tool calling now supports specifying field data types (string, boolean, number). [https://github.com/labring/FastGPT/issues/1236](https://github.com/labring/FastGPT/issues/1236)
16. Improved - Completions API size limit. [https://github.com/labring/FastGPT/issues/1241](https://github.com/labring/FastGPT/issues/1241)
17. Improved - Node API middleware and API-side code. @c121914yu
18. Improved - Chat history is now trimmed to an even number of messages to support models that require paired messages. Max length increased to 50 rounds. [https://github.com/labring/FastGPT/issues/1384](https://github.com/labring/FastGPT/issues/1384)
19. Improved - HTTP node now terminates the process on error. [https://github.com/labring/FastGPT/issues/1290](https://github.com/labring/FastGPT/issues/1290)
20. Fixed - Tool calling name cannot start with a number (random IDs occasionally generated numeric prefixes). @c121914yu
21. Fixed - Share link global variable query params being cached. @c121914yu
22. Fixed - Tool calling field compatibility. [https://github.com/labring/FastGPT/issues/1253](https://github.com/labring/FastGPT/issues/1253)
23. Fixed - HTTP module URL cursor issue. [https://github.com/labring/FastGPT/issues/1334](https://github.com/labring/FastGPT/issues/1334) @maquannene
file: ./content/self-host/upgrading/outdated/48.mdx
meta: {
"title": "V4.8",
"description": "FastGPT V4.8 更新说明"
}
import { Alert } from '@/components/docs/Alert';
## 新工作流
FastGPT workflow V2上线，支持更加简洁的工作流模式。
**由于工作流差异较大，不少地方需要手动重新构建。请依次重建插件和应用**
简易尽快更新工作流，避免未来持续迭代后导致无法兼容。
给应用和插件增加了 version 的字段，用于标识是旧工作流还是新工作流。当你更新 4.8 后，保存和新建的工作流均为新版，旧版工作流会有一个重置的弹窗提示。并且，如果是通过 API 和 分享链接 调用的工作流，仍可以正常使用，直到你下次保存它们。
## 商业版配置更新
商业版用户如果配置了邮件验证码，需要在管理端 -> 项目配置 -> 登录配置 -> 邮箱登录配置 -> 修改 **邮箱服务SMTP地址**，之前只能配置别名，现在可以配置自定义的地址。下面是一组别名和实际地址关系：
qq: smtp.qq.com
gmail: smtp.gmail.com
## V4.8 更新说明
1. 重构 - 工作流
2. 新增 - 判断器。支持 if elseIf else 判断。 @newfish-cmyk （preview版本的if else节点需要删除重建）
3. 新增 - 变量更新节点。支持更新运行中工作流输出变量，或更新全局变量。@newfish-cmyk
4. 新增 - 工作流自动保存和版本管理。
5. 新增 - 工作流 Debug 模式，可以调试单个节点或者逐步调试工作流。
6. 新增 - 定时执行应用。可轻松实现定时任务。
7. 新增 - 插件自定义输入优化，可以渲染输入组件。
8. 新增 - 分享链接发送对话前 hook [https://github.com/labring/FastGPT/pull/1252](https://github.com/labring/FastGPT/pull/1252) @gaord
9. 优化 - 工作流连线，可以四向连接，方便构建循环工作流。
10. 优化 - 工作流上下文传递，性能🚀。
11. 优化 - ctrl和alt+enter换行，换行符位置不正确。
12. 优化 - chat中存储变量配置。避免修改变量后，影响旧的对话。
13. 优化 - 简易模式，更新配置后自动更新调试框内容，无需保存。
14. 优化 - worker进程管理，并将计算 Token 任务分配给 worker 进程。
15. 优化 - 工具调用支持指定字段数据类型（string, boolean, number） [https://github.com/labring/FastGPT/issues/1236](https://github.com/labring/FastGPT/issues/1236)
16. 优化 - completions接口size限制 [https://github.com/labring/FastGPT/issues/1241](https://github.com/labring/FastGPT/issues/1241)
17. 优化 - Node api 中间件。优化 api 端代码。@c121914yu
18. 优化 - 对话记录保持为偶数进行截取，避免部分模型不支持奇数的历史记录，最大长度增加到50轮。 [https://github.com/labring/FastGPT/issues/1384](https://github.com/labring/FastGPT/issues/1384)
19. 优化 - HTTP节点错误后终止进程 [https://github.com/labring/FastGPT/issues/1290](https://github.com/labring/FastGPT/issues/1290)
20. 修复 - 工具调用时候，name不能是数字开头（随机数有概率数字开头）@c121914yu
21. 修复 - 分享链接， query 全局变量会被缓存。 @c121914yu
22. 修复 - 工具调用字段兼容。 [https://github.com/labring/FastGPT/issues/1253](https://github.com/labring/FastGPT/issues/1253)
23. 修复 - HTTP 模块url光标问题 [https://github.com/labring/FastGPT/issues/1334](https://github.com/labring/FastGPT/issues/1334) @maquannene
file: ./content/self-host/upgrading/outdated/481.en.mdx
meta: {
"title": "V4.8.1 (Upgrade Script)",
"description": "FastGPT V4.8.1 Release Notes"
}
## Initialization Script
From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your FastGPT domain.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv481' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
Due to previously inconsistent collection names, this initialization will reset table names. Before running, make sure the `dataset.trainings` table has no data. It's best to pause all active operations before initializing to avoid data conflicts.
## Run Stale Data Cleanup
From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your FastGPT domain.
```bash
curl --location --request POST 'https://{{host}}/api/admin/clearInvalidData' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
After initialization, you can run this command. The previous scheduled cleanup timer had some issues and missed certain data. This allows you to trigger a full cleanup manually.
## V4.8.1 Release Notes
If you're using the Chat API, note that a new `event: updateVariables` event has been added for updating variables.
[View the full release notes](https://github.com/labring/FastGPT/releases/tag/v4.8.1)
file: ./content/self-host/upgrading/outdated/481.mdx
meta: {
"title": "V4.8.1（升级脚本）",
"description": "FastGPT V4.8.1 更新说明"
}
## 初始化脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成FastGPT的域名。
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv481' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
由于之前集合名不规范，该初始化会重置表名。请在初始化前，确保 dataset.trainings 表没有数据。
最好更新该版本时，暂停所有进行中业务，再进行初始化，避免数据冲突。
## 执行脏数据清理
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成FastGPT的域名。
```bash
curl --location --request POST 'https://{{host}}/api/admin/clearInvalidData' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
初始化完后，可以执行这个命令。之前定时清理的定时器有些问题，部分数据没被清理，可以手动执行清理。
## V4.8.1 更新说明
使用 Chat api 接口需要注意，增加了 event: updateVariables 事件，用于更新变量。
[点击查看升级说明](https://github.com/labring/FastGPT/releases/tag/v4.8.1)
file: ./content/self-host/upgrading/outdated/4810.en.mdx
meta: {
"title": "V4.8.10 (Environment Changes, Upgrade Script)",
"description": "FastGPT V4.8.10 Release Notes"
}
## Upgrade Guide
### 1. Back up your database
### 2. Commercial Edition — Update environment variables
1. Add the sandbox environment variable to the `fastgpt-pro` image: `SANDBOX_URL=http://xxxxx:3000`
2. Add the following environment variables to both the `fastgpt-pro` and `fastgpt` images for better system log storage:
```
LOG_LEVEL=debug
STORE_LOG_LEVEL=warn
```
### 3. Update image tags
* Update the FastGPT image tag to v4.8.10
* Update the FastGPT commercial edition image tag to v4.8.10
* Sandbox image update is optional
## 4. Run initialization
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4810' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
1. Initializes publish record version markers
2. Initializes invoice records
***
## V4.8.10 Release Notes
For full details, see: [4.8.10 release](https://github.com/labring/FastGPT/releases/tag/v4.8.10)
1. New - Template marketplace.
2. New - Workflow node drag-and-drop auto-alignment and snapping.
3. New - User selection node (not yet supported in Debug mode).
4. New - Added `uid` global variable to workflows.
5. New - Workflow undo and redo.
6. New - Workflow edit history for the current session, replacing auto-save.
7. New - Workflow versions support renaming.
8. New - The "App Call" node in workflows is deprecated and migrated to a standalone node that works the same way as plugins, with support for passing global variables and user-uploaded files.
9. New - Plugins now support usage instructions configuration.
10. New - Plugin custom inputs support radio buttons.
11. New - HTTP node supports `text/plain` mode.
12. New - HTTP node supports timeout configuration, additional Body types, and a new variable selection mode for params and headers.
13. New - Workflow export/import now supports JSON files directly for easier sharing.
14. New - Verification code security check.
15. Commercial - Lark bot integration.
16. Commercial - WeChat Official Account integration.
17. Commercial - Self-service invoice requests.
18. Commercial - SSO customization.
19. Improved - Workflow loop validation to prevent skip-loop idle spinning. Also supports fully concurrent branch execution.
20. Improved - Workflow nested execution to prevent potential parameter pollution.
21. Improved - Added data type constraints to some global variables.
22. Improved - Node selection to prevent path loading errors when switching tabs.
23. Improved - Updated React Markdown component with Base64 image support.
24. Improved - Chat dialog performance.
25. Improved - Radio buttons auto-scroll to the selected position when opened.
26. Improved - Disabling a Knowledge Base collection directory now recursively disables all children.
27. Improved - SSE response code.
28. Improved - Improved copy functionality when SSL certificate is not available.
29. Improved - Knowledge Base list UI.
30. Improved - Knowledge Base detail page UI.
31. Improved - Support running without network configuration.
32. Improved - Updated .env.template MongoDB documentation for better clarity.
33. Improved - New payment mode.
34. Improved - Default user avatars.
35. Fixed - Prompt mode tool calls including `0:` prefix markers in non-stream mode.
36. Fixed - Chat log authentication: users who are only app administrators could not view chat log details.
37. Fixed - Unable to export Knowledge Base when using Milvus deployment.
38. Fixed - Creating an app copy failed to copy system configuration.
39. Fixed - Image recognition mode regex for auto-parsing image URLs was not strict enough.
40. Fixed - Content extraction data types not matching output data types.
41. Fixed - Workflow run time statistics were incorrect.
42. Fixed - Tool calls could produce `undefined` in stream mode.
43. Fixed - Reranker typo.
44. Fixed - Home host typo.
45. Fixed - i18n display.
46. Fixed - Global variable keys could be defined with duplicates.
47. Fixed - Global variables not persisting in Debug mode.
48. Fixed - Global variables not persisting via API.
49. Fixed - OpenAPI `detail=false` mode should not return tool call results, only text (resolves CoW compatibility issue).
50. Fixed - Knowledge Base tags loading repeatedly.
51. Fixed - Custom separators not taking effect when re-fetching web links.
52. Fixed - Plugin runtime passing extra global variables, potentially polluting plugin-internal variables.
53. Docs - QA docs.
54. Docs - Updated feishu.md.
55. Docs - Updated baseURL.
file: ./content/self-host/upgrading/outdated/4810.mdx
meta: {
"title": "V4.8.10（环境变量变更、升级脚本）",
"description": "FastGPT V4.8.10 更新说明"
}
## 更新指南
### 1. 做好数据备份
### 2. 商业版 —— 修改环境变量
1. 需要给`fastgpt-pro`镜像，增加沙盒的环境变量：`SANDBOX_URL=http://xxxxx:3000`
2. 给`fastgpt-pro`镜像和`fastgpt`镜像增加环境变量，以便更好的存储系统日志：
```
LOG_LEVEL=debug
STORE_LOG_LEVEL=warn
```
### 3. 修改镜像tag
* 更新 FastGPT 镜像 tag: v4.8.10
* 更新 FastGPT 商业版镜像 tag: v4.8.10
* Sandbox 镜像，可以不更新
## 4. 执行初始化
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**。
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4810' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
1. 初始化发布记录版本标记
2. 初始化开票记录
***
## V4.8.10 更新说明
完整内容请见：[4.8.10 release](https://github.com/labring/FastGPT/releases/tag/v4.8.10)
1. 新增 - 模板市场。
2. 新增 - 工作流节点拖动自动对齐吸附。
3. 新增 - 用户选择节点（Debug 模式暂未支持）。
4. 新增 - 工作流增加 uid 全局变量。
5. 新增 - 工作流撤销和重做。
6. 新增 - 工作流本次编辑记录，取代自动保存。
7. 新增 - 工作流版本支持重命名。
8. 新增 - 工作流的“应用调用”节点弃用，迁移成单独节点，与插件使用方式相同，同时可以传递全局变量和用户上传的文件。
9. 新增 - 插件增加使用说明配置。
10. 新增 - 插件自定义输入支持单选框。
11. 新增 - HTTP 节点支持 text/plain 模式。
12. 新增 - HTTP模块支持超时配置、支持更多的 Body 类型，params 和 headers 支持新的变量选择模式。
13. 新增 - 工作流导出导入，支持直接导出和导入 JSON 文件，便于交流。
14. 新增 - 发送验证码安全校验。
15. 商业版新增 - 飞书机器人接入。
16. 商业版新增 - 公众号接入接入。
17. 商业版新增 - 自助开票申请。
18. 商业版新增 - SSO 定制。
19. 优化 - 工作流循环校验，避免 skip 循环空转。同时支持分支完全并发执行。
20. 优化 - 工作流嵌套执行，参数可能存在的污染问题。
21. 优化 - 部分全局变量，增加数据类型约束。
22. 优化 - 节点选择，避免切换 tab 时候，path 加载报错。
23. 优化 - 最新 React Markdown 组件，支持 Base64 图片。
24. 优化 - 对话框性能问题。
25. 优化 - 单选框打开后自动滚动到选中的位置。
26. 优化 - 知识库集合禁用，目录禁用会递归修改其下所有 children 的禁用状态。
27. 优化 - SSE 响应代码优化。
28. 优化 - 无 SSL 证书情况下，优化复制。
29. 优化 - 知识库列表 UI。
30. 优化 - 知识库详情页 UI。
31. 优化 - 支持无网络配置情况下运行。
32. 优化 - 调整.env.template关于mongodb的说明，使得更易于理解。
33. 优化 - 新的支付模式。
34. 优化 - 用户默认头像。
35. 修复 - Prompt 模式调用工具，stream=false 模式下，会携带 0: 开头标记。
36. 修复 - 对话日志鉴权问题：仅为 APP 管理员的用户，无法查看对话日志详情。
37. 修复 - 选择 Milvus 部署时，无法导出知识库。
38. 修复 - 创建 APP 副本，无法复制系统配置。
39. 修复 - 图片识别模式下，自动解析图片链接正则不够严谨问题。
40. 修复 - 内容提取的数据类型与输出数据类型未一致。
41. 修复 - 工作流运行时间统计错误。
42. 修复 - stream 模式下，工具调用有可能出现 undefined。
43. 修复 - reranker typo。
44. 修复 - home host typo。
45. 修复 - i18n display。
46. 修复 - 全局变量可重复定义 key。
47. 修复 - 全局变量在 Debug 模式下不可持久化。
48. 修复 - 全局变量在 API 中无法持久化。
49. 修复 - OpenAPI，detail=false模式下，不应该返回 tool 调用结果，仅返回文字。（可解决 cow 不适配问题）。
50. 修复 - 知识库标签重复加载。
51. 修复 - 网络链接重新获取时，自定义分割符不生效。
52. 修复 - 插件运行时，会传递额外的全局变量，可能造成插件内变量污染。
53. 文档 - qa docs。
54. 文档 - Update feishu.md。
55. 文档 - update baseURL。
file: ./content/self-host/upgrading/outdated/4811.en.mdx
meta: {
"title": "V4.8.11 (Upgrade Script)",
"description": "FastGPT V4.8.11 Release Notes"
}
## Upgrade Guide
### 1. Back up your data
### 2. Update configuration file
To add the OpenAI o1 model, add the following configuration:
```json
{
"model": "o1-mini",
"name": "o1-mini",
"avatar": "/imgs/model/openai.svg",
"maxContext": 125000,
"maxResponse": 65000,
"quoteMaxToken": 120000,
"maxTemperature": 1.2,
"charsPointsPrice": 0,
"censor": false,
"vision": false,
"datasetProcess": true,
"usedInClassify": true,
"usedInExtractFields": true,
"usedInToolCall": true,
"toolChoice": false,
"functionCall": false,
"customCQPrompt": "",
"customExtractPrompt": "",
"defaultSystemChatPrompt": "",
"defaultConfig": {
"temperature": 1
}
},
{
"model": "o1-preview",
"name": "o1-preview",
"avatar": "/imgs/model/openai.svg",
"maxContext": 125000,
"maxResponse": 32000,
"quoteMaxToken": 120000,
"maxTemperature": 1.2,
"charsPointsPrice": 0,
"censor": false,
"vision": false,
"datasetProcess": true,
"usedInClassify": true,
"usedInExtractFields": true,
"usedInToolCall": true,
"toolChoice": false,
"functionCall": false,
"customCQPrompt": "",
"customExtractPrompt": "",
"defaultSystemChatPrompt": "",
"defaultConfig": {
"temperature": 1
}
}
```
***
### 3. Update image tags and restart
* Update the FastGPT image tag to v4.8.11-fix
* Update the FastGPT commercial edition image tag to v4.8.11
* Update the FastGPT Sandbox image tag to v4.8.11
### 4. Commercial Edition initialization
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/init/4811' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This initializes team member groups.
## V4.8.11 Release Notes
1. New - Form input node, allowing users to enter information during workflow execution.
2. New - Loop execution node that accepts an array for batch processing, currently supporting up to 50 items in serial execution.
3. New - Nodes can now be collapsed.
4. New - Simple Mode supports a new history mode that records local change history.
5. New - Chat history now uses scroll-based loading instead of only loading 30 messages.
6. New - Workflow adds a trackpad-priority mode, toggled via the button in the bottom-right corner.
7. New - Sandbox adds a string-to-Base64 global method (global variable `strToBase64`).
8. New - Support for OpenAI o1 models. Requires adding `defaultConfig` to the model configuration to override `temperature`, `max_tokens`, and `stream` settings, as o1 does not support stream mode.
9. New - AI chat node Knowledge Base references now support configuring `role=system` and `role=user`. Nodes with custom prompts already configured will keep `user` mode; all others will switch to `system` mode.
10. New - Plugins support uploading system files.
11. New - Plugin outputs support designating specific fields as tool responses.
12. New - When nesting child apps in workflows, you can now set "non-stream mode". Simple Mode can also select workflows as plugins. Simple Mode always forces non-stream mode when calling child apps.
13. New - In debug mode, child app calls return detailed execution data.
14. New - Logs for nested child app calls are now preserved in all modes.
15. New - Chat logs display team members.
16. New - Commercial edition supports configuring AI-generated copy prompts in the admin panel.
17. New - Jest unit testing framework.
18. New - Tool call parameter node for fully custom parameter declarations with tool calls.
19. New - BI chart plugin.
20. New - Surya OCR recognition module example.
21. New - Right-click to add comments in workflows.
22. Commercial - Team member groups.
23. Improved - Workflow nesting limited to 20 levels to prevent infinite loops from improper configurations.
24. Improved - Workflow handler performance.
25. Improved - Workflow shortcuts no longer trigger copy and undo during debug testing.
26. Improved - Removed extra "#" from names when copying workflow nodes.
27. Improved - Stream output continues even after switching browser tabs.
28. Improved - Enhanced external file Knowledge Base APIs.
29. Improved - Updated config.json path.
30. Improved - Properly handle hyperlinks starting with `//`.
31. Improved - Workflow Textarea scrolls normally instead of zooming.
32. Improved - Trimmed leading/trailing spaces from some input fields.
33. Improved - Returning to workflow now navigates to the last remembered tab.
34. Improved - Workflow canvas prevents trackpad browser zoom.
35. Improved - Some workflow nodes auto-select user question as the initial value.
36. Improved - Prompt Editor supports dynamic height expansion.
37. Improved - Auto-complete tool descriptions.
38. Improved - Updated configuration.md documentation.
39. Improved - iOS Safari voice input accuracy.
40. Fixed - Knowledge Base selection permission issue.
41. Fixed - Starting a conversation with an empty chatId caused errors when the first message included user selections.
42. Fixed - `createDataset` API not assigning `intro`.
43. Fixed - Chat dialog rendering performance issue.
44. Fixed - Rerank documentation URL.
45. Fixed - In stream mode with toolChoice, the `function` and `type` fields of toolCall could be null.
46. Fixed - Site sync custom separators not syncing.
47. Fixed - Tool call history storage issue.
48. Fixed - Chat page could enter an infinite redirect loop.
49. Fixed - Global variables not persisting across tool calls.
file: ./content/self-host/upgrading/outdated/4811.mdx
meta: {
"title": "V4.8.11（升级脚本）",
"description": "FastGPT V4.8.11 更新说明"
}
## 更新指南
### 1. 做好数据备份
### 2. 修改配置文件
如需增加 openai o1 模型，可添加如下配置：
```json
{
"model": "o1-mini",
"name": "o1-mini",
"avatar": "/imgs/model/openai.svg",
"maxContext": 125000,
"maxResponse": 65000,
"quoteMaxToken": 120000,
"maxTemperature": 1.2,
"charsPointsPrice": 0,
"censor": false,
"vision": false,
"datasetProcess": true,
"usedInClassify": true,
"usedInExtractFields": true,
"usedInToolCall": true,
"toolChoice": false,
"functionCall": false,
"customCQPrompt": "",
"customExtractPrompt": "",
"defaultSystemChatPrompt": "",
"defaultConfig": {
"temperature": 1
}
},
{
"model": "o1-preview",
"name": "o1-preview",
"avatar": "/imgs/model/openai.svg",
"maxContext": 125000,
"maxResponse": 32000,
"quoteMaxToken": 120000,
"maxTemperature": 1.2,
"charsPointsPrice": 0,
"censor": false,
"vision": false,
"datasetProcess": true,
"usedInClassify": true,
"usedInExtractFields": true,
"usedInToolCall": true,
"toolChoice": false,
"functionCall": false,
"customCQPrompt": "",
"customExtractPrompt": "",
"defaultSystemChatPrompt": "",
"defaultConfig": {
"temperature": 1
}
}
```
***
### 3. 修改镜像 tag 并重启
* 更新 FastGPT 镜像 tag: v4.8.11-fix
* 更新 FastGPT 商业版镜像 tag: v4.8.11
* 更新 FastGPT Sandbox 镜像 tag: v4.8.11
### 4. 商业版初始化
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成 **FastGPT 域名**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/init/4811' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会初始化团队成员组。
## V4.8.11 更新说明
1. 新增 - 表单输入节点，允许用户在工作流中让用户输入一些信息。
2. 新增 - 循环运行节点，可传入数组进行批量调用，目前最多支持 50 长度的数组串行执行。
3. 新增 - 节点支持折叠。
4. 新增 - 简易模式支持新的历史记录模式，可记录本地变更记录。
5. 新增 - 聊天记录滚动加载，不再只加载 30 条。
6. 新增 - 工作流增加触摸板优先模式，可以通过工作流右下角按键进行切换。
7. 新增 - 沙盒增加字符串转 base64 全局方法(全局变量 strToBase64)。
8. 新增 - 支持 Openai o1 模型，需增加模型的 `defaultConfig` 配置，覆盖 `temperature`、`max_tokens` 和 `stream` 配置，o1 不支持 stream 模式。
9. 新增 - AI 对话节点知识库引用，支持配置 role=system 和 role=user，已配置的过自定义提示词的节点将会保持 user 模式，其余用户将转成 system 模式。
10. 新增 - 插件支持上传系统文件。
11. 新增 - 插件输出，支持指定字段作为工具响应。
12. 新增 - 支持工作流嵌套子应用时，可以设置 `非流模式`，同时简易模式也可以选择工作流作为插件了，简易模式调用子应用时，都将强制使用非流模式。
13. 新增 - 调试模式下，子应用调用，支持返回详细运行数据。
14. 新增 - 保留所有模式下子应用嵌套调用的日志。
15. 新增 - 对话日志显示成员。
16. 新增 - 商业版支持后台配置 AI 生成文案提示。
17. 新增 - Jest 单测框架。
18. 新增 - 工具调用参数节点，可以配合工具调用完全自由声明参数。
19. 新增 - BI 图表插件。
20. 新增 - Surya OCR 识别模块示例。
21. 新增 - 工作流右键新增注释。
22. 商业版新增 - 团队成员组。
23. 优化 - 工作流嵌套层级限制 20 层，避免因编排不合理导致的无限死循环。
24. 优化 - 工作流 handler 性能优化。
25. 优化 - 工作流快捷键，避免调试测试时也会触发复制和回退。
26. 优化 - 工作流复制时，名字去掉多余“#”。
27. 优化 - 流输出，切换浏览器 Tab 后仍可以继续输出。
28. 优化 - 完善外部文件知识库相关 API。
29. 优化 - 修改 config.json 的地址。
30. 优化 - 正确处理//开头的超链接。
31. 优化 - 工作流 Textarea 滚轮可以正常滚动而不是缩放。
32. 优化 - 去除部分输入框前后空格。
33. 优化 - 工作流返回时，跳转到上一次记忆的 Tab。
34. 优化 - 工作流画布禁止触摸板缩放浏览器。
35. 优化 - 工作流部分节点会自动选择用户问题作为初始值。
36. 优化 - Prompt Editor 支持动态增高。
37. 优化 - 自动补全工具描述。
38. 优化 - 文档说明 configuration.md。
39. 优化 - iOS safari 浏览器语音输入不准确。
40. 修复 - 知识库选择权限问题。
41. 修复 - 空 chatId 发起会话，首轮携带用户选择时会异常。
42. 修复 - createDataset 接口，intro 未赋值。
43. 修复 - 对话框渲染性能问题。
44. 修复 - Rerank 文档地址。
45. 修复 - Stream 模式下使用 toolChoice,toolCall 的 function 和 type 可能为 null。
46. 修复 - 站点同步自定义分割符未同步。
47. 修复 - 工具调用历史记录存储问题。
48. 修复 - 对话页面可能无限重定向。
49. 修复 - 全局变量在工具调用中未持久传递。
file: ./content/self-host/upgrading/outdated/4812.en.mdx
meta: {
"title": "V4.8.12 (Upgrade Script)",
"description": "FastGPT V4.8.12 Release Notes"
}
## Upgrade Guide
### 1. Back up your data
### 2. Update images
* Update the FastGPT image tag to v4.8.12-fix
* Update the FastGPT admin image tag to v4.8.12 (fastgpt-pro image)
* Sandbox image update is optional
### 3. Run initialization (Commercial Edition)
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/init/4812' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This initializes member group data for apps and Knowledge Bases.
### 4. Rebuild Milvus data
Due to JavaScript int64 precision loss, users who previously deployed with Milvus or Zilliz and experienced data precision loss need to rebuild their Milvus data. (Check the `dataset_datas` collection — if `dataId` values in the `indexes` field have trailing precision loss, a rebuild is needed.) PG users do not need to take action.
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**.
```bash
curl --location --request POST 'https://{{host}}/api/admin/resetMilvus' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
## Release Notes
1. New - Global variables support number type, with configurable default values and input field parameters.
2. New - Plugin custom inputs (text fields, number fields, select boxes, toggles) all support being referenced as variables by default.
3. New - `FE_DOMAIN` environment variable. When configured, uploaded files/images get a complete URL with the domain suffix (resolves the issue where models sometimes fabricate image domains for docx file image links).
4. New - Tool calls support using the interaction node.
5. New - Debug mode supports inputting global variables.
6. New - Chat OpenAPI documentation.
7. New - Wiki search plugin.
8. New - Google search plugin.
9. New - Database connection and operation plugin.
10. New - Cookie privacy policy prompt.
11. New - HTTP node supports JSONPath expressions.
12. New - Apps and Knowledge Bases support member group permission configuration.
13. Improved - Loop node supports selecting variables from external nodes.
14. Improved - Docx file reading: optimized HTML-to-Markdown conversion for better speed and significantly reduced memory consumption.
15. Fixed - File extension detection now ignores query string parameters.
16. Fixed - Empty AI responses causing LLM history record merging.
17. Fixed - User interaction node not blocking the workflow.
18. Fixed - Creating a new app sometimes causing a null pointer error.
19. Fixed - Incorrect execution when multiple loop nodes are present.
20. Fixed - Variable modifications inside loop nodes not propagating.
21. Fixed - In non-stream mode, nested child apps/plugins unable to receive child app responses.
22. Fixed - Data chunking strategy now chunks each Markdown section independently.
file: ./content/self-host/upgrading/outdated/4812.mdx
meta: {
"title": "V4.8.12（升级脚本）",
"description": "FastGPT V4.8.12 更新说明"
}
## 更新指南
### 1. 做好数据备份
### 2. 修改镜像
* 更新 FastGPT 镜像 tag: v4.8.12-fix
* 更新 FastGPT 管理端镜像 tag: v4.8.12 （fastgpt-pro镜像）
* Sandbox 镜像，可以不更新
### 3. 商业版执行初始化
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/init/4812' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会初始化应用和知识库的成员组数据。
### 4. 重构 Milvus 数据
由于 js int64 精度丢失问题，之前私有化使用 milvus 或者 zilliz 的用户，如果存在数据精度丢失的问题，需要重构 Milvus 数据。（可以查看 dataset\_datas 表中，indexes 中的 dataId 是否末尾精度丢失）。使用 PG 的用户不需要操作。
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**。
```bash
curl --location --request POST 'https://{{host}}/api/admin/resetMilvus' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
## 更新说明
1. 新增 - 全局变量支持数字类型，支持配置默认值和部分输入框参数。
2. 新增 - 插件自定义输入，文本输入框、数字输入框、选择框、开关，默认都支持作为变量引用。
3. 新增 - FE\_DOMAIN 环境变量，配置该环境变量后，上传文件/图片会补全后缀后得到完整地址。（可解决 docx 文件图片链接，有时模型会伪造图片域名）
4. 新增 - 工具调用支持使用交互节点
5. 新增 - Debug 模式支持输入全局变量
6. 新增 - chat OpenAPI 文档
7. 新增 - wiki 搜索插件
8. 新增 - Google 搜索插件
9. 新增 - 数据库连接和操作插件
10. 新增 - Cookie 隐私协议提示
11. 新增 - HTTP 节点支持 JSONPath 表达式
12. 新增 - 应用和知识库支持成员组配置权限
13. 优化 - 循环节点支持选择外部节点的变量
14. 优化 - Docx 文件读取中， HTML to Markdown 优化，提高速度和大幅度降低内存消耗。
15. 修复 - 文件后缀判断，去除 query 影响。
16. 修复 - AI 响应为空时，会造成 LLM 历史记录合并。
17. 修复 - 用户交互节点未阻塞流程。
18. 修复 - 新建 APP，有时候会导致空指针报错。
19. 修复 - 拥有多个循环节点时，错误运行。
20. 修复 - 循环节点中修改变量，无法传递。
21. 修复 - 非 stream 模式，嵌套子应用/插件执行时无法获取子应用响应。
22. 修复 - 数据分块策略，同时将每个 Markdown 独立分块。
file: ./content/self-host/upgrading/outdated/4813.en.mdx
meta: {
"title": "V4.8.13 (Environment Changes)",
"description": "FastGPT V4.8.13 Release Notes"
}
## Upgrade Guide
### 1. Back up your data
### 2. Update images
* Update the FastGPT image tag to v4.8.13-fix
* Update the FastGPT commercial edition image tag to v4.8.13-fix (fastgpt-pro image)
* Sandbox image update is optional
### 3. Add environment variables
* Add the environment variable `FE_DOMAIN=http://xx.com` to both the fastgpt and fastgpt-pro images. Set the value to the FastGPT frontend access URL (do not include a trailing `/`). This automatically prepends the domain to relative file paths.
### 4. Update file upload workflow configuration
While the old file upload workflow configuration is still supported, backward compatibility will be removed within the next two versions. Please update your workflows to use the new file upload logic as soon as possible. In particular, file passing in nested apps will no longer be automatic — you must explicitly specify which files to pass. For details, see: [File Upload Changes](../../../guide/build/general/fileInput.en.mdx#4813%E7%89%88%E6%9C%AC%E8%B5%B7%E5%85%B3%E4%BA%8E%E6%96%87%E4%BB%B6%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%9B%B4%E6%96%B0)
## Release Notes
1. New - Array variable selection supports multi-select. You can select multiple arrays or their corresponding single data types, which are automatically merged in selection order.
2. New - Revamped file upload approach. AI chat and tool call nodes directly accept file URLs and enforce prompt injection without relying on model-driven decisions. Plugin custom variables support file upload types, replacing global files.
3. New - Chat history now displays timestamps.
4. New - Workflow validation errors now navigate to the error node.
5. New - Loop node adds an index value.
6. New - Added translations for some chat error messages.
7. New - Chat input box supports drag-and-drop file upload.
8. New - Chat logs now show the specific share link/API name as the source.
9. New - Share links support configuring whether to display real-time execution status.
10. Improved - Merged multiple system prompts into one to support models that don't accept multiple system prompts.
11. Improved - Better error messages for Knowledge Base file uploads.
12. Improved - Full-text search query optimization, eliminating one subquery.
13. Improved - Replaced `findLast` with `[...array].reverse().find` for older browser compatibility.
14. Improved - Markdown component auto-spacing to avoid splitting Chinese characters in URLs.
15. Improved - Workflow context splitting for better performance.
16. Improved - Text-to-speech: browsers that don't support `mediaSource` can now wait for full audio generation before playback.
17. Improved - Chat starter CSV reading with automatic encoding detection.
18. Improved - Fixed potential garbled text when importing chat starters via CSV.
19. Fixed - Dockerfile pnpm install now supports proxy.
20. Fixed - Dockerfile pnpm install now supports proxy.
21. Fixed - BI chart generation unable to write files. Also improved parsing to support numeric array types.
22. Fixed - Share link title displaying incorrectly on first load.
file: ./content/self-host/upgrading/outdated/4813.mdx
meta: {
"title": "V4.8.13（环境变量变更）",
"description": "FastGPT V4.8.13 更新说明"
}
## 更新指南
### 1. 做好数据备份
### 2. 修改镜像
* 更新 FastGPT 镜像 tag: v4.8.13-fix
* 更新 FastGPT 商业版镜像 tag: v4.8.13-fix （fastgpt-pro镜像）
* Sandbox 镜像，可以不更新
### 3. 添加环境变量
* 给 fastgpt 和 fastgpt-pro 镜像添加环境变量：`FE_DOMAIN=http://xx.com`，值为 fastgpt 前端访问地址，注意后面不要加`/`。可以自动补齐相对文件地址的前缀。
### 4. 调整文件上传编排
虽然依然兼容旧版的文件上传编排，但是未来两个版本内将会去除兼容代码，请尽快调整编排，以适应最新的文件上传逻辑。尤其是嵌套应用的文件传递，未来将不会自动传递，必须手动指定传递的文件。具体内容可参考: [文件上传变更](../../../guide/build/general/fileInput.mdx#4813%E7%89%88%E6%9C%AC%E8%B5%B7%E5%85%B3%E4%BA%8E%E6%96%87%E4%BB%B6%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%9B%B4%E6%96%B0)
## 更新说明
1. 新增 - 数组变量选择支持多选，可以选多个数组或对应的单一数据类型，会自动按选择顺序进行合并。
2. 新增 - 文件上传方案调整，AI对话和工具调用节点直接支持接收文件链接，并且会强制加入提示词，无需由模型决策调用。插件自定义变量支持文件上传类型，取代全局文件。
3. 新增 - 对话记录增加时间显示。
4. 新增 - 工作流校验错误时，跳转至错误节点。
5. 新增 - 循环节点增加下标值。
6. 新增 - 部分对话错误提醒增加翻译。
7. 新增 - 对话输入框支持拖拽文件上传，可直接拖文件到输入框中。
8. 新增 - 对话日志，来源可显示分享链接/API具体名称
9. 新增 - 分享链接支持配置是否展示实时运行状态。
10. 优化 - 合并多个 system 提示词成 1 个，避免部分模型不支持多个 system 提示词。
11. 优化 - 知识库上传文件，优化报错提示。
12. 优化 - 全文检索语句，减少一轮子查询。
13. 优化 - 修改 findLast 为 \[...array].reverse().find，适配旧版浏览器。
14. 优化 - Markdown 组件自动空格，避免分割 url 中的中文。
15. 优化 - 工作流上下文拆分，性能优化。
16. 优化 - 语音播报，不支持 mediaSource 的浏览器可等待完全生成语音后输出。
17. 优化 - 对话引导 csv 读取，自动识别编码
18. 优化 - csv 导入问题引导可能乱码
19. 修复 - Dockerfile pnpm install 支持代理。。
20. 修复 - Dockerfile pnpm install 支持代理。
21. 修复 - BI 图表生成无法写入文件。同时优化其解析，支持数字类型数组。
22. 修复 - 分享链接首次加载时，标题显示不正确。
file: ./content/self-host/upgrading/outdated/4814.en.mdx
meta: {
"title": "V4.8.14",
"description": "FastGPT V4.8.14 Release Notes"
}
## Upgrade Guide
### 1. Back up your data
### 2. Update images
* Update the FastGPT image tag to v4.8.14-fix
* Update the FastGPT commercial edition image tag to v4.8.14 (fastgpt-pro image)
* Sandbox image update is optional
For Milvus users: use the v4.8.14-milvus-fix image.
## New Feature Preview
### Auto-trigger Workflow
You can configure a workflow to automatically trigger once when a user loads a conversation. This is useful for CRM systems where you want to proactively guide users without waiting for them to initiate.
| | |
| ------------------------------------------------ | ------------------------------------------------ |
|  |  |
## Full Release Notes
1. New - Workflows support auto-triggering a conversation round when entering the chat or clicking "Start conversation".
2. New - Rewritten chatContext. Chat testing now generates logs, and conversations persist after page refresh.
3. New - Share links support configuring whether to allow viewing original source text.
4. New - New doc2x plugin.
5. New - Traditional Chinese language support.
6. New - Share links and chat API support passing a custom uid.
7. Commercial - Microsoft OAuth login.
8. Improved - Workflow UI details.
9. Improved - App edit history now uses diff-based storage to prevent browser overflow.
10. Improved - Code entry point adds a register entry, no longer requiring the first visit to execute.
11. Improved - Workflow validation with additional missing value checks.
12. Improved - Added maximum retry limit for Knowledge Base training.
13. Improved - Image path issues and diagram tasks.
14. Improved - Milvus description.
15. Fixed - Chunking strategy was dropping level-4 headings. Also added level-5 heading support.
16. Fixed - MongoDB Knowledge Base collection unique index.
17. Fixed - Deselecting Knowledge Base references could cause errors.
18. Fixed - Converting Simple Mode to workflow was not using the latest edit history.
19. Fixed - Form input description text not displaying.
20. Fixed - API unable to use Base64 images.
file: ./content/self-host/upgrading/outdated/4814.mdx
meta: {
"title": "V4.8.14",
"description": "FastGPT V4.8.14 更新说明"
}
## 更新指南
### 1. 做好数据备份
### 2. 修改镜像
* 更新 FastGPT 镜像 tag: v4.8.14-fix
* 更新 FastGPT 商业版镜像 tag: v4.8.14 （fastgpt-pro镜像）
* Sandbox 镜像，可以不更新
milvus版本使用：v4.8.14-milvus-fix 镜像。
## 新功能预览
### 自动触发工作流
可以允许你配置用户加载对话时，自动触发一次工作流。可以用于一些 CRM 系统，可以快速的引导用户使用，无需等待用户主动触发。
| | |
| ------------------------------------------------ | ------------------------------------------------ |
|  |  |
## 完整更新内容
1. 新增 - 工作流支持进入聊天框/点击开始对话后，自动触发一轮对话。
2. 新增 - 重写 chatContext，对话测试也会有日志，并且刷新后不会丢失对话。
3. 新增 - 分享链接支持配置是否允许查看原文。
4. 新增 - 新的 doc2x 插件。
5. 新增 - 繁体中文。
6. 新增 - 分析链接和 chat api 支持传入自定义 uid。
7. 商业版新增 - 微软 oauth 登录
8. 优化 - 工作流 ui 细节。
9. 优化 - 应用编辑记录采用 diff 存储，避免浏览器溢出。
10. 优化 - 代码入口，增加 register 入口，无需等待首次访问才执行。
11. 优化 - 工作流检查，增加更多缺失值检查。
12. 优化 - 增加知识库训练最大重试次数限制。
13. 优化 - 图片路径问题和示意图任务
14. 优化 - Milvus description
15. 修复 - 分块策略，四级标题会被丢失。 同时新增了五级标题的支持。
16. 修复 - MongoDB 知识库集合唯一索引。
17. 修复 - 反选知识库引用后可能会报错。
18. 修复 - 简易模式转工作流，不是使用最新编辑记录进行转移。
19. 修复 - 表单输入的说明文字不显示。
20. 修复 - API 无法使用 base64 图片。
file: ./content/self-host/upgrading/outdated/4815.en.mdx
meta: {
"title": "V4.8.15 (Upgrade Script)",
"description": "FastGPT V4.8.15 Release Notes"
}
## New Feature Preview
### API Knowledge Base
| | |
| ------------------------------------------------- | ------------------------------------------------- |
|  |  |
### HTML Rendering
| Source Mode | Preview Mode | Fullscreen Mode |
| ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
|  |  |  |
## Upgrade Guide
* Update the fastgpt image tag to v4.8.15-fix3
* Update the fastgpt-pro commercial edition image tag to v4.8.15
* Sandbox image update is optional
## Run Migration Script
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4815' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This resets the scheduled execution fields for apps, removing null values to reduce index size.
***
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/init/refreshFreeUser' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This recalculates free-tier user durations. A previous version upgrade did not recalculate time properly, which caused incorrect notifications.
## Full Release Notes
1. New - API Knowledge Base. See [API Knowledge Base Introduction](../../../guide/dataset/third-party/api_dataset.en.mdx). The external file library will be deprecated.
2. New - Toolbox page displaying all available system resources. The commercial edition admin panel now offers easier configuration of system plugins and custom categories.
3. New - HTML code in Markdown is now rendered separately. You can choose preview mode, which blocks all scripts and only displays content.
4. New - Custom system-level file parsing service. See [Integrating Marker PDF Document Parsing](../../custom-models/marker.en.mdx).
5. New - Collections can be reconfigured directly without deleting and re-importing.
6. New - Commercial edition admin panel supports configuring sidebar navigation links.
7. Improved - Base64 image truncation detection.
8. Improved - i18n cookie detection.
9. Improved - Markdown text splitting now supports heading-only sections with no content.
10. Improved - String variable substitution: unassigned variables now resolve to `undefined` instead of preserving the raw ID string.
11. Improved - Global variable default values now take effect in API calls, and custom variables support default values.
12. Improved - Added JSON parsing for HTTP Body with regex conversion of `undefined` to `null`, reducing Body parsing errors.
13. Improved - Scheduled execution now includes run logs and retries to reduce error rates.
14. Fixed - Share link like/upvote authentication issue.
15. Fixed - Switching to an auto-execute app on the chat page could incorrectly trigger non-auto-execute apps.
16. Fixed - Audio playback authentication issue.
17. Fixed - Plugin app Knowledge Base reference limit was always capped at 3000.
18. Fixed - Workflow edit history storage limit. Removed local storage and added forced auto-save on abnormal exit.
19. Fixed - Workflow special variable substitution issue (strings starting with `$` could not be replaced).
file: ./content/self-host/upgrading/outdated/4815.mdx
meta: {
"title": "V4.8.15（升级脚本）",
"description": "FastGPT V4.8.15 更新说明"
}
## 新功能预览
### API 知识库
| | |
| ------------------------------------------------- | ------------------------------------------------- |
|  |  |
### HTML 渲染
| 源码模式 | 预览模式 | 全屏模式 |
| ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
|  |  |  |
## 升级指南
* 更新 fastgpt 镜像 tag: v4.8.15-fix3
* 更新 fastgpt-pro 商业版镜像 tag: v4.8.15
* Sandbox 镜像，可以不更新
## 运行升级脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4815' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会重置应用定时执行的字段，把 null 去掉，减少索引大小。
***
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/init/refreshFreeUser' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
重新计算一次免费版用户的时长，之前有版本升级时没有重新计算时间，导致会误发通知。
## 完整更新内容
1. 新增 - API 知识库, 见 [API 知识库介绍](../../../guide/dataset/third-party/api_dataset.mdx)，外部文件库会被弃用。
2. 新增 - 工具箱页面，展示所有可用的系统资源。商业版后台可更便捷的配置系统插件和自定义分类。
3. 新增 - Markdown 中，HTML代码会被额外渲染，可以选择预览模式，会限制所有 script 脚本，仅做展示。
4. 新增 - 自定义系统级文件解析服务, 见 [接入 Marker PDF 文档解析](../../custom-models/marker.mdx)
5. 新增 - 集合直接重新调整参数，无需删除再导入。
6. 新增 - 商业版后台支持配置侧边栏跳转链接。
7. 优化 - base64 图片截取判断。
8. 优化 - i18n cookie 判断。
9. 优化 - 支持 Markdown 文本分割时，只有标题，无内容。
10. 优化 - 字符串变量替换，未赋值的变量会转成 undefined，而不是保留原来 id 串。
11. 优化 - 全局变量默认值在 API 生效，并且自定义变量支持默认值。
12. 优化 - 增加 HTTP Body 的 JSON 解析，正则将 undefined 转 null，减少 Body 解析错误。
13. 优化 - 定时执行增加运行日志，增加重试，减少报错概率。
14. 修复 - 分享链接点赞鉴权问题。
15. 修复 - 对话页面切换自动执行应用时，会误触发非自动执行应用。
16. 修复 - 语言播放鉴权问题。
17. 修复 - 插件应用知识库引用上限始终为 3000
18. 修复 - 工作流编辑记录存储上限，去掉本地存储，增加异常离开时，强制自动保存。
19. 修复 - 工作流特殊变量替换问题。（$开头的字符串无法替换）
file: ./content/self-host/upgrading/outdated/4816.en.mdx
meta: {
"title": "V4.8.16 (Configuration Changes)",
"description": "FastGPT V4.8.16 Release Notes"
}
## Upgrade Guide
### 1. Update images:
* Update the fastgpt image tag to v4.8.16
* Update the fastgpt-pro commercial edition image tag to v4.8.16
* Update the Sandbox image tag to v4.8.16
### 2. Update configuration file
Update your `config.json` or admin model configuration. Add the `provider` field to LLMModel and VectorModel for model categorization. The legacy `config.json` guide is no longer maintained. For current versions, see [Model Configuration](../../config/model/intro.en.mdx). For example:
```json
{
"provider": "OpenAI", // This is new
"model": "gpt-4o",
"name": "gpt-4o",
"maxContext": 125000,
"maxResponse": 4000,
"quoteMaxToken": 120000,
"maxTemperature": 1.2,
"charsPointsPrice": 0,
"censor": false,
"vision": true,
"datasetProcess": true,
"usedInClassify": true,
"usedInExtractFields": true,
"usedInToolCall": true,
"usedInQueryExtension": true,
"toolChoice": true,
"functionCall": false,
"customCQPrompt": "",
"customExtractPrompt": "",
"defaultSystemChatPrompt": "",
"defaultConfig": {},
"fieldMap": {}
}
```
## Full Release Notes
1. New - SearXNG search plugin.
2. New - Commercial edition supports scheduled sync for API Knowledge Bases and link collections.
3. New - "Suggested questions" supports model selection and custom prompts.
4. New - DingTalk and WeCom bot webhook plugins.
5. New - Commercial edition supports DingTalk SSO login configuration. [View tutorial](../../../guide/admin/sso.en.mdx#钉钉)
6. New - Commercial edition supports Lark and Yuque Knowledge Base import. [View tutorial](../../../guide/dataset/third-party/lark_dataset.en.mdx)
7. New - Sandbox adds `createHmac` encryption global method.
8. New - Right-click in workflow supports "Collapse all".
9. Improved - Model selector.
10. Improved - SSR rendering now pre-detects mobile vs. desktop to reduce page jitter.
11. Improved - Workflow/Simple Mode variable initialization code. Removed listener-based initialization to prevent failures from inconsistent render order.
12. Improved - Workflow now performs type conversion when receiving mismatched data types, preventing `undefined`.
13. Fixed - Unable to auto-switch default language. Share links now force a default language switch on load.
14. Fixed - Array selector auto-compatibility with pre-4.8.13 data.
15. Fixed - Site sync Knowledge Base not using the selector for link syncing.
16. Fixed - Converting Simple Mode to workflow did not convert system configuration items.
17. Fixed - Plugin standalone execution not applying initial variable values.
18. Fixed - Workflow modal components sometimes causing page offset after closing.
19. Fixed - Plugin debug logs not saving plugin input parameters.
20. Fixed - Some template marketplace templates.
21. Fixed - Incorrect image file URL when NEXT\_PUBLIC\_BASE\_URL is set.
file: ./content/self-host/upgrading/outdated/4816.mdx
meta: {
"title": "V4.8.16（配置变更）",
"description": "FastGPT V4.8.16 更新说明"
}
## 更新指南
### 1. 更新镜像：
* 更新 fastgpt 镜像 tag: v4.8.16
* 更新 fastgpt-pro 商业版镜像 tag: v4.8.16
* Sandbox 镜像 tag: v4.8.16
### 2. 更新配置文件
更新 `config.json` 或 admin 中模型文件配置。给 LLMModel 和 VectorModel 增加 `provider` 字段，以便进行模型分类。旧版 `config.json` 配置说明已不再维护，当前版本请参考[模型配置方案](../../config/model/intro.mdx)。例如：
```json
{
"provider": "OpenAI", // 这是新增的
"model": "gpt-4o",
"name": "gpt-4o",
"maxContext": 125000,
"maxResponse": 4000,
"quoteMaxToken": 120000,
"maxTemperature": 1.2,
"charsPointsPrice": 0,
"censor": false,
"vision": true,
"datasetProcess": true,
"usedInClassify": true,
"usedInExtractFields": true,
"usedInToolCall": true,
"usedInQueryExtension": true,
"toolChoice": true,
"functionCall": false,
"customCQPrompt": "",
"customExtractPrompt": "",
"defaultSystemChatPrompt": "",
"defaultConfig": {},
"fieldMap": {}
}
```
## 完整更新内容
1. 新增 - SearXNG 搜索插件
2. 新增 - 商业版支持 API 知识库和链接集合定时同步。
3. 新增 - 猜你想问支持选择模型和自定义提示词。
4. 新增 - 钉钉和企微机器人 webhook 插件。
5. 新增 - 商业版支持钉钉 SSO 登录配置。[点击查看教程](../../../guide/admin/sso.mdx#钉钉)
6. 新增 - 商业版支持飞书和语雀知识库导入。[点击查看教程](../../../guide/dataset/third-party/lark_dataset.mdx)
7. 新增 - sandbox 新增 createHmac 加密全局方法。
8. 新增 - 工作流右键支持全部折叠。
9. 优化 - 模型选择器。
10. 优化 - SSR 渲染，预判断是移动端还是 pc 端，减少页面抖动。
11. 优化 - 工作流/简易模式变量初始化代码，去除监听初始化，避免因渲染顺序不一致导致的失败。
12. 优化 - 工作流获取数据类型不一致数据时，增加类型转化，避免 undefined。
13. 修复 - 无法自动切换默认语言。增加分享链接，强制执行一次切换默认语言。
14. 修复 - 数组选择器自动兼容 4.8.13 以前的数据。
15. 修复 - 站点同步知识库，链接同步时未使用选择器。
16. 修复 - 简易模式转工作流，没有把系统配置项转化。
17. 修复 - 插件独立运行，变量初始值未赋上。
18. 修复 - 工作流使用弹窗组件时，关闭弹窗后，有时候会出现页面偏移。
19. 修复 - 插件调试时，日志未保存插件输入参数。
20. 修复 - 部分模板市场模板
21. 修复 - 设置 NEXT\_PUBLIC\_BASE\_URL 时，图片文件读取 URL 不正确
file: ./content/self-host/upgrading/outdated/4817.en.mdx
meta: {
"title": "V4.8.17 (Upgrade Script)",
"description": "FastGPT V4.8.17 Release Notes"
}
## Upgrade Guide
### 1. Update images:
* Update the fastgpt image tag to v4.8.17-fix-title
* Update the fastgpt-pro commercial edition image tag to v4.8.17
* Sandbox image update is not required
### 2. Run migration script
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4817' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This migrates user-bound OpenAI accounts to the team level.
## Completions API response changes
The `/api/v1/chat/completions` endpoint response has been updated. Nodes that use models (chat nodes, tool nodes, etc.) will no longer return a `tokens` field. Instead, they return `inputTokens` and `outputTokens` fields representing the input and output token counts respectively.
## Full Release Notes
1. New - Simple Mode tool calls support array-type plugins.
2. New - Workflow adds auto-save on abnormal exit to prevent workflow loss.
3. New - LLM model parameters support disabling `max_tokens` and `temperature`.
4. New - Commercial edition supports configuring the template marketplace in the admin panel.
5. New - Commercial edition supports configuring custom workflow variables in the admin panel for business system authentication integration.
6. New - Search test API supports query optimization.
7. New - Input tokens and output tokens are now tracked and displayed separately in workflows. Also fixed billing not recording output tokens for some requests.
8. Improved - Markdown size check: content exceeding 200K characters no longer uses the Markdown component to prevent crashes.
9. Improved - Knowledge Base search parameters: sliders now support input mode for more precise control.
10. Improved - Available models display UI.
11. Improved - MongoDB queries with added virtual fields.
12. Fixed - File response API missing `Content-Length` header, causing Alibaba vision models to fail image recognition when uploading files from different origins.
13. Fixed - Removed hidden line breaks from both ends of condition node strings to prevent condition evaluation failures.
14. Fixed - Variable update node: non-string data types could not be auto-converted when manually entering update content.
15. Fixed - Doubao models unable to make tool calls.
file: ./content/self-host/upgrading/outdated/4817.mdx
meta: {
"title": "V4.8.17（升级脚本）",
"description": "FastGPT V4.8.17 更新说明"
}
## 更新指南
### 1. 更新镜像：
* 更新 fastgpt 镜像 tag: v4.8.17-fix-title
* 更新 fastgpt-pro 商业版镜像 tag: v4.8.17
* Sandbox 镜像无需更新
### 2. 运行升级脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**。
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4817' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会将用户绑定的 OpenAI 账号移动到团队中。
## 调整 completions 接口返回值
/api/v1/chat/completions 接口返回值调整，对话节点、工具节点等使用到模型的节点，将不再返回 `tokens` 字段，改为返回 `inputTokens` 和 `outputTokens` 字段，分别表示输入和输出的 Token 数量。
## 完整更新内容
1. 新增 - 简易模式工具调用支持数组类型插件。
2. 新增 - 工作流增加异常离开自动保存，避免工作流丢失。
3. 新增 - LLM 模型参数支持关闭 max\_tokens 和 temperature。
4. 新增 - 商业版支持后台配置模板市场。
5. 新增 - 商业版支持后台配置自定义工作流变量，用于与业务系统鉴权打通。
6. 新增 - 搜索测试接口支持问题优化。
7. 新增 - 工作流中 Input Token 和 Output Token 分开记录展示。并修复部分请求未记录输出 Token 计费问题。
8. 优化 - Markdown 大小测试，超出 20 万字符不使用 Markdown 组件，避免崩溃。
9. 优化 - 知识库搜索参数，滑动条支持输入模式，可以更精准的控制。
10. 优化 - 可用模型展示UI。
11. 优化 - Mongo 查询语句，增加 virtual 字段。
12. 修复 - 文件返回接口缺少 Content-Length 头，导致通过非同源文件上传时，阿里 vision 模型无法识别图片。
13. 修复 - 去除判断器两端字符串隐藏换行符，避免判断器失效。
14. 修复 - 变量更新节点，手动输入更新内容时候，非字符串类型数据类型无法自动转化。
15. 修复 - 豆包模型无法工具调用。
file: ./content/self-host/upgrading/outdated/4818.en.mdx
meta: {
"title": "V4.8.18 (Upgrade Script)",
"description": "FastGPT V4.8.18 Release Notes"
}
## Upgrade Guide
### 1. Update images:
* Update the fastgpt image tag to v4.8.18-fix
* Update the fastgpt-pro commercial edition image tag to v4.8.18-fix
* Sandbox image update is not required
### 2. Run migration script
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4818' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This migrates the full-text search table. The migration takes a while — full-text search will be unavailable during the process. The log will print the amount of data already migrated.
## Full Release Notes
1. New - Support creating apps directly via JSON configuration.
2. New - Support quickly creating HTTP plugins via CURL scripts.
3. New - Commercial edition supports department-based permission structure.
4. New - Support configuring custom CORS security policies (defaults to fully open).
5. New - Added model troubleshooting documentation for private deployments.
6. Improved - HTTP Body special handling to resolve parsing issues with newlines in string variables.
7. Improved - Share links generate random user avatars.
8. Improved - Image upload security validation. Added unique avatar image storage to prevent cumulative storage.
9. Improved - Separated MongoDB full-text index table.
10. Improved - Merged Knowledge Base search queries to reduce database calls.
11. Improved - File encoding detection to reduce CSV file garbled text.
12. Improved - Asynchronous file content reading to reduce process blocking.
13. Improved - File viewer: HTML files are now downloaded directly instead of being viewable online.
14. Fixed - HTML file upload: Base64 images not auto-converting to image URLs.
15. Fixed - Plugin billing errors.
file: ./content/self-host/upgrading/outdated/4818.mdx
meta: {
"title": "V4.8.18（升级脚本）",
"description": "FastGPT V4.8.18 更新说明"
}
## 更新指南
### 1. 更新镜像：
* 更新 fastgpt 镜像 tag: v4.8.18-fix
* 更新 fastgpt-pro 商业版镜像 tag: v4.8.18-fix
* Sandbox 镜像无需更新
### 2. 运行升级脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4818' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
会迁移全文检索表，时间较长，迁移期间全文检索会失效，日志中会打印已经迁移的数据长度。
## 完整更新内容
1. 新增 - 支持通过 JSON 配置直接创建应用。
2. 新增 - 支持通过 CURL 脚本快速创建 HTTP 插件。
3. 新增 - 商业版支持部门架构权限模式。
4. 新增 - 支持配置自定跨域安全策略，默认全开。
5. 新增 - 补充私有部署，模型问题排查文档。
6. 优化 - HTTP Body 增加特殊处理，解决字符串变量带换行时无法解析问题。
7. 优化 - 分享链接随机生成用户头像。
8. 优化 - 图片上传安全校验。并增加头像图片唯一存储，确保不会累计存储。
9. 优化 - Mongo 全文索引表分离。
10. 优化 - 知识库检索查询语句合并，同时减少查库数量。
11. 优化 - 文件编码检测，减少 CSV 文件乱码概率。
12. 优化 - 异步读取文件内容，减少进程阻塞。
13. 优化 - 文件阅读，HTML 直接下载，不允许在线阅读。
14. 修复 - HTML 文件上传，base64 图片无法自动转图片链接。
15. 修复 - 插件计费错误。
file: ./content/self-host/upgrading/outdated/4819.en.mdx
meta: {
"title": "V4.8.19 (Upgrade Script)",
"description": "FastGPT V4.8.19 Release Notes"
}
## Upgrade Guide
### 1. Update images:
* Update the fastgpt image tag to v4.8.19-beta
* Update the fastgpt-pro commercial edition image tag to v4.8.19-beta
* Sandbox image update is not required
### 2. Run migration script
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4819' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This migrates user avatars from the user table to the member table.
## Full Release Notes
1. New - Workflow Knowledge Base search supports filtering by Knowledge Base permissions.
2. New - Lark/Yuque Knowledge Base view original source.
3. New - Flow wait plugin that pauses execution for n milliseconds before continuing.
4. New - Lark bot integration supports configuring a private Lark server URL.
5. Improved - Member list pagination loading.
6. Improved - Unified pagination loading code.
7. Improved - Chat page loading now supports configuring whether it's a standalone page.
8. Improved - Member avatars migrated to the member table.
9. Fixed - Yuque file library import: nested file contents could not be expanded.
10. Fixed - Workflow editor: LLM parameters could not be disabled.
11. Fixed - Workflow editor: code execution node template restoration issue.
12. Fixed - HTTP interface object string parsing compatibility.
13. Fixed - API file upload (localFile) endpoint: image expiration flag not being cleared.
14. Fixed - Workflow import: number input types could not be overridden.
15. Fixed - Some model provider logos not displaying correctly.
file: ./content/self-host/upgrading/outdated/4819.mdx
meta: {
"title": "V4.8.19（升级脚本）",
"description": "FastGPT V4.8.19 更新说明"
}
## 更新指南
### 1. 更新镜像：
* 更新 fastgpt 镜像 tag: v4.8.19-beta
* 更新 fastgpt-pro 商业版镜像 tag: v4.8.19-beta
* Sandbox 镜像无需更新
### 2. 运行升级脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4819' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
迁移用户表的头像到成员表中。
## 完整更新内容
1. 新增 - 工作流知识库检索支持按知识库权限进行过滤。
2. 新增 - 飞书/语雀知识库查看原文。
3. 新增 - 流程等待插件，可以等待 n 毫秒后继续执行流程。
4. 新增 - 飞书机器人接入，支持配置私有化飞书地址。
5. 优化 - 成员列表分页加载。
6. 优化 - 统一分页加载代码。
7. 优化 - 对话页面加载时，可配置是否为独立页面。
8. 优化 - 成员头像迁移，移动到成员表。
9. 修复 - 语雀文件库导入时，嵌套文件内容无法展开的问题。
10. 修复 - 工作流编排中，LLM 参数无法关闭问题。
11. 修复 - 工作流编排中，代码运行节点还原模板问题。
12. 修复 - HTTP 接口适配对象字符串解析。
13. 修复 - 通过 API 上传文件（localFile）接口，图片过期标记未清除。
14. 修复 - 工作流导入编排时，number input 类型无法覆盖。
15. 修复 - 部分模型提供商 logo 无法正常显示。
file: ./content/self-host/upgrading/outdated/482.en.mdx
meta: {
"title": "V4.8.2 (Environment Changes)",
"description": "FastGPT V4.8.2 Release Notes"
}
## Sealos Upgrade Instructions
1. Create a new app in App Management with the image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sandbox:v4.8.1
2. No external access URL is needed. Set the port to 3000.
3. After deployment, copy the app's internal network address.
4. Click "Update" on FastGPT, modify the environment variables, and add the following:
```
SANDBOX_URL=internal-network-address
```
## Docker Deployment
You can pull the latest [docker-compose.yml](https://github.com/labring/FastGPT/blob/main/document/public/deploy/docker/main/global/docker-compose.pg.yml) file for reference.
1. Add a new `sandbox` container.
2. Add the `SANDBOX_URL` environment variable to the fastgpt and fastgpt-pro (commercial edition) containers.
3. It's recommended not to expose the sandbox to the public network, as it has no credential verification.
## V4.8.2 Release Notes
1. New - JavaScript code execution node (with improved type hints; more enhancements coming).
2. New - Content extraction node now supports data type selection.
3. Fixed - Newly added site sync not working.
4. Fixed - Scheduled tasks unable to accept input content.
file: ./content/self-host/upgrading/outdated/482.mdx
meta: {
"title": "V4.8.2（环境变量变更）",
"description": "FastGPT V4.8.2 更新说明"
}
## Sealos 升级说明
1. 在应用管理中新建一个应用，镜像为：registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sandbox:v4.8.1
2. 无需外网访问地址，端口号为 3000
3. 部署完后，复制应用的内网地址
4. 点击变更\`FastGPT - 修改环境变量，增加下面的环境变量即可
```
SANDBOX_URL=内网地址
```
## Docker 部署
可以拉取最新 [docker-compose.yml](https://github.com/labring/FastGPT/blob/main/document/public/deploy/docker/main/global/docker-compose.pg.yml) 文件参考
1. 新增一个容器 `sandbox`
2. fastgpt 和 fastgpt-pro(商业版) 容器新增环境变量: `SANDBOX_URL`
3. sandbox 简易不要开启外网访问，未做凭证校验。
## V4.8.2 更新说明
1. 新增 - js 代码运行节点（更完整的 type 提醒，后续继续完善）
2. 新增 - 内容提取节点支持数据类型选择
3. 修复 - 新增的站点同步无法使用
4. 修复 - 定时任务无法输入内容
file: ./content/self-host/upgrading/outdated/4820.en.mdx
meta: {
"title": "V4.8.20 (Environment Changes, Upgrade Script)",
"description": "FastGPT V4.8.20 Release Notes"
}
## Upgrade Guide
### 1. Back up your database
### 2. Update environment variables
If you are an early adopter who configured `ONEAPI_URL`, you need to change it to `OPENAI_BASE_URL`.
### 3. Update images:
* Update the fastgpt image tag to v4.8.20-fix2
* Update the fastgpt-pro commercial edition image tag to v4.8.20-fix2
* Sandbox image update is not required
### 4. Run migration script
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4820' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
The script automatically loads models from the old configuration file into the new model configuration.
## Full Release Notes
1. New - Visual model parameter configuration, replacing the old config file approach. Over 100 model presets included, with one-click testing for all model types. (Full in-page channel configuration is planned for the next version.) [View model configuration guide](../../config/model/intro.en.mdx)
2. New - DeepSeek Reasoner model supports outputting the thinking process.
3. New - Usage record export and dashboard.
4. New - Markdown syntax extension supporting audio and video (via `audio` and `video` code blocks).
5. New - Adjusted `max_tokens` calculation logic. `max_tokens` is now prioritized at the configured value; if it exceeds the maximum context, history is reduced instead. For example, requesting 8000 `max_tokens` reduces the context length by 8000.
6. Improved - Query optimization now includes context filtering to prevent exceeding context limits.
7. Improved - Page component extraction to reduce page component routing.
8. Improved - Full-text search is now case-insensitive.
9. Improved - QA generation and enhanced indexing switched to streaming output to prevent timeouts with some models.
10. Improved - Automatically adds `null` to empty assistant `content`, and merges consecutive text assistant messages to prevent errors from some models.
11. Improved - Adjusted image host: domain is no longer appended during upload but before sending a conversation, preventing broken images after domain changes.
12. Fixed - Member list not triggering bottom-loading in some scenarios.
13. Fixed - Workflow recursive execution failing under certain conditions.
file: ./content/self-host/upgrading/outdated/4820.mdx
meta: {
"title": "V4.8.20（环境变量变更、升级脚本）",
"description": "FastGPT V4.8.20 更新说明"
}
## 更新指南
### 1. 做好数据库备份
### 2. 更新环境变量
如果有很早版本用户，配置了`ONEAPI_URL`的，需要统一改成`OPENAI_BASE_URL`
### 3. 更新镜像：
* 更新 fastgpt 镜像 tag: v4.8.20-fix2
* 更新 fastgpt-pro 商业版镜像 tag: v4.8.20-fix2
* Sandbox 镜像无需更新
### 4. 运行升级脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4820' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
脚本会自动把原配置文件的模型加载到新版模型配置中。
## 完整更新内容
1. 新增 - 可视化模型参数配置，取代原配置文件配置模型。预设超过 100 个模型配置。同时支持所有类型模型的一键测试。（预计下个版本会完全支持在页面上配置渠道）。[点击查看模型配置方案](../../config/model/intro.mdx)
2. 新增 - DeepSeek resoner 模型支持输出思考过程。
3. 新增 - 使用记录导出和仪表盘。
4. 新增 - markdown 语法扩展，支持音视频（代码块 audio 和 video）。
5. 新增 - 调整 max\_tokens 计算逻辑。优先保证 max\_tokens 为配置值，如超出最大上下文，则减少历史记录。例如：如果申请 8000 的 max\_tokens，则上下文长度会减少 8000。
6. 优化 - 问题优化增加上下文过滤，避免超出上下文。
7. 优化 - 页面组件抽离，减少页面组件路由。
8. 优化 - 全文检索，忽略大小写。
9. 优化 - 问答生成和增强索引改成流输出，避免部分模型超时。
10. 优化 - 自动给 assistant 空 content，补充 null，同时合并连续的 text assistant，避免部分模型抛错。
11. 优化 - 调整图片 Host， 取消上传时补充 FE\_DOMAIN，改成发送对话前补充，避免替换域名后原图片无法正常使用。
12. 修复 - 部分场景成员列表无法触底加载。
13. 修复 - 工作流递归执行，部分条件下无法正常运行。
file: ./content/self-host/upgrading/outdated/4821.en.mdx
meta: {
"title": "V4.8.21",
"description": "FastGPT V4.8.21 Release Notes"
}
## Upgrade Guide
### 1. Back up your database
### 2. Update images:
* Update the fastgpt image tag to v4.8.21-fix
* Update the fastgpt-pro commercial edition image tag to v4.8.21-fix
* Sandbox image update is not required
## Full Release Notes
1. New - Deprecated/deleted plugin indicators.
2. New - Chat logs with source categorization, title search, and export.
3. New - Global variables support drag-and-drop reordering.
4. New - LLM models support `top_p`, `response_format`, and `json_schema` parameters.
5. New - Doubao 1.5 model preset. Alibaba Embedding v3 preset.
6. New - Vector models support normalization configuration to accommodate unnormalized vector models such as Doubao embedding models.
7. New - AI chat node supports outputting thinking process results, which can be referenced by other nodes.
8. Improved - Embedded chat widget with window position adaptation.
9. Improved - Better error messages when models are not configured.
10. Improved - Support for non-stream mode thinking output.
11. Improved - Added null pointer protection when TTS voice is not configured.
12. Improved - Markdown link parsing/splitting rules switched to strict matching mode, sacrificing compatibility for fewer false positives.
13. Improved - Reduced data fetching scope for unauthenticated users to improve system privacy.
14. Fixed - Simple Mode: switching to a non-vision model now correctly disables image recognition.
15. Fixed - o1/o3 models: field mapping not taking effect during testing, causing errors.
16. Fixed - WeChat Official Account chat null pointer exception.
17. Fixed - Multiple audio/video files displaying incorrectly.
18. Fixed - Share link authentication error causing infinite loop.
file: ./content/self-host/upgrading/outdated/4821.mdx
meta: {
"title": "V4.8.21",
"description": "FastGPT V4.8.21 更新说明"
}
## 更新指南
### 1. 做好数据库备份
### 2. 更新镜像：
* 更新 fastgpt 镜像 tag: v4.8.21-fix
* 更新 fastgpt-pro 商业版镜像 tag: v4.8.21-fix
* Sandbox 镜像无需更新
## 完整更新内容
1. 新增 - 弃用/已删除的插件提示。
2. 新增 - 对话日志按来源分类、标题检索、导出功能。
3. 新增 - 全局变量支持拖拽排序。
4. 新增 - LLM 模型支持 top\_p, response\_format, json\_schema 参数。
5. 新增 - Doubao1.5 模型预设。阿里 embedding3 预设。
6. 新增 - 向量模型支持归一化配置，以便适配未归一化的向量模型，例如 Doubao 的 embedding 模型。
7. 新增 - AI 对话节点，支持输出思考过程结果，可用于其他节点引用。
8. 优化 - 网站嵌入式聊天窗口，增加窗口位置适配。
9. 优化 - 模型未配置时错误提示。
10. 优化 - 适配非 Stream 模式思考输出。
11. 优化 - 增加 TTS voice 未配置时的空指针保护。
12. 优化 - Markdown 链接解析分割规则，改成严格匹配模式，牺牲兼容多种情况，减少误解析。
13. 优化 - 减少未登录用户的数据获取范围，提高系统隐私性。
14. 修复 - 简易模式，切换到其他非视觉模型时候，会强制关闭图片识别。
15. 修复 - o1,o3 模型，在测试时候字段映射未生效导致报错。
16. 修复 - 公众号对话空指针异常。
17. 修复 - 多个音频/视频文件展示异常。
18. 修复 - 分享链接鉴权报错后无限循环。
file: ./content/self-host/upgrading/outdated/4822.en.mdx
meta: {
"title": "V4.8.22 (Upgrade Script)",
"description": "FastGPT V4.8.22 Release Notes"
}
## Upgrade Guide
### 1. Back up your database
### 2. Update images:
* Update the fastgpt image tag to v4.8.22
* Update the fastgpt-pro commercial edition image tag to v4.8.22
* Sandbox image update is not required
### 3. Run migration script
Only required for commercial edition users providing SaaS services.
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4822' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
This migrates contact information to the corresponding user table.
## New Features
1. AI chat node parses `AI Proxy Yml Configuration
```
# AI Proxy
aiproxy:
image: 'ghcr.io/labring/aiproxy:latest'
container_name: aiproxy
restart: unless-stopped
depends_on:
aiproxy_pg:
condition: service_healthy
networks:
- fastgpt
environment:
# Corresponds to AIPROXY_API_TOKEN in FastGPT
- ADMIN_KEY=aiproxy
# Error log detail retention time (hours)
- LOG_DETAIL_STORAGE_HOURS=1
# Database connection URL
- SQL_DSN=postgres://postgres:aiproxy@aiproxy_pg:5432/aiproxy
# Maximum retry attempts
- RETRY_TIMES=3
# Billing not required
- BILLING_ENABLED=false
# Strict model validation not required
- DISABLE_MODEL_CONFIG=true
healthcheck:
test: ['CMD', 'curl', '-f', 'http://localhost:3000/api/status']
interval: 5s
timeout: 5s
retries: 10
aiproxy_pg:
image: pgvector/pgvector:0.8.0-pg15 # docker hub
# image: registry.cn-hangzhou.aliyuncs.com/fastgpt/pgvector:v0.8.0-pg15 # Alibaba Cloud
restart: unless-stopped
container_name: aiproxy_pg
volumes:
- ./aiproxy_pg:/var/lib/postgresql/data
networks:
- fastgpt
environment:
TZ: Asia/Shanghai
POSTGRES_USER: postgres
POSTGRES_DB: aiproxy
POSTGRES_PASSWORD: aiproxy
healthcheck:
test: ['CMD', 'pg_isready', '-U', 'postgres', '-d', 'aiproxy']
interval: 5s
timeout: 5s
retries: 10
```
#### 2. Add FastGPT Environment Variables:
Modify the environment variables for the FastGPT container in the yml file:
```
# AI Proxy address — takes priority if configured
- AIPROXY_API_ENDPOINT=http://aiproxy:3000
# AI Proxy Admin Token, must match the ADMIN_KEY env var in AI Proxy
- AIPROXY_API_TOKEN=aiproxy
```
#### 3. Restart Services
Run `docker-compose down` to stop services, then `docker-compose up -d` to start them. This will add the `aiproxy` service and update FastGPT's configuration.
#### 4. Run the OneAPI to AI Proxy Migration Script
* If the container has internet access:
```bash
# Enter the aiproxy container
docker exec -it aiproxy sh
# Install curl
apk add curl
# Run the migration script
curl --location --request POST 'http://localhost:3000/api/channels/import/oneapi' \
--header 'Authorization: Bearer aiproxy' \
--header 'Content-Type: application/json' \
--data-raw '{
"dsn": "mysql://root:oneapimmysql@tcp(mysql:3306)/oneapi"
}'
# A response of {"data":[],"success":true} indicates success
```
* If the container has no internet access, expose the `aiproxy` external port and run the script locally.
Expose the aiproxy port: 3003:3000, then run `docker-compose up -d` to restart services.
```bash
# Run the script from your terminal
curl --location --request POST 'http://localhost:3003/api/channels/import/oneapi' \
--header 'Authorization: Bearer aiproxy' \
--header 'Content-Type: application/json' \
--data-raw '{
"dsn": "mysql://root:oneapimmysql@tcp(mysql:3306)/oneapi"
}'
# A response of {"data":[],"success":true} indicates success
```
* If you're not familiar with Docker operations, skip the migration script and manually re-add channels after removing all OneAPI content.
#### 5. Verify AI Proxy is Running in FastGPT
Log in with the root account. On the `Account - Model Providers` page, you should see two new options: `Model Channels` and `Call Logs`. Open Model Channels to verify that your previous OneAPI channels are listed, confirming the migration was successful. You can then manually check that each channel is working properly.
#### 6. Remove the OneAPI Service
```bash
# Stop services, or selectively stop OneAPI and its MySQL
docker-compose down
# Remove OneAPI and its MySQL dependency from the yml file
# Restart services
docker-compose up -d
```
### 4. Run the FastGPT Upgrade Script
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv490' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
**Script Functions**
1. Upgrades the PG Vector extension version.
2. Updates all knowledge base collection fields.
3. Updates the index `type` field across all knowledge base data. (This takes a while — you may see a timeout at the end, which can be ignored. The process will continue incrementally as long as the database is running.)
## Compatibility & Deprecations
1. Deprecated — The previous custom file parsing solution for private deployments. Please update to the latest environment-variable configuration. [See Environment Variables](../../config/env.en.mdx)
2. Deprecated — The legacy local file upload API: `/api/core/dataset/collection/create/file` (previously available only in the Pro edition). This endpoint has been replaced by: `/api/core/dataset/collection/create/localFile`
3. Maintenance ending, deprecation upcoming — External file library APIs. Use the API File Library as a replacement.
4. API Update — For endpoints that include a `trainingType` field (file upload to knowledge base, link collection creation, API file library, push chunk data, etc.), `trainingType` will only support `chunk` and `QA` modes going forward. Enhanced indexing mode will use a separate field: `autoIndexes`. Legacy `trainingType=auto` code is still supported for now, but please migrate to the new API format as soon as possible. See: [Knowledge Base OpenAPI Documentation](../../../openapi/dataset.en.mdx)
## New Features
1. PDF enhanced parsing UI added to the page. Doc2x service is now built in, allowing direct PDF parsing via Doc2x.
2. Automatic image annotation, along with updated data logic and UI for knowledge base file uploads.
3. PG Vector extension upgraded to 0.8.0, introducing iterative search to reduce cases where data cannot be retrieved.
4. Added qwen-qwq series model configurations.
## Improvements
1. Knowledge base data no longer has a limit on the number of indexes — unlimited custom indexes are now supported. Input text indexes are automatically updated without affecting custom indexes.
2. Markdown parsing now detects Chinese punctuation after links and adds spacing.
3. Prompt-mode tool calls now support reasoning models, with improved format detection to reduce empty outputs.
4. Merged Mongo file read streams to reduce computation. Optimized storage chunks for significantly faster large file reads — 50MB PDF read time improved by 3x.
5. HTTP Body adaptation now supports string object types.
## Bug Fixes
1. Added security link validation for web scraping.
2. During batch runs, global variables were not passed to subsequent runs, causing incorrect final variable updates.
file: ./content/self-host/upgrading/outdated/490.mdx
meta: {
"title": "V4.9.0（环境变量变更、升级脚本）",
"description": "FastGPT V4.9.0 更新说明"
}
## 更新指南
### 1. 做好数据库备份
### 2. 更新镜像和 PG 容器
* 更新 FastGPT 镜像 tag: v4.9.0
* 更新 FastGPT 商业版镜像 tag: v4.9.0
* Sandbox 镜像，可以不更新
* 更新 PG 容器为 v0.8.0-pg15, 可以查看[最新的 yml](https://raw.githubusercontent.com/labring/FastGPT/main/document/public/deploy/docker/main/global/docker-compose.pg.yml)
### 3. 替换 OneAPI（可选）
如果需要使用 [AI Proxy](https://github.com/labring/aiproxy) 替换 OneAPI 的用户可执行该步骤。
#### 1. 修改 yml 文件
参考[最新的 yml](https://raw.githubusercontent.com/labring/FastGPT/main/document/public/deploy/docker/main/global/docker-compose.pg.yml) 文件。里面已移除 OneAPI 并添加了 AIProxy 配置。包含一个服务和一个 PgSQL 数据库。将 `aiproxy` 的配置 `追加` 到 OneAPI 的配置后面（先不要删除 OneAPI，有一个初始化会自动同步 OneAPI 的配置）
AI Proxy Yml 配置
```
# AI Proxy
aiproxy:
image: 'ghcr.io/labring/aiproxy:latest'
container_name: aiproxy
restart: unless-stopped
depends_on:
aiproxy_pg:
condition: service_healthy
networks:
- fastgpt
environment:
# 对应 fastgpt 里的AIPROXY_API_TOKEN
- ADMIN_KEY=aiproxy
# 错误日志详情保存时间（小时）
- LOG_DETAIL_STORAGE_HOURS=1
# 数据库连接地址
- SQL_DSN=postgres://postgres:aiproxy@aiproxy_pg:5432/aiproxy
# 最大重试次数
- RETRY_TIMES=3
# 不需要计费
- BILLING_ENABLED=false
# 不需要严格检测模型
- DISABLE_MODEL_CONFIG=true
healthcheck:
test: ['CMD', 'curl', '-f', 'http://localhost:3000/api/status']
interval: 5s
timeout: 5s
retries: 10
aiproxy_pg:
image: pgvector/pgvector:0.8.0-pg15 # docker hub
# image: registry.cn-hangzhou.aliyuncs.com/fastgpt/pgvector:v0.8.0-pg15 # 阿里云
restart: unless-stopped
container_name: aiproxy_pg
volumes:
- ./aiproxy_pg:/var/lib/postgresql/data
networks:
- fastgpt
environment:
TZ: Asia/Shanghai
POSTGRES_USER: postgres
POSTGRES_DB: aiproxy
POSTGRES_PASSWORD: aiproxy
healthcheck:
test: ['CMD', 'pg_isready', '-U', 'postgres', '-d', 'aiproxy']
interval: 5s
timeout: 5s
retries: 10
```
#### 2. 增加 FastGPT 环境变量：
修改 yml 文件中，fastgpt 容器的环境变量：
```
# AI Proxy 的地址，如果配了该地址，优先使用
- AIPROXY_API_ENDPOINT=http://aiproxy:3000
# AI Proxy 的 Admin Token，与 AI Proxy 中的环境变量 ADMIN_KEY
- AIPROXY_API_TOKEN=aiproxy
```
#### 3. 重载服务
`docker-compose down` 停止服务，然后 `docker-compose up -d` 启动服务，此时会追加 `aiproxy` 服务，并修改 FastGPT 的配置。
#### 4. 执行 OneAPI 迁移 AI proxy 脚本
* 可联网方案:
```bash
# 进入 aiproxy 容器
docker exec -it aiproxy sh
# 安装 curl
apk add curl
# 执行脚本
curl --location --request POST 'http://localhost:3000/api/channels/import/oneapi' \
--header 'Authorization: Bearer aiproxy' \
--header 'Content-Type: application/json' \
--data-raw '{
"dsn": "mysql://root:oneapimmysql@tcp(mysql:3306)/oneapi"
}'
# 返回 {"data":[],"success":true} 代表成功
```
* 无法联网时，可打开 `aiproxy` 的外网暴露端口，然后在本地执行脚本。
aiProxy 暴露端口：3003:3000，修改后重新 `docker-compose up -d` 启动服务。
```bash
# 在终端执行脚本
curl --location --request POST 'http://localhost:3003/api/channels/import/oneapi' \
--header 'Authorization: Bearer aiproxy' \
--header 'Content-Type: application/json' \
--data-raw '{
"dsn": "mysql://root:oneapimmysql@tcp(mysql:3306)/oneapi"
}'
# 返回 {"data":[],"success":true} 代表成功
```
* 如果不熟悉 docker 操作，建议不要走脚本迁移，直接删除 OneAPI 所有内容，然后手动重新添加渠道。
#### 5. 进入 FastGPT 检查 `AI Proxy` 服务是否正常启动。
登录 root 账号后，在 `账号-模型提供商` 页面，可以看到多出了 `模型渠道` 和 `调用日志` 两个选项，打开模型渠道，可以看到之前 OneAPI 的渠道，说明迁移完成，此时可以手动再检查下渠道是否正常。
#### 6. 删除 OneAPI 服务
```bash
# 停止服务，或者针对性停止 OneAPI 和其 Mysql
docker-compose down
# yml 文件中删除 OneAPI 和其 Mysql 依赖
# 重启服务
docker-compose up -d
```
### 4. 运行 FastGPT 升级脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成 **FastGPT 域名**。
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv490' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
**脚本功能**
1. 升级 PG Vector 插件版本
2. 全量更新知识库集合字段。
3. 全量更新知识库数据中，index 的 type 类型。（时间较长，最后可能提示 timeout，可忽略，数据库不崩都会一直增量执行）
## 兼容 & 弃用
1. 弃用 - 之前私有化部署的自定义文件解析方案，请同步更新到最新的环境变量配置方案。[点击查看环境变量说明](../../config/env.mdx)
2. 弃用 - 弃用旧版本地文件上传 API：/api/core/dataset/collection/create/file（以前仅商业版可用的 API，该接口已放切换成：/api/core/dataset/collection/create/localFile）
3. 停止维护，即将弃用 - 外部文件库相关 API，可通过 API 文件库替代。
4. API 更新 - 上传文件至知识库、创建连接集合、API 文件库、推送分块数据等带有 `trainingType` 字段的接口，`trainingType` 字段未来仅支持 `chunk` 和 `QA` 两种模式。增强索引模式将设置单独字段：`autoIndexes`，目前仍有适配旧版 `trainingType=auto` 代码，但请尽快变更成新接口类型。具体可见：[知识库 OpenAPI 文档](../../../openapi/dataset.mdx)
## 🚀 新增内容
1. PDF 增强解析交互添加到页面上。同时内嵌 Doc2x 服务，可直接使用 Doc2x 服务解析 PDF 文件。
2. 图片自动标注，同时修改知识库文件上传部分数据逻辑和交互。
3. pg vector 插件升级 0.8.0 版本，引入迭代搜索，减少部分数据无法被检索的情况。
4. 新增 qwen-qwq 系列模型配置。
## ⚙️ 优化
1. 知识库数据不再限制索引数量，可无限自定义。同时可自动更新输入文本的索引，不影响自定义索引。
2. Markdown 解析，增加链接后中文标点符号检测，增加空格。
3. Prompt 模式工具调用，支持思考模型。同时优化其格式检测，减少空输出的概率。
4. Mongo 文件读取流合并，减少计算量。同时优化存储 chunks，极大提高大文件读取速度。50M PDF 读取时间提高 3 倍。
5. HTTP Body 适配，增加对字符串对象的适配。
## 🐛 修复
1. 增加网页抓取安全链接校验。
2. 批量运行时，全局变量未进一步传递到下一次运行中，导致最终变量更新错误。
file: ./content/self-host/upgrading/outdated/491.en.mdx
meta: {
"title": "V4.9.1 (Upgrade Script)",
"description": "FastGPT V4.9.1 Release Notes"
}
## Upgrade Guide
### 1. Back Up Your Database
### 2. Update Images
* Update FastGPT image tag: v4.9.1-fix2
* Update FastGPT Pro image tag: v4.9.1-fix2
* Sandbox image: no update required
* AIProxy image changed to: registry.cn-hangzhou.aliyuncs.com/labring/aiproxy:v0.1.3
### 3. Run the Upgrade Script
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv491' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
**Script Functions**
Re-processes tokenization using the latest jieba dictionary. This takes a while — you can monitor progress in the logs.
## New Features
1. Pro edition supports single-team mode for better internal member management.
2. Knowledge base chunk reader.
3. API knowledge base supports PDF enhanced parsing.
4. Team member invitations now use an invite link model.
5. Hybrid search weight configuration support.
6. Rerank model selection and weight configuration support. The knowledge base search weight calculation has been adjusted from `vector search weight + full-text search weight + rerank weight` to `search weight + rerank weight`. This may affect search results — you can adjust the relevant weights to adapt your data.
## Improvements
1. Knowledge base data input UI improvements.
2. App-bound knowledge base data fetching moved to backend processing.
3. Added dependency package security version checks and upgraded some dependencies.
4. Model testing code improvements.
5. Optimized reasoning output parsing: as long as a model is configured to support reasoning, `` tags will always be parsed, even when reasoning is disabled during a conversation.
6. Loaded the latest jieba dictionary for improved full-text search tokenization.
## Bug Fixes
1. Max response tokens tooltip showing incorrect values.
2. HTTP Node failing to parse strings containing newline characters.
3. Knowledge base question optimization not passing conversation history.
4. Missing error message translations.
5. Content extraction node: incorrect schema for array types.
6. Model channel testing not actually targeting the specified channel.
7. Adding a custom model would also save default model fields, causing incorrect default model detection.
8. Prompt-mode tool calls not null-checking the reasoning chain, causing UI rendering errors.
9. Editing app info causing avatar loss.
10. Share link titles being reset on refresh.
11. Authentication failure when calculating parentPath, causing it to be cleared.
file: ./content/self-host/upgrading/outdated/491.mdx
meta: {
"title": "V4.9.1（升级脚本）",
"description": "FastGPT V4.9.1 更新说明"
}
## 更新指南
### 1. 做好数据库备份
### 2. 更新镜像
* 更新 FastGPT 镜像 tag: v4.9.1-fix2
* 更新 FastGPT 商业版镜像 tag: v4.9.1-fix2
* Sandbox 镜像，可以不更新
* AIProxy 镜像修改为: registry.cn-hangzhou.aliyuncs.com/labring/aiproxy:v0.1.3
### 3. 执行升级脚本
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**。
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv491' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
**脚本功能**
重新使用最新的 jieba 分词库进行分词处理。时间较长，可以从日志里查看进度。
## 🚀 新增内容
1. 商业版支持单团队模式，更好的管理内部成员。
2. 知识库分块阅读器。
3. API 知识库支持 PDF 增强解析。
4. 邀请团队成员，改为邀请链接模式。
5. 支持混合检索权重设置。
6. 支持重排模型选择和权重设置，同时调整了知识库搜索权重计算方式，改成 搜索权重 + 重排权重，而不是向量检索权重+全文检索权重+重排权重。会对检索结果有一定影响，可以通过调整相关权重来进行数据适配。
## ⚙️ 优化
1. 知识库数据输入框交互
2. 应用拉取绑定知识库数据交由后端处理。
3. 增加依赖包安全版本检测，并升级部分依赖包。
4. 模型测试代码。
5. 优化思考过程解析逻辑：只要配置了模型支持思考，均会解析 `` 标签，不会因为对话时，关闭思考而不解析。
6. 载入最新 jieba 分词库，增强全文检索分词效果。
## 🐛 修复
1. 最大响应 tokens 提示显示错误的问题。
2. HTTP Node 中，字符串包含换行符时，会解析失败。
3. 知识库问题优化中，未传递历史记录。
4. 错误提示翻译缺失。
5. 内容提取节点，array 类型 schema 错误。
6. 模型渠道测试时，实际未指定渠道测试。
7. 新增自定义模型时，会把默认模型字段也保存，导致默认模型误判。
8. 修复 promp 模式工具调用，未判空思考链，导致 UI 错误展示。
9. 编辑应用信息导致头像丢失。
10. 分享链接标题会被刷新掉。
11. 计算 parentPath 时，存在鉴权失败清空。
file: ./content/self-host/upgrading/outdated/4910.en.mdx
meta: {
"title": "V4.9.10",
"description": "FastGPT V4.9.10 Release Notes"
}
## Upgrade Guide
Important: This update rebuilds the full-text index. During the rebuild, full-text search results will be empty. On a 4c16g instance, rebuilding approximately 7 million full-text indexes takes about 25 minutes. For a seamless upgrade, you'll need to handle table synchronization yourself.
### 1. Back Up Your Data
### 2. Update Image Tags
* Update FastGPT image tag: v4.9.10-fix2
* Update FastGPT Pro image tag: v4.9.10-fix2
* mcp\_server: no update required
* Sandbox: no update required
* AIProxy: no update required
## New Features
1. Support for setting the `systemEnv.hnswMaxScanTuples` parameter in PG to increase the total data volume for iterative search.
2. Knowledge base preprocessing now includes a "Chunk Conditions" parameter to control when chunking should be skipped.
3. Knowledge base preprocessing now includes a "Paragraph Priority" mode with configurable maximum paragraph depth. The previous "Length Priority" mode no longer includes embedded paragraph priority logic.
4. Workflow adjusted to single-direction input/output connections, with quick "add next node" support.
5. Lark and Yuque knowledge bases are now available in the Community Edition.
6. Latest Gemini and Claude model presets.
## Improvements
1. Increased default timeout for LLM stream calls.
2. Various confirmation dialog UI improvements.
3. Renamed the knowledge base "Table Dataset" to "Backup Import". Also added support for exporting and importing knowledge base indexes.
4. Knowledge base citation limit in workflows: if no related AI nodes exist in the workflow, the interaction mode switches to manual input only, with a limit of 10 million.
5. Mobile voice input now accurately detects whether the device is a phone rather than just a small screen.
6. Optimized context truncation algorithm to always preserve at least one Human message.
## Bug Fixes
1. Incorrect score sorting during full-text search across multiple knowledge bases.
2. Stream response potentially capturing incorrect `finish_reason` values.
3. Tool call mode not saving reasoning output.
4. Knowledge base `indexSize` parameter not taking effect.
5. Incorrect preview citations and context after 2 levels of workflow nesting.
6. Extra leading space when converting xlsx to Markdown.
7. Base64 images in Markdown files not being extracted and saved during file reading.
file: ./content/self-host/upgrading/outdated/4910.mdx
meta: {
"title": "V4.9.10",
"description": "FastGPT V4.9.10 更新说明"
}
## 升级指南
重要提示：本次更新会重新构建全文索引，构建期间，全文检索结果会为空，4c16g 700 万组全文索引大致消耗 25 分钟。如需无缝升级，需自行做表同步工程。
### 1. 做好数据备份
### 2. 更新镜像 tag
* 更新 FastGPT 镜像 tag: v4.9.10-fix2
* 更新 FastGPT 商业版镜像 tag: v4.9.10-fix2
* mcp\_server 无需更新
* Sandbox 无需更新
* AIProxy 无需更新
## 🚀 新增内容
1. 支持 PG 设置`systemEnv.hnswMaxScanTuples`参数，提高迭代搜索的数据总量。
2. 知识库预处理参数增加 “分块条件”，可控制某些情况下不进行分块处理。
3. 知识库预处理参数增加 “段落优先” 模式，可控制最大段落深度。原“长度优先”模式，不再内嵌段落优先逻辑。
4. 工作流调整为单向接入和接出，支持快速的添加下一步节点。
5. 开放飞书和语雀知识库到社区版。
6. gemini 和 claude 最新模型预设。
## ⚙️ 优化
1. LLM stream调用，默认超时调大。
2. 部分确认交互优化。
3. 纠正原先知识库的“表格数据集”名称，改成“备份导入”。同时支持知识库索引的导出和导入。
4. 工作流知识库引用上限，如果工作流中没有相关 AI 节点，则交互模式改成纯手动输入，并且上限为 1000万。
5. 语音输入，移动端判断逻辑，准确判断是否为手机，而不是小屏。
6. 优化上下文截取算法，至少保证留下一组 Human 信息。
## 🐛 修复
1. 全文检索多知识库时排序得分排序不正确。
2. 流响应捕获 finish\_reason 可能不正确。
3. 工具调用模式，未保存思考输出。
4. 知识库 indexSize 参数未生效。
5. 工作流嵌套 2 层后，获取预览引用、上下文不正确。
6. xlsx 转成 Markdown 时候，前面会多出一个空格。
7. 读取 Markdown 文件时，Base64 图片未进行额外抓换保存。
file: ./content/self-host/upgrading/outdated/4911.en.mdx
meta: {
"title": "V4.9.11 (Upgrade Script)",
"description": "FastGPT V4.9.11 Release Notes"
}
## Upgrade Guide
### 1. Update Images:
* Update FastGPT image tag: v4.9.11
* Update FastGPT Pro image tag: v4.9.11
* mcp\_server: no update required
* Update Sandbox image tag: v4.9.11
* AIProxy: no update required
### 2. Run the Upgrade Script
This script only needs to be run by Pro edition users.
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**.
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4911' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
**Script Functions**
1. Migrates third-party knowledge base API configurations.
## New Features
1. Pro edition supports image knowledge bases.
2. Added node search functionality in the workflow editor.
3. Sub-workflow version control in workflows now supports a "Keep Latest Version" option — no manual updates needed.
4. Additional audit operation logs.
5. Knowledge base now has an async document parsing queue — documents can be imported without waiting for parsing to complete.
6. Third-party knowledge base development documentation. [View here](../../../guide/dataset/third-party/third_dataset.en.mdx)
## Improvements
1. Raw text cache now uses GridFS storage for higher capacity.
2. Added knowledge base template import option.
## Bug Fixes
1. Admin-declared global system tools in workflows unable to be version-managed.
2. Context errors when an interactive node precedes a tool call node.
3. Backup import failing to chunk content under 1,000 characters.
4. Custom PDF parsing unable to save Base64 images.
5. Non-stream requests not performing CITE marker replacement.
6. Hidden security vulnerability in the Python sandbox.
7. Missing confirm button when importing plugins via curl.
file: ./content/self-host/upgrading/outdated/4911.mdx
meta: {
"title": "V4.9.11（升级脚本）",
"description": "FastGPT V4.9.11 更新说明"
}
## 更新指南
### 1. 更新镜像：
* 更新 FastGPT 镜像 tag: v4.9.11
* 更新 FastGPT 商业版镜像 tag: v4.9.11
* mcp\_server 无需更新
* 更新 Sandbox 镜像 tag: v4.9.11
* AIProxy 无需更新
### 2. 执行升级脚本
该脚本仅需商业版用户执行。
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**。
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv4911' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
**脚本功能**
1. 移动第三方知识库 API 配置。
## 🚀 新增内容
1. 商业版支持图片知识库。
2. 工作流中增加节点搜索功能。
3. 工作流中，子流程版本控制，可选择“保持最新版本”，无需手动更新。
4. 增加更多审计操作日志。
5. 知识库增加文档解析异步队列，导入文档时，无需等待文档解析完毕才进行导入。
6. 第三方知识库开发文档, [点击查看](../../../guide/dataset/third-party/third_dataset.mdx)
## ⚙️ 优化
1. 原文缓存改用 gridfs 存储，提高上限。
2. 增加知识库模板导入选项。
## 🐛 修复
1. 工作流中，管理员声明的全局系统工具，无法进行版本管理。
2. 工具调用节点前，有交互节点时，上下文异常。
3. 修复备份导入，小于 1000 字时，无法分块问题。
4. 自定义 PDF 解析，无法保存 base64 图片。
5. 非流请求，未进行 CITE 标记替换。
6. Python 沙盒存在隐藏风险。
7. curl 导入插件缺失确认按键
file: ./content/self-host/upgrading/outdated/4912.en.mdx
meta: {
"title": "V4.9.12 (Environment Changes)",
"description": "FastGPT V4.9.12 Release Notes"
}
## Upgrade Guide
### 1. Update Environment Variables
Add the following environment variable to both the `fastgpt` and `fastgpt-pro` image configurations: `AES256_SECRET_KEY=` — used for secret key encryption.
### 2. Update Images:
* Update FastGPT image tag: v4.9.12
* Update FastGPT Pro image tag: v4.9.12
* mcp\_server: no update required
* Sandbox: no update required
* Update AIProxy image tag: v0.2.2
## New Features
1. Enhanced AI Proxy monitoring with chart and table views for model call and performance metrics.
2. HTTP nodes and MCP now support separate "Auth Configuration" — plaintext credentials are never sent back to the client, ensuring data security.
3. Question classification and content extraction now automatically include the previous round's results in the prompt for additional guidance.
4. Conditional node now supports variable references.
5. Pro edition supports LLM-based automatic segment detection during knowledge base chunking.
6. Admin dashboard with data analytics.
7. Doubao 1.6 series models and updated Qwen model configurations.
## Improvements
1. Password validation now accepts more special characters.
2. Backend now fully computes knowledge base chunk parameters to prevent default values from being incorrectly applied in auto mode.
3. Text chunking moved to a worker thread to avoid blocking.
4. More subscription plan usage information displayed.
5. Input box styling improvements, with updated voice input UI for both desktop and mobile.
6. MCP tool calls now use raw schema for invocation to ensure completeness.
7. Deleting knowledge base files no longer fails if the file doesn't exist.
8. Upgraded MCP SDK with compatibility for the latest HTTP Streamable protocol.
9. Yuque document library now recursively fetches data from document-type directories.
## Bug Fixes
1. Custom QA extraction prompts being overwritten.
2. Template import failing when empty indexes exist in the data.
3. Potential XSS vulnerability on the login page.
4. Voice input in the text box causing the file list to be lost.
5. Image TTL field not being cleared in knowledge base documents, causing images to expire.
6. MCP tool storage not escaping integer type data.
file: ./content/self-host/upgrading/outdated/4912.mdx
meta: {
"title": "V4.9.12（环境变量变更）",
"description": "FastGPT V4.9.12 更新说明"
}
## 更新指南
### 1. 更新环境变量
在 `fastgpt`和`fastgpt-pro`镜像环境变量中加入: `AES256_SECRET_KEY=` 变量，用于密钥加密。
### 2. 更新镜像：
* 更新 FastGPT 镜像 tag: v4.9.12
* 更新 FastGPT 商业版镜像 tag: v4.9.12
* mcp\_server 无需更新
* Sandbox 无需更新
* 更新 AIProxy 镜像 tag: v0.2.2
## 🚀 新增内容
1. AI proxy 监控完善，支持以图表/表格形式查看模型调用和性能情况。
2. HTTP 节点和 MCP 支持单独“鉴权配置”，鉴权配置明文不会二次返回客户端，以保障数据安全。
3. 问题分类和内容提取，提示词中自动加入上一轮结果进行额外引导。
4. 判断器支持变量引用。
5. 商业版支持知识库分块时，LLM 进行自动分段识别。
6. Admin 管理员数据看板。
7. 豆包 1.6 系列模型，更新 qwen 模型配置。
## ⚙️ 优化
1. 密码校验时，增加更多的特殊字符
2. 后端全量计算知识库 chunk 参数，避免自动模式下部分参数未正确使用默认值。
3. 将文本分块移至 worker 线程，避免阻塞。
4. 展示更多套餐用量信息。
5. 优化输入框样式，桌面和移动端的语音输入样式更新。
6. MCP 工具调用，使用 Raw schema 进行工具调用，保障完整性。
7. 删除知识库文件时，如果文件不存在，不会阻断删除。
8. 升级 MCP SDK，兼容最新的 HTTPStreamable。
9. 语雀文档库，递归获取文档类型目录下的数据。
## 🐛 修复
1. 自定义问答提取提示词被覆盖。
2. 模板导入时，存在空 indexes 时，导致数据插入失败。
3. 登录页可能存在的 XSS 攻击。
4. 输入框语音输入时候会丢失文件列表的问题。
5. 知识库文档中图片 TTL 字段未清除，导致图片过期。
6. MCP 工具存储时，未转义 int 类型数据。
file: ./content/self-host/upgrading/outdated/4913.en.mdx
meta: {
"title": "V4.9.13",
"description": "FastGPT V4.9.13 Release Notes"
}
## Upgrade Guide
### 1. Update Images:
* Update FastGPT image tag: v4.9.13
* Update FastGPT Pro image tag: v4.9.13
* mcp\_server: no update required
* Sandbox: no update required
* AIProxy: no update required
## New Features
1. Subscription plan caching to reduce MongoDB query frequency.
## Improvements
1. All NodeId random value generation adjusted to avoid starting with a digit.
2. Knowledge base collection search now supports nested search.
## Bug Fixes
1. Chat log date range selection issues.
2. System prompt potentially being duplicated when passed via API calls.
3. AI chat/tool calls reading files from history even when no file link was selected.
4. Manually updating knowledge base indexes incorrectly deleting old indexes, causing manual indexes to become ineffective.
file: ./content/self-host/upgrading/outdated/4913.mdx
meta: {
"title": "V4.9.13",
"description": "FastGPT V4.9.13 更新说明"
}
## 更新指南
### 1. 更新镜像：
* 更新 FastGPT 镜像 tag: v4.9.13
* 更新 FastGPT 商业版镜像 tag: v4.9.13
* mcp\_server 无需更新
* Sandbox 无需更新
* AIProxy 无需更新
## 🚀 新增内容
1. 套餐缓存，减少 MongoDB 查询次数。
## ⚙️ 优化
1. 所有 NodeId 调整随机值生成，避免首字母数字开头。
2. 知识库集合搜索，支持嵌套搜索。
## 🐛 修复
1. 对话日志，日期范围选择问题。
2. API 调用时，传入的 system 提示词可能会重复。
3. AI 对话/工具调用，未选择文件链接时，也会从历史记录读取文件。
4. 手动更新知识库索引时，错误的删除旧索引，导致手动索引无效。
file: ./content/self-host/upgrading/outdated/4914.en.mdx
meta: {
"title": "V4.9.14",
"description": "FastGPT V4.9.14 Release Notes"
}
## Upgrade Guide
### 1. Update Images:
* Update FastGPT image tag: v4.9.14
* Update FastGPT Pro image tag: v4.9.14
* mcp\_server: no update required
* Sandbox: no update required
* AIProxy: no update required
## New Features
1. Knowledge base import now supports automatically adding the filename to the system index.
2. Admin-side audit logs.
## Improvements
1. Unified knowledge base training queue code logic.
2. Input box UX improvements.
3. Image knowledge base now automatically removes line breaks from descriptions to prevent model output line breaks from breaking image display.
4. Image indexing now generates separate image content descriptions, and attaches them to search results after retrieval — enabling LLMs to understand image content.
5. Auto-completion for MCP Schema entries missing the `properties` field to prevent errors with certain models.
6. Error handling for potential JSON import template failures.
7. Dangerous characters filtered during CSV export.
8. Added security request headers.
9. Changing password now invalidates all other active sessions.
10. Citation display optimization: detects preceding URLs and automatically adds spacing.
## Bug Fixes
1. Knowledge base data input incorrectly detecting QA mode.
2. Knowledge base tag condition conflicts.
3. Chat log like/dislike statistics.
file: ./content/self-host/upgrading/outdated/4914.mdx
meta: {
"title": "V4.9.14",
"description": "FastGPT V4.9.14 更新说明"
}
## 更新指南
### 1. 更新镜像：
* 更新 FastGPT 镜像 tag: v4.9.14
* 更新 FastGPT 商业版镜像 tag: v4.9.14
* mcp\_server 无需更新
* Sandbox 无需更新
* AIProxy 无需更新
## 🚀 新增内容
1. 知识库导入，支持配置：自动将文件名加入系统索引中。
2. Admin 端审计日志。
## ⚙️ 优化
1. 统一知识库训练队列代码逻辑。
2. 输入框 UX。
3. 图片知识库自动去除介绍中的换行，避免模型输出换行导致无法显示图片。
4. 图片索引过程会单独描述图片内容，并在检索后会将图片描述赋予检索结果，使语言模型也可以对图片进行理解。
5. 对于 MCP Schema 中，缺少`properties`属性的值，进行自动补全，避免部分模型报错。
6. 对 JSON 导入模板可能的报错进行捕获。
7. 过滤 CSV 导出时可能存在的危险字符串。
8. 添加安全请求头。
9. 修改密码，强制其他登录端失效。
10. Cite 引用展示优化，识别前置的 url 并自动加空格。
## 🐛 修复
1. 知识库数据输入，识别 QA 模式错误。
2. 知识库标签条件冲突。
3. 对话日志点赞点踩统计。
file: ./content/self-host/upgrading/outdated/492.en.mdx
meta: {
"title": "V4.9.2 (Environment Changes)",
"description": "FastGPT V4.9.2 Release Notes"
}
## Upgrade Guide
You can skip directly to v4.9.3 — v4.9.2 has a workflow data type conversion bug.
### 1. Back Up Your Database
### 2. SSO Migration
Pro edition users using SSO or member sync with DingTalk or WeCom need to migrate their existing SSO configuration:
Refer to [SSO & External Member Sync](../../../guide/admin/sso.en.mdx) for deploying and configuring the `sso-service`.
1. Before upgrading images, copy and back up the existing configuration from the Pro admin panel (e.g., for WeCom, copy the AppId, Secret, etc.).
2. Follow the documentation above to deploy the SSO service and configure the relevant environment variables.
3. If you were previously using WeCom org structure sync, after upgrading, switch the team mode to "Sync Mode" in the Pro admin panel.
### 3. Configuration Parameter Changes
Rename the `systemEnv.pgHNSWEfSearch` parameter in your `config.json` file to `hnswEfSearch`.
Pro edition users can make this change in the admin panel under `System Configuration - Basic Settings` after upgrading.
### 4. Update Images
* Update FastGPT image tag: v4.9.2
* Update FastGPT Pro image tag: v4.9.2
* Sandbox image: no update required
* AIProxy image changed to: registry.cn-hangzhou.aliyuncs.com/labring/aiproxy:v0.1.4
## Important Updates
* Knowledge base data import API changes: added optional parameters `chunkSettingMode`, `chunkSplitMode`, and `indexSize`. See the [Knowledge Base Data Import API](../../../openapi/dataset.en.mdx) documentation for details.
## New Features
1. Knowledge base chunking optimization: supports separate configuration for chunk size and index size, allowing extra-large chunks that trade higher input tokens for complete chunks.
2. Knowledge base chunking now includes custom separator presets and supports custom newline-based splitting.
3. External variables renamed to Custom Variables. Now supports debugging during testing, and the variable is hidden in share links.
4. Collection sync now supports syncing title changes.
5. Team member management overhaul: extracted mainstream IM SSO (WeCom, Lark, DingTalk) and added support for connecting to FastGPT via custom SSO. Also improved member sync with external systems.
6. Support for `oceanbase` vector database. Set the `OCEANBASE_URL` environment variable to enable.
7. PDF parsing example based on mistral-ocr.
8. PDF parsing example based on miner-u.
## Improvements
1. Chat log export now includes member names.
2. Invite link UI improvements.
3. When SSL certificate is unavailable and copy fails, a dialog is shown for manual copying.
4. FastGPT now properly displays AI Proxy channel names even when channels are not built in.
5. Upgraded Next.js to version 14.2.25.
6. Workflow node array-string type now auto-adapts to string input.
7. Workflow node array type now automatically JSON-parses string input.
8. AI Proxy log optimization: removed retry failure logs, keeping only the final error log.
9. Personal info and notification display improvements.
10. Model testing loading animation improvements.
11. Minor chunking algorithm adjustments:
* Stronger continuity between cross-processing symbols.
* Code blocks now use the LLM model context as chunk size to better preserve code block integrity.
* Tables now use the LLM model context as chunk size to better preserve table integrity.
## Bug Fixes
1. Lark and Yuque knowledge bases unable to sync.
2. Channel testing using the custom request URL instead of the channel request URL when a custom URL was configured.
3. Speech recognition model testing unable to test disabled models.
4. Admin-configured system plugins failing authentication when the plugin contains other system apps.
5. Removing TTS custom request URL requiring the requestAuth field to be filled.
file: ./content/self-host/upgrading/outdated/492.mdx
meta: {
"title": "V4.9.2（环境变量变更）",
"description": "FastGPT V4.9.2 更新说明"
}
## 更新指南
可直接升级v4.9.3，v4.9.2存在一个工作流数据类型转化错误。
### 1. 做好数据库备份
### 2. SSO 迁移
使用了 SSO 或成员同步的商业版用户，并且是对接`钉钉`、`企微`的，需要迁移已有的 SSO 相关配置:
参考：[SSO & 外部成员同步](../../../guide/admin/sso.mdx)中的配置进行`sso-service`的部署和配置。
1. 先将原商业版后台中的相关配置项复制备份出来（以企微为例，将 AppId, Secret 等复制出来）再进行镜像升级。
2. 参考上述文档，部署 SSO 服务，配置相关的环境变量
3. 如果原先使用企微组织架构同步的用户，升级完镜像后，需要在商业版后台切换团队模式为“同步模式”
### 3. 配置参数变更
修改`config.json`文件中`systemEnv.pgHNSWEfSearch`参数名，改成`hnswEfSearch`。\
商业版用户升级镜像后，直接在后台`系统配置-基础配置`中进行变更。
### 4. 更新镜像
* 更新 FastGPT 镜像 tag: v4.9.2
* 更新 FastGPT 商业版镜像 tag: v4.9.2
* Sandbox 镜像，可以不更新
* AIProxy 镜像修改为: registry.cn-hangzhou.aliyuncs.com/labring/aiproxy:v0.1.4
## 重要更新
* 知识库导入数据 API 变更，增加`chunkSettingMode`,`chunkSplitMode`,`indexSize`可选参数，具体可参考 [知识库导入数据 API](../../../openapi/dataset.mdx) 文档。
## 🚀 新增内容
1. 知识库分块优化：支持单独配置分块大小和索引大小，允许进行超大分块，以更大的输入 Tokens 换取完整分块。
2. 知识库分块增加自定义分隔符预设值，同时支持自定义换行符分割。
3. 外部变量改名：自定义变量。 并且支持在测试时调试，在分享链接中，该变量直接隐藏。
4. 集合同步时，支持同步修改标题。
5. 团队成员管理重构，抽离主流 IM SSO（企微、飞书、钉钉），并支持通过自定义 SSO 接入 FastGPT。同时完善与外部系统的成员同步。
6. 支持 `oceanbase` 向量数据库。填写环境变量`OCEANBASE_URL`即可。
7. 基于 mistral-ocr 的 PDF 解析示例。
8. 基于 miner-u 的 PDF 解析示例。
## ⚙️ 优化
1. 导出对话日志时，支持导出成员名。
2. 邀请链接交互。
3. 无 SSL 证书时复制失败，会提示弹窗用于手动复制。
4. FastGPT 未内置 ai proxy 渠道时，也能正常展示其名称。
5. 升级 nextjs 版本至 14.2.25。
6. 工作流节点数组字符串类型，自动适配 string 输入。
7. 工作流节点数组类型，自动进行 JSON parse 解析 string 输入。
8. AI proxy 日志优化，去除重试失败的日志，仅保留最后一份错误日志。
9. 个人信息和通知展示优化。
10. 模型测试 loading 动画优化。
11. 分块算法小调整：
* 跨处理符号之间连续性更强。
* 代码块分割时，用 LLM 模型上下文作为分块大小，尽可能保证代码块完整性。
* 表格分割时，用 LLM 模型上下文作为分块大小，尽可能保证表格完整性。
## 🐛 修复
1. 飞书和语雀知识库无法同步。
2. 渠道测试时，如果配置了模型自定义请求地址，会走自定义请求地址，而不是渠道请求地址。
3. 语音识别模型测试未启用的模型时，无法正常测试。
4. 管理员配置系统插件时，如果插件包含其他系统应用，无法正常鉴权。
5. 移除 TTS 自定义请求地址时，必须需要填 requestAuth 字段。
file: ./content/self-host/upgrading/outdated/493.en.mdx
meta: {
"title": "V4.9.3",
"description": "FastGPT V4.9.3 Release Notes"
}
## Upgrade Guide
### 1. Back Up Your Database
### 2. Update Images
* Update FastGPT image tag: v4.9.3
* Update FastGPT Pro image tag: v4.9.3
* Sandbox image tag: v4.9.3
* AIProxy image tag: v0.1.5
## New Features
1. Workflow debug mode now supports interactive nodes.
2. Code execution now supports Python 3.
## Bug Fixes
1. Workflow format conversion errors.
file: ./content/self-host/upgrading/outdated/493.mdx
meta: {
"title": "V4.9.3",
"description": "FastGPT V4.9.3 更新说明"
}
## 更新指南
### 1. 做好数据库备份
### 2. 更新镜像
* 更新 FastGPT 镜像 tag: v4.9.3
* 更新 FastGPT 商业版镜像 tag: v4.9.3
* Sandbox 镜像tag: v4.9.3
* AIProxy 镜像tag: v0.1.5
## 🚀 新增内容
1. 工作流 debug 模式支持交互节点。
2. 代码运行支持 Python3 代码。
## 🐛 修复
1. 工作流格式转化异常。
file: ./content/self-host/upgrading/outdated/494.en.mdx
meta: {
"title": "V4.9.4 (Environment Changes, Upgrade Script)",
"description": "FastGPT V4.9.4 Release Notes"
}
## Upgrade Guide
### 1. Back Up Your Data
### 2. Install Redis
* For Docker deployments, refer to the latest `docker-compose.yml` file to add Redis configuration. Add a Redis container and configure the `REDIS_URL` environment variable for both `fastgpt` and `fastgpt-pro`.
* For Sealos deployments, create a new `redis` database in the Database section, copy the `internal connection` URL as the Redis connection string, then configure the `REDIS_URL` environment variable for both `fastgpt` and `fastgpt-pro`.
| | | |
| ---------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
|  |  |  |
### 3. Update Image Tags
* Update FastGPT image tag: v4.9.4
* Update FastGPT Pro image tag: v4.9.4
* Sandbox: no update required
* AIProxy: no update required
### 4. Run the Upgrade Script
This script only needs to be run by Pro edition users.
From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv494' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
**Script Functions**
1. Updates the site sync scheduler.
## New Features
1. Collection data training status display.
2. SMTP email sending plugin.
3. BullMQ message queue.
4. Partial data caching via Redis.
5. Site sync now supports configuring training parameters and incremental sync.
6. AI chat/tool calls now return the model's `finish_reason` field for easier tracking of output interruption causes.
7. Mobile voice input UI adjustments.
## Improvements
1. Admin template rendering adjustments.
2. Chat file expiration time now configurable via environment variable.
3. MongoDB log database can now be deployed independently.
## Bug Fixes
1. Unable to click into subdirectories when searching apps/knowledge bases.
2. Retraining parameters not properly initialized.
3. Inconsistent requests in package/service across multiple apps.
file: ./content/self-host/upgrading/outdated/494.mdx
meta: {
"title": "V4.9.4（环境变量变更、升级脚本）",
"description": "FastGPT V4.9.4 更新说明"
}
## 升级指南
### 1. 做好数据备份
### 2. 安装 Redis
* docker 部署的用户，参考最新的 `docker-compose.yml` 文件增加 Redis 配置。增加一个 redis 容器，并配置`fastgpt`,`fastgpt-pro`的环境变量，增加 `REDIS_URL` 环境变量。
* Sealos 部署的用户，在数据库里新建一个`redis`数据库，并复制`内网地址的 connection` 作为 `redis` 的链接串。然后配置`fastgpt`,`fastgpt-pro`的环境变量，增加 `REDIS_URL` 环境变量。
| | | |
| ---------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
|  |  |  |
### 3. 更新镜像 tag
* 更新 FastGPT 镜像 tag: v4.9.4
* 更新 FastGPT 商业版镜像 tag: v4.9.4
* Sandbox 无需更新
* AIProxy 无需更新
### 4. 执行升级脚本
该脚本仅需商业版用户执行。
从任意终端，发起 1 个 HTTP 请求。其中 `{{rootkey}}` 替换成环境变量里的 `rootkey`；`{{host}}` 替换成**FastGPT 域名**:
```bash
curl --location --request POST 'https://{{host}}/api/admin/initv494' \
--header 'rootkey: {{rootkey}}' \
--header 'Content-Type: application/json'
```
**脚本功能**
1. 更新站点同步定时器
## 🚀 新增内容
1. 集合数据训练状态展示
2. SMTP 发送邮件插件
3. BullMQ 消息队列。
4. 利用 redis 进行部分数据缓存。
5. 站点同步支持配置训练参数和增量同步。
6. AI 对话/工具调用，增加返回模型 finish\_reason 字段，便于追踪模型输出中断原因。
7. 移动端语音输入交互调整
## ⚙️ 优化
1. Admin 模板渲染调整。
2. 支持环境变量配置对话文件过期时间。
3. MongoDB log 库可独立部署。
## 🐛 修复
1. 搜索应用/知识库时，无法点击目录进入下一层。
2. 重新训练时，参数未成功初始化。
3. package/service 部分请求在多 app 中不一致。
file: ./content/self-host/upgrading/outdated/495.en.mdx
meta: {
"title": "V4.9.5",
"description": "FastGPT V4.9.5 Release Notes"
}
## Upgrade Guide
### 1. Back Up Your Data
### 2. Update Image Tags
* Update FastGPT image tag: v4.9.5
* Update FastGPT Pro image tag: v4.9.5
* Sandbox: no update required
* AIProxy: no update required
## New Features
1. Granular team member permissions: separately control whether members can create root-level apps/knowledge bases and API keys.
2. Interactive nodes now work inside nested workflows.
3. Team member operation audit logs.
4. User input node now supports checkboxes.
## Improvements
1. Traditional Chinese translation updates.
2. ARM image builds.
## Bug Fixes
1. Incorrect password validation rules.
2. Share links unable to hide knowledge base search results.
3. Regex compatibility issues on older iOS versions.
4. QA extraction queue counter not resetting after errors, causing the queue to stop working.
5. Debug mode interactive nodes potentially causing infinite loops on next step.
file: ./content/self-host/upgrading/outdated/495.mdx
meta: {
"title": "V4.9.5",
"description": "FastGPT V4.9.5 更新说明"
}
## 升级指南
### 1. 做好数据备份
### 2. 更新镜像 tag
* 更新 FastGPT 镜像 tag: v4.9.5
* 更新 FastGPT 商业版镜像 tag: v4.9.5
* Sandbox 无需更新
* AIProxy 无需更新
## 🚀 新增内容
1. 团队成员权限细分，可分别控制是否可创建在根目录应用/知识库以及 API Key
2. 支持交互节点在嵌套工作流中使用。
3. 团队成员操作日志。
4. 用户输入节点支持多选框。
## ⚙️ 优化
1. 繁体中文翻译。
2. Arm 镜像打包
## 🐛 修复
1. password 检测规则错误。
2. 分享链接无法隐藏知识库检索结果。
3. IOS 低版本正则兼容问题。
4. 修复问答提取队列错误后，计数器未清零问题，导致问答提取队列失效。
5. Debug 模式交互节点下一步可能造成死循环。
file: ./content/self-host/upgrading/outdated/496.en.mdx
meta: {
"title": "V4.9.6 (Environment Changes)",
"description": "FastGPT V4.9.6 Release Notes"
}
## New Features
1. Apps can now be called externally via MCP.
2. Support for creating tools using the MCP SSE protocol.
3. Batch execution node now supports interactive nodes, enabling human participation in each loop iteration.
4. Added workspace secondary menu with merged toolbox.
5. Added system configurations for grok3, GPT4.1, o-series, and Gemini 2.5 models.
## Improvements
1. Enhanced workflow data type conversion robustness and compatibility.
2. Python sandbox code now supports large data inputs.
3. Breadcrumb component now supports configuring whether the last step is clickable.
4. Knowledge base tool call results now automatically prepend image domain names.
5. GitHub Action runner upgraded to Ubuntu 24.
6. Removed extra leading/trailing newlines when replying via Lark, WeChat Official Account, and other third-party channels.
7. Adjusted chunking strategy: large tables are now split into independent chunks instead of being merged into oversized blocks.
8. Iframe embed component now includes built-in microphone permission declaration.
## Bug Fixes
1. Sub-workflows with interactive nodes not fully restoring all sub-workflow data.
2. Completion v1 API not accepting the `interactive` parameter, causing API call failures.
3. Consecutive tool calls causing abnormal context truncation.
## Upgrade Guide
### 1. Back Up Your Data
### 2. Deploy the MCP Server Service
#### Docker Deployment
Add the `fastgpt-mcp-server` service to your `docker-compose.yml` file:
```yml
fastgpt-mcp-server:
container_name: fastgpt-mcp-server
image: ghcr.io/labring/fastgpt-mcp_server:v4.9.6
ports:
- 3005:3000
networks:
- fastgpt
restart: always
environment:
- FASTGPT_ENDPOINT=http://fastgpt:3000
```
#### Sealos Deployment
In `App Management`, add a new `fastgpt-mcp-server` app with the image `ghcr.io/labring/fastgpt-mcp_server:v4.9.6` and set the environment variable `FASTGPT_ENDPOINT=`.
### 3. Update FastGPT Container Environment Variables
#### Community Edition
Add the following to your `config.json` configuration file: `"feconfigs.mcpServerProxyEndpoint": ""` (no trailing slash). For example:
```json
{
"feConfigs": {
"lafEnv": "https://laf.dev",
"mcpServerProxyEndpoint": "https://mcp.fastgpt.cn"
}
}
```
#### Pro Edition
In the Admin panel, go to `System Configuration - Basic Settings - System Parameters` and set the `MCP Proxy Server URL` to the public access URL of your `fastgpt-mcp-server`.
### 4. Update Image Tags
* Update FastGPT image tag: v4.9.6
* Update FastGPT Pro image tag: v4.9.6
* Update Sandbox image tag: v4.9.6
* Add FastGPT MCP Server image tag: v4.9.6
* AIProxy: no update required
file: ./content/self-host/upgrading/outdated/496.mdx
meta: {
"title": "V4.9.6（环境变量变更）",
"description": "FastGPT V4.9.6 更新说明"
}
## 🚀 新增内容
1. 以 MCP 方式对外提供应用调用。
2. 支持以 MCP SSE 协议创建工具。
3. 批量执行节点支持交互节点，可实现每一轮循环都人工参与。
4. 增加工作台二级菜单，合并工具箱。
5. 增加 grok3、GPT4.1、o 系列、Gemini2.5 模型系统配置。
## ⚙️ 优化
1. 工作流数据类型转化鲁棒性和兼容性增强。
2. Python sandbox 代码，支持大数据输入。
3. 路径组件支持配置最后一步是否可点击。
4. 知识库工具调用结果，自动补充图片域名。
5. GitHub action runner 升级成 unbuntu24
6. 去除飞书、公众号等三方渠道，回复时，可能前后多一个换行的问题。
7. 调整分块策略，大表格时，不进行超大块合并，而是独立拆块。
8. Iframe 嵌套组件，内置允许麦克风声明。
## 🐛 修复
1. 修复子工作流包含交互节点时，未成功恢复子工作流所有数据。
2. completion v1 接口，未接受 interactive 参数，导致 API 调用失败。
3. 连续工具调用，上下文截断异常
## 升级指南
### 1. 做好数据备份
### 2. 部署 MCP server 服务
#### Docker 部署
在 `docker-compose.yml` 文件中，加入 `fastgpt-mcp-server` 服务:
```yml
fastgpt-mcp-server:
container_name: fastgpt-mcp-server
image: ghcr.io/labring/fastgpt-mcp_server:v4.9.6
ports:
- 3005:3000
networks:
- fastgpt
restart: always
environment:
- FASTGPT_ENDPOINT=http://fastgpt:3000
```
#### Sealos 部署
直接在 `应用管理` 中，增加一个 `fastgpt-mcp-server` 应用，镜像为 `ghcr.io/labring/fastgpt-mcp_server:v4.9.6`，并设置环境变量 `FASTGPT_ENDPOINT=fastgpt 的访问地址`。
### 3. 修改 FastGPT 容器环境变量
#### 社区版
修改 `config.json` 配置文件，增加: `"feconfigs.mcpServerProxyEndpoint": "fastgpt-mcp-server 的访问地址"`，末尾不要携带/，例如:
```json
{
"feConfigs": {
"lafEnv": "https://laf.dev",
"mcpServerProxyEndpoint": "https://mcp.fastgpt.cn"
}
}
```
#### 商业版
在 Admin 后台，`系统配置-基础配置-系统参数` 中的 `MCP 转发服务地址` 中，设置 `fastgpt-mcp-server` 的公网访问地址。
### 4. 更新镜像 tag
* 更新 FastGPT 镜像 tag: v4.9.6
* 更新 FastGPT 商业版镜像 tag: v4.9.6
* 更新 Sandbox 镜像 tag: v4.9.6
* 增加 FastGPT mcp server 镜像 tag: v4.9.6
* AIProxy 无需更新
file: ./content/self-host/upgrading/outdated/497.en.mdx
meta: {
"title": "V4.9.7",
"description": "FastGPT V4.9.7 Release Notes"
}
## Upgrade Guide
### 1. Back Up Your Data
### 2. Update Image Tags
* Update FastGPT image tag: v4.9.7-fix2
* Update FastGPT Pro image tag: v4.9.7
* mcp\_server: no update required
* Sandbox: no update required
* Update AIProxy image tag: v0.1.8
## New Features
1. Knowledge base answers now include citations at the end of each referenced paragraph.
2. MCP tools support the HTTP Streamable protocol.
3. MCP Server supports editing tool names to accommodate clients that don't support Chinese characters.
4. Right-click in the workflow editor to auto-align nodes.
5. Support for custom `config.json` path in production environments.
6. API calls support passing a special chatId (`NO_RECORD_HISTORIES`) to prevent the system from storing conversation history.
7. Rerank model usage-based billing support.
8. Subscription plan redemption codes.
9. Alipay payment support.
10. Short link analytics tracking.
11. Added Jina AI model system configuration.
## Improvements
1. Doc2x document parsing: added error message capture and increased timeout duration.
2. Adjusted PG vector query to force vector index usage.
3. Conversation time statistics now accurately return the overall workflow execution time.
4. Audio parsing duration now retrieved from ai\_proxy.
5. AI model token counts now prioritize the API usage values for accuracy. If unavailable, falls back to GPT-3.5 estimation.
6. Optimized the chat log list API to handle scenarios with large numbers of messages in a single conversation.
## Bug Fixes
1. File upload chunk size limit to prevent exceeding MongoDB limits.
2. Usage dashboard unable to retrieve statistics for specific members.
3. Dashboard API returning incorrect statistics due to timezone handling issues.
4. LLM model test API unable to test disabled models. Also fixed the issue where model testing would strip custom request URLs.
5. Copy app permission issues.
6. Chat record export now limits individual conversations to 1,000 message pairs to prevent export failures.
7. Workflow variables followed by another workflow variable not triggering rendering.
8. Debugging the knowledge base search module showing "no permission" errors.
9. Text content extraction node default value assignment logic.
10. Share links forcibly returning citation content from nested apps.
11. Knowledge base collection metadata filtering: same-named tags across different knowledge bases returning no results when using `$and` filters.
12. App list permission configuration potentially causing index refresh issues.
file: ./content/self-host/upgrading/outdated/497.mdx
meta: {
"title": "V4.9.7",
"description": "FastGPT V4.9.7 更新说明"
}
## 升级指南
### 1. 做好数据备份
### 2. 更新镜像 tag
* 更新 FastGPT 镜像 tag: v4.9.7-fix2
* 更新 FastGPT 商业版镜像 tag: v4.9.7
* mcp\_server 无需更新
* Sandbox 无需更新
* 更新 AIProxy 镜像 tag: v0.1.8
## 🚀 新增内容
1. 知识库回答时，回答段落末尾增加引用。
2. MCP 工具支持 HTTP Streamable 协议。
3. MCP server 支持编辑工具名，适配部分客户端不支持中文名问题。
4. 工作流右键可自动对齐节点。
5. 支持生产环境自定义`config.json`路径。
6. API 调用，支持传递一个特殊 chatId(`NO_RECORD_HISTORIES`)，使得系统不会进行历史记录存储。
7. 支持 Rerank 模型按量计费。
8. 套餐兑换码功能。
9. 支付宝支付。
10. 短链数据埋点。
11. 新增 Jina AI 模型系统配置。
## ⚙️ 优化
1. Doc2x 文档解析，增加报错信息捕获，增加超时时长。
2. 调整 PG vector 查询语句，强制使用向量索引。
3. 对话时间统计，准确返回工作流整体运行时间。
4. 从 ai\_proxy 获取音频解析时长。
5. AI 模型 Token 值均优先采用 API usage，确保 tokens 值准确，若为空，则再采用 GPT3.5 的估算方式。
6. 优化对话日志 list 接口，适配单个对话框，大量对话的场景。
## 🐛 修复
1. 文件上传分块大小限制，避免超出 MongoDB 限制。
2. 使用记录仪表盘，无法获取指定成员的使用统计。
3. 仪表盘接口，因未考虑时区问题，统计异常。
4. LLM 模型测试接口，无法测试未启用的 LLM。同时修复，模型测试接口会把模型自定义请求地址去除问题。
5. Copy app 权限问题。
6. 导出对话记录，限制单条对话记录消息上限 1000 组，避免导出失败。
7. 工作流变量下一段文本仍是工作流变量，不触发渲染。
8. 调试知识库检索模块，提示无权操作知识库。
9. 文本内容提取节点，默认值赋值逻辑。
10. 分享链接中，会强制返回嵌套应用中的引用内容。
11. 知识库集合元数据过滤时，不同知识库的同名标签使用 $and 筛选无法获取结果。
12. 修复应用列表，权限配置可能出现 index 刷新问题。
file: ./content/self-host/upgrading/outdated/498.en.mdx
meta: {
"title": "V4.9.8",
"description": "FastGPT V4.9.8 Release Notes"
}
## Upgrade Guide
### 1. Back Up Your Data
### 2. Update Image Tags
* Update FastGPT image tag: v4.9.8
* Update FastGPT Pro image tag: v4.9.8
* mcp\_server: no update required
* Sandbox: no update required
* AIProxy: no update required
## New Features
1. Support for parallel tool call execution.
2. All built-in tasks switched from non-stream mode to stream mode to avoid compatibility issues with models that don't support non-stream mode. To override, you can force `stream=false` in the model's `Extra Body` parameters.
3. Qwen3 model presets.
4. Yuque knowledge base now supports setting a root directory.
5. Configurable password expiration — users will be forced to change their password on next login after expiration.
6. Password login now includes preLogin temporary key verification.
7. Admin panel now supports configuring visibility of publishing channels and third-party knowledge bases.
## Improvements
1. Chat log list optimization to prevent memory overflow with large datasets.
2. Token calculation worker is now preloaded to prevent thread blocking from concurrent creation during main tasks.
3. Workflow node version control UI improvements.
4. Web fetch and html2md optimization: now supports video and audio tag conversion.
## Bug Fixes
1. App list / knowledge base list: incorrect permission display for delete row actions.
2. Opening knowledge base search parameters automatically enabling the rerank option.
3. Incorrect API request format for LLM json\_schema mode.
4. Expired image indexes not properly cleared during retraining, causing image loss.
5. Retraining permission issues.
6. Documentation link URLs.
7. Claude tool calls failing due to empty index values.
8. Nested workflows with interactive nodes inside tool calls causing abnormal flow behavior.
file: ./content/self-host/upgrading/outdated/498.mdx
meta: {
"title": "V4.9.8",
"description": "FastGPT V4.9.8 更新说明"
}
## 升级指南
### 1. 做好数据备份
### 2. 更新镜像 tag
* 更新 FastGPT 镜像 tag: v4.9.8
* 更新 FastGPT 商业版镜像 tag: v4.9.8
* mcp\_server 无需更新
* Sandbox 无需更新
* AIProxy 无需更新
## 🚀 新增内容
1. 支持 Toolcalls 并行执行。
2. 将所有内置任务，从非 stream 模式调整成 stream 模式，避免部分模型不支持非 stream 模式。如需覆盖，则可以在模型`额外 Body`参数中，强制指定`stream=false`。
3. qwen3 模型预设
4. 语雀知识库支持设置根目录。
5. 可配置密码过期时间，过期后下次登录会强制要求修改密码。
6. 密码登录增加 preLogin 临时密钥校验。
7. 支持 Admin 后台配置发布渠道和第三方知识库的显示隐藏。
## ⚙️ 优化
1. Chat log list 优化，避免大数据时超出内存限制。
2. 预加载 token 计算 worker，避免主任务中并发创建导致线程阻塞。
3. 工作流节点版本控制交互优化。
4. 网络获取以及 html2md 优化，支持视频和音频标签的转换。
## 🐛 修复
1. 应用列表/知识库列表，删除行权限展示问题。
2. 打开知识库搜索参数后，重排选项自动被打开。
3. LLM json\_schema 模式 API 请求格式错误。
4. 重新训练时，图片过期索引未成功清除，导致图片会丢失。
5. 重新训练权限问题。
6. 文档链接地址。
7. Claude 工具调用，由于 index 为空，导致工具调用失败。
8. 嵌套工作流，工具调用下包含交互节点时，流程异常。
file: ./content/self-host/upgrading/outdated/499.en.mdx
meta: {
"title": "V4.9.9",
"description": "FastGPT V4.9.9 Release Notes"
}
## Upgrade Guide
### 1. Back Up Your Data
### 2. Pro Edition Users: Replace Your License
Pro edition users can contact the FastGPT team for a license replacement plan. After replacement, you can upgrade the system directly — the admin panel will prompt you to enter the new license.
### 3. Update Image Tags
* Update FastGPT image tag: v4.9.9
* Update FastGPT Pro image tag: v4.9.9
* mcp\_server: no update required
* Sandbox: no update required
* AIProxy: no update required
## New Features
1. Switched from JWT to SessionId-based login authentication, with configurable maximum concurrent client sessions.
2. New Pro edition license management model.
3. WeChat Official Account calls now display and log chat conversation errors for easier troubleshooting.
4. API knowledge base now supports BasePath selection. Requires an additional API endpoint — see [API Knowledge Base Introduction](../../../guide/dataset/third-party/api_dataset.en.mdx#4-获取文件详细信息用于获取文件信息) for details.
## Improvements
1. Optimized tool call logic for new tool detection.
2. Adjusted citation prompt text.
## Bug Fixes
1. Unable to retrieve app history save/publish records.
2. Member MCP tool creation permission issues.
3. Source citation display passing incorrect IDs, causing "no permission to access this file" errors.
4. Answer annotation frontend data errors.
file: ./content/self-host/upgrading/outdated/499.mdx
meta: {
"title": "V4.9.9",
"description": "FastGPT V4.9.9 更新说明"
}
## 升级指南
### 1. 做好数据备份
### 2. 商业版用户替换新 License
商业版用户可以联系 FastGPT 团队支持同学，获取 License 替换方案。替换后，可以直接升级系统，管理后台会提示输入新 License。
### 3. 更新镜像 tag
* 更新 FastGPT 镜像 tag: v4.9.9
* 更新 FastGPT 商业版镜像 tag: v4.9.9
* mcp\_server 无需更新
* Sandbox 无需更新
* AIProxy 无需更新
## 🚀 新增内容
1. 切换 SessionId 来替代 JWT 实现登录鉴权，可控制最大登录客户端数量。
2. 新的商业版 License 管理模式。
3. 公众号调用，显示记录 chat 对话错误，方便排查。
4. API 知识库支持 BasePath 选择，需增加 API 接口，具体可见[API 知识库介绍](../../../guide/dataset/third-party/api_dataset.mdx#4-获取文件详细信息用于获取文件信息)
## ⚙️ 优化
1. 优化工具调用，新工具的判断逻辑。
2. 调整 Cite 引用提示词。
## 🐛 修复
1. 无法正常获取应用历史保存/发布记录。
2. 成员创建 MCP 工具权限问题。
3. 来源引用展示，存在 ID 传递错误，导致提示无权操作该文件。
4. 回答标注前端数据报错。
file: ./content/guide/build/tools/system-plugins/upload_system_tool.en.mdx
meta: {
"title": "Upload System Tools Online",
"description": "FastGPT System Tool Online Upload Guide"
}
> Starting from FastGPT 4.14.0, system admins can upload and update system tools directly through the web interface for hot reloading.
## Permission Requirements
⚠️ **Important**: Only **root users** can use the online system tool upload feature.
* Make sure you are logged in with the `root` account
## Supported File Formats
* **File type**: `.pkg` files
* **File size**: Maximum 100 MB
* **File count**: Up to 15 files per upload
## Upload Steps
### 1. Access the Configuration Page
### 2. Prepare Tool Files
Before uploading, make sure your `.pkg` files are from the `dist/pkgs` folder, built by running `bun run build:pkg` in the fastgpt-plugin project.
### 3. Upload
1. Click the **"Import/Update"** button
2. In the dialog that appears, click the file selection area
3. Select your prepared `.pkg` tool files
4. After confirming the file details, click **"Confirm Import"**
### 4. Upload Process
* A success message will appear after the upload completes
* The page auto-refreshes and the new tools will appear in the tool list
## Features
### Tool Management
* **View tools**: All users can view installed system tools
* **Upload tools**: Only root users can upload new tools or update existing ones
* **Delete tools**: Only root users can delete uploaded tools
## FAQ
### Q: Can't see the "Import/Update" button
**Reason:** The current user is not a root user
**Solution:** Log in again with the root account
file: ./content/guide/build/tools/system-plugins/upload_system_tool.mdx
meta: {
"title": "如何在线上传系统工具",
"description": "FastGPT 系统工具在线上传指南"
}
> 从 FastGPT 4.14.0 版本开始，系统管理员可以通过 Web 界面直接上传和更新系统工具进行热更新
## 权限要求
⚠️ **重要提示**：只有 **root 用户** 才能使用在线上传系统工具功能。
* 确保您已使用 `root` 账户登录 FastGPT
## 支持的文件格式
* **文件类型**：`.pkg` 文件
* **文件大小**：最大 100 MB
* **文件数量**：每次最多上传 15 个文件
## 上传步骤
### 1. 进入配置页面
### 2. 准备工具文件
在上传之前，请确保您的 `.pkg` 文件是从 fastgpt-plugin 项目中通过 `bun run build:pkg` 命令打包后的 `dist/pkgs` 文件夹下得到的
### 3. 执行上传
1. 点击 **"导入/更新"** 按钮
2. 在弹出的对话框中，点击文件选择区域
3. 选择您准备好的 `.pkg` 工具文件
4. 确认文件信息无误后，点击 **"确认导入"**
### 4. 上传过程
* 上传成功后会显示成功提示
* 页面自动刷新，新工具会出现在工具列表中
## 功能特点
### 工具管理
* **查看工具**：所有用户都可以查看已安装的系统工具
* **上传工具**：仅 root 用户可以上传新工具或更新现有工具
* **删除工具**：仅 root 用户可以删除已上传的工具
## 常见问题
### Q: 无法看到"导入/更新"按钮
**原因：** 当前用户不是 root 用户
**解决方案：** 使用 root 账户重新登录
file: ./content/guide/build/workflow/nodes/ai_chat.en.mdx
meta: {
"title": "AI Chat",
"description": "FastGPT AI Chat node overview"
}
import { Alert } from '@/components/docs/Alert';
## Characteristics
* Can be added multiple times
* Trigger-based execution
* Core module
## Parameters
## AI Model
Configure available chat models via [config.json](../../../../self-host/config/model/intro.en.mdx)。
Click the AI model to configure its parameters.
For detailed parameter descriptions, see: [AI Parameter Configuration](../../general/ai_settings.en.mdx)
file: ./content/guide/build/workflow/nodes/ai_chat.mdx
meta: {
"title": "AI 对话",
"description": "FastGPT AI 对话模块介绍"
}
import { Alert } from '@/components/docs/Alert';
## 特点
* 可重复添加
* 触发执行
* 核心模块
## 参数说明
## AI模型
可以通过 [config.json](../../../../self-host/config/model/intro.mdx) 配置可选的对话模型。
点击AI模型后，可以配置模型的相关参数。
具体配置参数介绍可以参考: [AI参数配置说明](../../general/ai_settings.mdx)
file: ./content/guide/build/workflow/nodes/content_extract.en.mdx
meta: {
"title": "Text Content Extraction",
"description": "FastGPT Text Content Extraction node overview"
}
## Characteristics
* Can be added multiple times
* Requires manual configuration
* Trigger-based execution
* function\_call module
* Core module
## What It Does
Extracts structured data from text, typically used with the HTTP node for extended functionality. It can also perform direct extraction tasks such as translation.
## Parameters
### Extraction Requirement Description
Set a goal for the model describing what content needs to be extracted.
**Example 1**
> You are a lab appointment assistant. Extract the name, appointment time, and lab number from the conversation. Current time `{{cTime}}`
**Example 2**
> You are a Google search assistant. Extract search keywords from the conversation.
**Example 3**
> Translate my question directly into English without answering it.
### Chat History
Some chat history is usually needed for more complete extraction. For example, if the task requires a name, time, and lab name, the user might initially provide only the time and lab name. After being prompted for the missing info, the user provides their name. At that point, the previous record is needed to extract all 3 fields completely.
### Target Fields
Target fields correspond to extraction results. As shown above, each new field adds a corresponding output.
* **key**: Unique identifier for the field. Must not be duplicated.
* **Field description**: Describes what the field represents, e.g., name, time, search keyword, etc.
* **Required**: Whether the model is forced to extract this field. It may still return an empty string.
## Output
* **Complete extraction result**: A JSON string containing all extracted fields.
* **Target field extraction results**: All returned as string type.
file: ./content/guide/build/workflow/nodes/content_extract.mdx
meta: {
"title": "文本内容提取",
"description": "FastGPT 内容提取模块介绍"
}
## 特点
* 可重复添加
* 需要手动配置
* 触发执行
* function\_call 模块
* 核心模块
## 功能
从文本中提取结构化数据，通常是配合 HTTP 模块实现扩展。也可以做一些直接提取操作，例如：翻译。
## 参数说明
### 提取要求描述
顾名思义，给模型设置一个目标，需要提取哪些内容。
**示例 1**
> 你是实验室预约助手，从对话中提取出姓名，预约时间，实验室号。当前时间 `{{cTime}}`
**示例 2**
> 你是谷歌搜索助手，从对话中提取出搜索关键词
**示例 3**
> 将我的问题直接翻译成英文，不要回答问题
### 历史记录
通常需要一些历史记录，才能更完整的提取用户问题。例如上图中需要提供姓名、时间和实验室名，用户可能一开始只给了时间和实验室名，没有提供自己的姓名。再经过一轮缺失提示后，用户输入了姓名，此时需要结合上一次的记录才能完整的提取出 3 个内容。
### 目标字段
目标字段与提取的结果相对应，从上图可以看到，每增加一个字段，输出会增加一个对应的出口。
* **key**: 字段的唯一标识，不可重复！
* **字段描述**：描述该字段是关于什么的，例如：姓名、时间、搜索词等等。
* **必须**：是否强制模型提取该字段，可能提取出来是空字符串。
## 输出介绍
* **完整提取结果**: 一个 JSON 字符串，包含所有字段的提取结果。
* **目标字段提取结果**：类型均为字符串。
file: ./content/guide/build/workflow/nodes/coreferenceResolution.en.mdx
meta: {
"title": "Query Enhancement",
"description": "FastGPT Query Enhancement node overview and usage"
}
## Characteristics
* Can be added multiple times
* Has external input
* Trigger-based execution
## Background
In RAG, we perform embedding searches against the database based on the input query to find relevant content (Knowledge Base search).
During search -- especially in multi-turn conversations -- follow-up questions often fail to retrieve useful results. One reason is that Knowledge Base search only uses the "current" question. Consider this example:
When the user asks "What is the second point?", the system searches the Knowledge Base for exactly that phrase and finds nothing. The actual intended query is "What is the QA structure?". This is why we need a Query Enhancement node to refine the user's current question so the Knowledge Base search can return relevant results. With query enhancement applied:
## What It Does
Calls an AI model to complete and refine the user's current question. It primarily resolves coreferences (pronouns and vague references), making search queries more complete and reliable. This improves Knowledge Base search accuracy in multi-turn conversations.
The main challenge is that the model may not have a clear understanding of "completion" and often struggles to determine how to properly refine queries with long context.
file: ./content/guide/build/workflow/nodes/coreferenceResolution.mdx
meta: {
"title": "问题优化",
"description": "问题优化模块介绍和使用"
}
## 特点
* 可重复添加
* 有外部输入
* 触发执行
## 背景
在 RAG 中，我们需要根据输入的问题去数据库里执行 embedding 搜索，查找相关的内容，从而查找到相似的内容（简称知识库搜索）。
在搜索的过程中，尤其是连续对话的搜索，我们通常会发现后续的问题难以搜索到合适的内容，其中一个原因是知识库搜索只会使用“当前”的问题去执行。看下面的例子：
用户在提问“第二点是什么”的时候，只会去知识库里查找“第二点是什么”，压根查不到内容。实际上需要查询的是“QA 结构是什么”。因此我们需要引入一个【问题优化】模块，来对用户当前的问题进行补全，从而使得知识库搜索能够搜索到合适的内容。使用补全后效果如下：
## 功能
调用 AI 去对用户当前的问题进行补全。目前主要是补全“指代”词，使得检索词更加的完善可靠，从而增强上下文连续对话的知识库搜索能力。
遇到最大的难题在于：模型对于【补全】的概念可能不清晰，且对于长上下文往往无法准确的知道应该如何补全。
file: ./content/guide/build/workflow/nodes/custom_feedback.en.mdx
meta: {
"title": "Custom Feedback",
"description": "FastGPT Custom Feedback node overview"
}
This is a temporary module that will receive a more comprehensive redesign in the future.
## Characteristics
* Can be added multiple times
* No external input
* Auto-executed
| | |
| ------------------------------ | ------------------------------ |
|  |  |
|  |  |
## Overview
The Custom Feedback node adds a feedback tag to conversations, making it easier to analyze conversation data from the admin panel.
In debug mode, feedback content is not recorded. Instead it displays: `Auto feedback test: feedback content`.
In conversation mode (chat, shared window, or API calls with chatId), feedback content is recorded in the conversation log with a 60-second delay.
## Use Cases
The Custom Feedback node works like event tracking in software development, letting you observe and monitor data within conversations.
file: ./content/guide/build/workflow/nodes/custom_feedback.mdx
meta: {
"title": "自定义反馈",
"description": "自定义反馈模块介绍"
}
该模块为临时模块，后续会针对该模块进行更全面的设计。
## 特点
* 可重复添加
* 无外部输入
* 自动执行
| | |
| ------------------------------ | ------------------------------ |
|  |  |
|  |  |
## 介绍
自定义反馈模块，可以为你的对话增加一个反馈标记，从而方便在后台更好的分析对话的数据。
在调试模式下，不会记录反馈内容，而是直接提示: `自动反馈测试: 反馈内容`。
在对话模式（对话、分享窗口、带 chatId 的 API 调用）时，会将反馈内容记录到对话日志中。（会延迟60s记录）
## 作用
自定义反馈模块的功能类似于程序开发的`埋点`，便于你观测的对话中的数据。
file: ./content/guide/build/workflow/nodes/dataset_search.en.mdx
meta: {
"title": "Knowledge Base Search",
"description": "FastGPT Knowledge Base Search node overview"
}
For detailed parameters and internal logic, see: [FastGPT Knowledge Base Search](../../../dataset/rag.en.mdx)
## Characteristics
* Can be added multiple times (keeps connections tidy in complex workflows)
* Has external input
* Has static configuration
* Trigger-based execution
* Core module
## Parameters
### Input - Linked Knowledge Bases
Select one or more Knowledge Bases using the **same embedding model** for vector search.
### Input - Search Parameters
[View parameter details](../../../dataset/dataset_engine.en.mdx#搜索参数)
### Output - Referenced Content
Outputs references as an array with a possible length of 0. This means the output path will still execute even when no results are found.
file: ./content/guide/build/workflow/nodes/dataset_search.mdx
meta: {
"title": "知识库搜索",
"description": "FastGPT AI 知识库搜索模块介绍"
}
知识库搜索具体参数说明，以及内部逻辑请移步：[FastGPT知识库搜索方案](../../../dataset/rag.mdx)
## 特点
* 可重复添加（复杂编排时防止线太乱，可以更美观）
* 有外部输入
* 有静态配置
* 触发执行
* 核心模块
## 参数说明
### 输入 - 关联的知识库
可以选择一个或多个**相同向量模型**的知识库，用于向量搜索。
### 输入 - 搜索参数
[点击查看参数介绍](../../../dataset/dataset_engine.mdx#搜索参数)
### 输出 - 引用内容
以数组格式输出引用，长度可以为 0。意味着，即使没有搜索到内容，这个输出链路也会走通。
file: ./content/guide/build/workflow/nodes/document_parsing.en.mdx
meta: {
"title": "Document Parsing",
"description": "FastGPT Document Parsing node overview"
}
| | |
| --------------------------------- | --------------------------------- |
|  |  |
The Document Parsing component becomes available after enabling file upload.
## Features
## Use Cases
file: ./content/guide/build/workflow/nodes/document_parsing.mdx
meta: {
"title": "文档解析",
"description": "FastGPT 文档解析模块介绍"
}
| | |
| --------------------------------- | --------------------------------- |
|  |  |
开启文件上传后，可使用文档解析组件。
## 功能
## 作用
file: ./content/guide/build/workflow/nodes/form_input.en.mdx
meta: {
"title": "Form Input",
"description": "FastGPT Form Input node overview"
}
## Characteristics
* User interaction
* Can be added multiple times
* Trigger-based execution
## What It Does
The Form Input node is a user interaction node. When triggered, the conversation enters an "interactive" state -- the workflow state is saved and execution pauses until the user completes the interaction.
In the example above, when the Form Input node is triggered, the chat box is hidden and the conversation enters interactive mode.
After the user fills in the required fields and clicks submit, the node collects the form data and passes it to subsequent nodes.
## Use Cases
Precisely collect specific user information, then perform follow-up operations based on that data.
file: ./content/guide/build/workflow/nodes/form_input.mdx
meta: {
"title": "表单输入",
"description": "FastGPT 表单输入模块介绍"
}
## 特点
* 用户交互
* 可重复添加
* 触发执行
## 功能
「表单输入」节点属于用户交互节点，当触发这个节点时，对话会进入“交互”状态，会记录工作流的状态，等用户完成交互后，继续向下执行工作流
比如上图中的例子，当触发表单输入节点时，对话框隐藏，对话进入“交互状态”
当用户填完必填的信息并点击提交后，节点能够收集用户填写的表单信息，传递到后续的节点中使用
## 作用
能够精准收集需要的用户信息，再根据用户信息进行后续操作
file: ./content/guide/build/workflow/nodes/http.en.mdx
meta: {
"title": "HTTP Request",
"description": "FastGPT HTTP Request node overview"
}
import { Alert } from '@/components/docs/Alert';
## Characteristics
* Can be added multiple times
* Manual configuration
* Trigger-based execution
* Core of core modules
## Overview
The HTTP node sends an `HTTP` request to a specified URL. It works similarly to tools like Postman and ApiFox.
* Params are query parameters, commonly used in GET requests.
* Body is the request body, commonly used in POST/PUT requests.
* Headers are request headers for passing additional information.
* Custom variables can receive outputs from upstream nodes.
* All 3 data types support variable references via `{{}}`.
* The URL also supports `{{}}` variable references.
* Variables come from `global variables`, `system variables`, and `upstream node outputs`.
## Parameter Structure
### System Variables
Hover over the question mark next to `Request Parameters` to see available variables.
* appId: Application ID
* chatId: Current conversation ID (not available in test mode)
* responseChatItemId: Response message ID in the current conversation (not available in test mode)
* variables: Global variables for the current conversation
* cTime: Current time
* histories: Chat history (defaults to max 10 entries, length is not configurable)
### Params, Headers
Usage is the same as Postman and ApiFox.
Use `{{key}}` to reference variables. For example:
| key | value |
| ------------- | ------------------ |
| appId | `{{appId}}` |
| Authorization | Bearer `{{token}}` |
### Body
Only takes effect with certain request types.
Write a custom JSON body and use `{{key}}` to reference variables. For example:
```json
{
"string": "字符串",
"number": 123,
"boolean": true,
"array": [1, 2, 3],
"obj": {
"name": "FastGPT",
"url": "https://fastgpt.io"
}
}
```
When referencing a `string` in the Body, wrap it in quotes: `"{{string}}"`.
```json
{
"string": "{{string}}",
"token": "Bearer {{string}}",
"number": {{number}},
"boolean": {{boolean}},
"array": [{{number}}, "{{string}}"],
"array2": {{array}},
"object": {{obj}}
}
```
```json
{
"string": "字符串",
"token": "Bearer 字符串",
"number": 123,
"boolean": true,
"array": [123, "字符串"],
"array2": [1, 2, 3],
"object": {
"name": "FastGPT",
"url": "https://fastgpt.io"
}
}
```
### Extracting Return Values
As shown in the image, FastGPT lets you add multiple return values. These don't represent the raw API response -- they define `how to parse the API response`. You can use `JSON path` syntax to `extract` values from the response.
Syntax reference: [https://github.com/JSONPath-Plus/JSONPath?tab=readme-ov-file](https://github.com/JSONPath-Plus/JSONPath?tab=readme-ov-file)
```json
{
"message": "测试",
"data": {
"user": {
"name": "xxx",
"age": 12
},
"list": [
{
"name": "xxx",
"age": 50
},
[{ "test": 22 }]
],
"psw": "xxx"
}
}
```
```json
{
"$.message": "测试",
"$.data.user": { "name": "xxx", "age": 12 },
"$.data.user.name": "xxx",
"$.data.user.age": 12,
"$.data.list": [{ "name": "xxx", "age": 50 }, [{ "test": 22 }]],
"$.data.list[0]": { "name": "xxx", "age": 50 },
"$.data.list[0].name": "xxx",
"$.data.list[0].age": 50,
"$.data.list[1]": [{ "test": 22 }],
"$.data.list[1][0]": { "test": 22 },
"$.data.list[1][0].test": 22,
"$.data.psw": "xxx"
}
```
Configure the `key` to extract values from FastGPT's parsed format, following standard JavaScript object access rules. For example:
1. To get the `message` content, set the `key` to `message`.
2. To get the user's name, set the `key` to `data.user.name`.
3. To get the second element in the list, set the `key` to `data.list[1]`. If you select string as the output type, it will automatically return the JSON string `[ { "test": 22 } ]`.
### Auto-format Output
Starting from FastGPT v4.6.8, output formatting was added, primarily converting `JSON` to `string`. If you select `string` as the output type, the HTTP node will convert the corresponding key's value to a JSON string. This lets you pipe HTTP output directly into a `Text Processing` node, append appropriate prompts, and feed the result into `AI Chat`.
The HTTP node is extremely versatile. You can integrate public APIs to extend your workflow
capabilities.
## HTTP Service Integration Example
Here is a POST request service example:
```ts
type RequestType = {
appId: string;
appointment: string;
action: 'post' | 'delete' | 'put' | 'get';
};
export async function handleAppointmentRequest(body: RequestType) {
try {
const { appId, appointment, action } = body;
const parseBody = JSON.parse(appointment);
if (action === 'get') {
return await getRecord(appId, parseBody);
}
if (action === 'post') {
return await createRecord(appId, parseBody);
}
if (action === 'put') {
return await putRecord(appId, parseBody);
}
if (action === 'delete') {
return await removeRecord(appId, parseBody);
}
return {
response: 'Error'
};
} catch (err) {
return {
response: 'Error'
};
}
}
```
## Use Cases
The HTTP node enables unlimited extensibility, such as:
* Database operations
* External data source calls
* Web searches
* Sending emails
* ....
file: ./content/guide/build/workflow/nodes/http.mdx
meta: {
"title": "HTTP 请求",
"description": "FastGPT HTTP 模块介绍"
}
import { Alert } from '@/components/docs/Alert';
## 特点
* 可重复添加
* 手动配置
* 触发执行
* 核中核模块
## 介绍
HTTP 模块会向对应的地址发送一个 `HTTP` 请求，实际操作与 Postman 和 ApiFox 这类直流工具使用差不多。
* Params 为路径请求参数，GET 请求中用的居多。
* Body 为请求体，POST/PUT 请求中用的居多。
* Headers 为请求头，用于传递一些特殊的信息。
* 自定义变量中可以接收前方节点的输出作为变量
* 3 种数据中均可以通过 `{{}}` 来引用变量。
* URL 也可以通过 `{{}}` 来引用变量。
* 变量来自于 `全局变量`、`系统变量`、`前方节点输出`
## 参数结构
### 系统变量说明
你可以将鼠标放置在 `请求参数` 旁边的问号中，里面会提示你可用的变量。
* appId: 应用的 ID
* chatId: 当前对话的 ID，测试模式下不存在。
* responseChatItemId: 当前对话中，响应的消息 ID，测试模式下不存在。
* variables: 当前对话的全局变量。
* cTime: 当前时间。
* histories: 历史记录（默认最多取 10 条，无法修改长度）
### Params, Headers
不多描述，使用方法和 Postman, ApiFox 基本一致。
可通过 `{{key}}` 来引入变量。例如：
| key | value |
| ------------- | ------------------ |
| appId | `{{appId}}` |
| Authorization | Bearer `{{token}}` |
### Body
只有特定请求类型下会生效。
可以写一个 `自定义的 Json`，并通过 `{{key}}` 来引入变量。例如：
```json
{
"string": "字符串",
"number": 123,
"boolean": true,
"array": [1, 2, 3],
"obj": {
"name": "FastGPT",
"url": "https://fastgpt.io"
}
}
```
注意，在 Body 中，你如果引用 `字符串`，则需要加上 `""`，例如：`"{{string}}"`。
```json
{
"string": "{{string}}",
"token": "Bearer {{string}}",
"number": {{number}},
"boolean": {{boolean}},
"array": [{{number}}, "{{string}}"],
"array2": {{array}},
"object": {{obj}}
}
```
```json
{
"string": "字符串",
"token": "Bearer 字符串",
"number": 123,
"boolean": true,
"array": [123, "字符串"],
"array2": [1, 2, 3],
"object": {
"name": "FastGPT",
"url": "https://fastgpt.io"
}
}
```
### 如何获取返回值
从图中可以看出，FastGPT 可以添加多个返回值，这个返回值并不代表接口的返回值，而是代表 `如何解析接口返回值`，可以通过 `JSON path` 的语法，来 `提取` 接口响应的值。
语法可以参考: [https://github.com/JSONPath-Plus/JSONPath?tab=readme-ov-file](https://github.com/JSONPath-Plus/JSONPath?tab=readme-ov-file)
```json
{
"message": "测试",
"data": {
"user": {
"name": "xxx",
"age": 12
},
"list": [
{
"name": "xxx",
"age": 50
},
[{ "test": 22 }]
],
"psw": "xxx"
}
}
```
```json
{
"$.message": "测试",
"$.data.user": { "name": "xxx", "age": 12 },
"$.data.user.name": "xxx",
"$.data.user.age": 12,
"$.data.list": [{ "name": "xxx", "age": 50 }, [{ "test": 22 }]],
"$.data.list[0]": { "name": "xxx", "age": 50 },
"$.data.list[0].name": "xxx",
"$.data.list[0].age": 50,
"$.data.list[1]": [{ "test": 22 }],
"$.data.list[1][0]": { "test": 22 },
"$.data.list[1][0].test": 22,
"$.data.psw": "xxx"
}
```
你可以配置对应的 `key` 来从 `FastGPT 转化后的格式` 获取需要的值，该规则遵守 JS 的对象取值规则。例如：
1. 获取 `message` 的内容，那么你可以配置 `message` 的 `key` 为 `message`，这样就可以获取到 `message` 的内容。
2. 获取 `user的name`，则 `key` 可以为：`data.user.name`。
3. 获取 list 中第二个元素，则 `key` 可以为：`data.list[1]`，然后输出类型选择字符串，则获自动获取到 `[ { "test": 22 } ]` 的 `json` 字符串。
### 自动格式化输出
FastGPT v4.6.8 后，加入了出参格式化功能，主要以 `json` 格式化成 `字符串` 为主。如果你的输出类型选择了 `字符串`，则会将 `HTTP` 对应 `key` 的值，转成 `json` 字符串进行输出。因此，未来你可以直接从 `HTTP` 接口输出内容至 `文本加工` 中，然后拼接适当的提示词，最终输入给 `AI对话`。
HTTP 模块非常强大，你可以对接一些公开的 API，来提高编排的功能。
## HTTP 对接业务服务示例
下面是一个 POST 请求服务示例：
```ts
type RequestType = {
appId: string;
appointment: string;
action: 'post' | 'delete' | 'put' | 'get';
};
export async function handleAppointmentRequest(body: RequestType) {
try {
const { appId, appointment, action } = body;
const parseBody = JSON.parse(appointment);
if (action === 'get') {
return await getRecord(appId, parseBody);
}
if (action === 'post') {
return await createRecord(appId, parseBody);
}
if (action === 'put') {
return await putRecord(appId, parseBody);
}
if (action === 'delete') {
return await removeRecord(appId, parseBody);
}
return {
response: '异常'
};
} catch (err) {
return {
response: '异常'
};
}
}
```
## 作用
通过 HTTP 模块你可以无限扩展，比如：
* 操作数据库
* 调用外部数据源
* 执行联网搜索
* 发送邮箱
* ……
file: ./content/guide/build/workflow/nodes/knowledge_base_search_merge.en.mdx
meta: {
"title": "Knowledge Base Search Merge",
"description": "FastGPT Knowledge Base Search Merge node overview"
}
## What It Does
Merges search results from multiple Knowledge Bases into a single output, re-ranks them using RRF (Reciprocal Rank Fusion), and supports max token filtering.
## Usage
The AI Chat node can only accept one Knowledge Base reference input. If you call multiple Knowledge Bases, you cannot directly reference all of them (as shown below).
Use **Knowledge Base Search Merge** to combine results from multiple Knowledge Bases into one.
## Example Use Cases
1. After question classification, search different Knowledge Bases per category, then feed the merged results to a single AI Chat node. This avoids adding a separate AI Chat node to each branch.
file: ./content/guide/build/workflow/nodes/knowledge_base_search_merge.mdx
meta: {
"title": "知识库搜索引用合并",
"description": "FastGPT 知识库搜索引用合并模块介绍"
}
## 作用
将多个知识库搜索结果合并成一个结果进行输出，并会通过 RRF 进行重新排序（根据排名情况），并且支持最大 tokens 过滤。
## 使用方法
AI对话只能接收一个知识库引用内容。因此，如果调用了多个知识库，无法直接引用所有知识库（如下图）
使用**知识库搜索引用合并**，可以把多个知识库的搜索结果合在一起。
## 可用例子：
1. 经过问题分类后对不同知识库进行检索，然后统一给一个 AI 进行回答，此时可以用到合并，不需要每个分支都添加一个 AI 对话。
file: ./content/guide/build/workflow/nodes/loop.en.mdx
meta: {
"title": "Batch Processing",
"description": "FastGPT Batch Processing node overview and usage"
}
## Node Overview
The **Batch Processing** node was introduced in FastGPT V4.8.11. It allows workflows to iterate over array-type input data, processing one element at a time and automatically executing subsequent nodes until the entire array is processed.
This node is inspired by loop structures in programming languages, presented in a visual format.
> In programming terms, nodes are like functions or API endpoints -- each one is a **step**. By connecting multiple nodes together, you build a step-by-step process that produces the final AI output.
The **Batch Processing** node is essentially a function whose job is to automate repeated execution of a specific workflow.
## Core Features
1. **Array Batch Processing**
* Accepts array-type data input
* Automatically iterates through array elements
* Maintains processing order
* Supports parallel processing for performance optimization
2. **Automatic Iteration**
* Automatically triggers downstream nodes
* Supports conditional termination
* Supports loop counting
* Maintains execution context
3. **Works with Other Nodes**
* AI Chat nodes
* HTTP Request nodes
* Content Extraction nodes
* Conditional nodes
## Use Cases
The **Batch Processing** node extends workflow capabilities through automation, enabling FastGPT to handle batch tasks and complex data processing pipelines. It significantly improves efficiency when processing large-scale data or scenarios requiring multiple iterations.
The **Batch Processing** node is ideal for:
1. **Batch Data Processing**
* Batch text translation
* Batch document summarization
* Batch content generation
2. **Data Pipeline Processing**
* Analyzing search results one by one
* Processing Knowledge Base retrieval results individually
* Processing array data from HTTP responses item by item
3. **Recursive or Iterative Tasks**
* Long text segmented processing
* Multi-round content refinement
* Chained data processing
## Usage
### Input Parameters
The **Batch Processing** node requires two core inputs:
1. **Array (Required)**: An array-type input, which can be:
* String array (`Array`)
* Number array (`Array`)
* Boolean array (`Array`)
* Object array (`Array