Skip to content

赵月辉 / fastgpt-migrated

Go to a project
Commit 4b244721 by Archer Committed by GitHub
Options

docs(i18n): translate final 9 files in introduction directory (#6471) 

* docs(i18n): translate batch 1

* docs(i18n): translate batch 2

* docs(i18n): translate batch 3 (20 files)

- openapi/: app, share
- faq/: all 8 files
- use-cases/: index, external-integration (5 files), app-cases (4 files)

Translated using North American style with natural, concise language.
Preserved MDX syntax, code blocks, images, and component imports.

* docs(i18n): translate protocol docs

* docs(i18n): translate introduction docs (part 1)

* docs(i18n): translate use-cases docs

* docs(i18n): translate introduction docs (part 2 - batch 1)

* docs(i18n): translate final 9 files

* fix(i18n): fix YAML and MDX syntax errors in translated files

- Add quotes to description with colon in submit_application_template.en.mdx
- Remove duplicate Chinese content in translate-subtitle-using-gpt.en.mdx
- Fix unclosed details tag issue

* docs(i18n): translate all meta.json navigation files

* fix(i18n): translate Chinese separators in meta.en.json files

* translate

* translate

* i18n

---------

Co-authored-by: archer <archer@archerdeMac-mini.local>
Co-authored-by: archer <545436317@qq.com>
parent e9eca2f8
Showing with 4328 additions and 499 deletions
.claude/settings.json 0 → 100644
{
"enabledPlugins": {
"skill-creator@claude-plugins-official": true
}
}
.claude/skills/doc-i18n/SKILL.md 0 → 100644
---
name: doc-i18n
description: 将 FastGPT 文档从中文翻译为面向北美用户的英文。当用户提到翻译文档、i18n、国际化、translate docs、新增/修改了中文文档需要同步英文版时，使用此 skill。也适用于用户要求检查文档翻译缺失、批量翻译、或对比中英文文档差异的场景。
---
## 概述
FastGPT 文档采用双文件 i18n 方案，中文为源语言，英文为目标语言。你的任务是将中文文档翻译为自然流畅的北美英文，而非逐字直译。
## 文件结构
文档位于 `document/content/docs/` 目录下：
- 内容文件：`{name}.mdx`（中文） → `{name}.en.mdx`（英文）
- 导航文件：`meta.json`（中文） → `meta.en.json`（英文）
## 工作流程
### 1. 确定翻译范围
两种方式确定需要翻译的文件：
**自动检测**（用户未指定具体文件时）：
- 运行 `git diff --name-only` 和 `git diff --cached --name-only` 检测 `document/` 下变更的中文文件
- 筛选出 `.mdx`（排除 `.en.mdx`）和 `meta.json`（排除 `meta.en.json`）
- 检查对应的英文文件是否存在或是否需要更新
**手动指定**：用户直接给出文件路径或目录。
### 2. 翻译内容文件（.mdx → .en.mdx）
对每个中文 `.mdx` 文件，生成或更新对应的 `.en.mdx` 文件。
**保持不变的部分**：
- MDX import 语句（如 `import { Alert } from '@/components/docs/Alert'`）
- 图片路径（如 `![](/imgs/intro/image1.png)`）
- 链接 URL（保持原始 URL 不变）
- HTML/JSX 组件结构和属性（如 `<Alert icon="🤖" context="success">`）
- 表格的 markdown 结构
- 代码块内容（除非是中文注释）
- emoji 符号
**需要翻译的部分**：
- frontmatter 的 `title` 和 `description`
- 所有正文文本内容
- 组件内的文本内容（如 Alert 内的文字）
- 表格中的文字内容
- 代码块中的中文注释
### 3. 翻译导航文件（meta.json → meta.en.json）
对每个中文 `meta.json`，生成或更新对应的 `meta.en.json`。
**需要翻译的字段**：`title`、`description`、分隔符字符串（如 `"---入门---"` → `"---Getting Started---"`）
**保持不变的字段**：`pages` 数组中的文件名引用、`icon`、`root`、`order`
### 4. 翻译完成后
- 列出所有已翻译的文件
- 如果发现中文文件有对应英文文件缺失的情况，提醒用户
## 翻译原则
这些原则的核心目标是让北美开发者读起来感觉像是原生英文文档，而不是翻译过来的。
### 语言风格
- 面向北美开发者，使用自然的美式英语技术写作风格
- 不要逐字翻译，要传达原文的意思和意图
- 技术文档倾向简洁直接，避免冗余修饰
- 中文文档常用的排比、铺陈手法，翻译时应精简为英文读者习惯的表达
**示例**：
```
中文：可轻松导入各式各样的文档及数据，能自动对其开展知识结构化处理工作。
✗：You can easily import various documents and data, which will be automatically processed for knowledge structuring.
✓：Import documents and data with automatic knowledge structuring.
```
### 中国特有平台和服务的本地化
直接使用国际版名称，不保留中文原名：
| 中文 | 英文 |
|------|------|
| 飞书 | Lark |
| 企业微信 | WeCom |
| 钉钉 | DingTalk |
| 公众号 | WeChat Official Account |
| 文心一言 | ERNIE Bot |
| 中国大陆版 | China Mainland |
| 国际版 | International |
### 技术术语
保持业界通用的英文术语，不要生造翻译：
| 中文 | 英文 |
|------|------|
| 知识库 | Knowledge Base |
| 工作流 | Workflow |
| 大语言模型 | LLM / Large Language Model |
| 向量存储 | Vector Store |
| 可视化编排 | Visual Orchestration |
| 低代码 | Low-code |
| 节点 | Node |
| 插件 | Plugin |
### 语气
- 保持专业但友好的语气，和原文档的风格一致
- 不要过度正式，也不要过于随意
- 面向开发者和技术用户，假设读者有基本的技术背景
.claude/skills/system-create_skill_file/templates/basic-skill-template.md deleted 100644 → 0
---
name: your-skill-name
description: Brief description of what this skill does and when to activate it. Include trigger keywords and scenarios where this skill should be used.
---
# Your Skill Title
> Brief one-line summary of what this skill accomplishes
## When to Use This Skill
- User asks to [specific action or task]
- User mentions keywords like "[keyword1]", "[keyword2]", or "[keyword3]"
- User is working with [specific technology/framework/tool]
- User needs to [specific outcome or goal]
## Quick Start
```bash
# Basic usage example
command-to-run --option value
```
## How It Works
1. **Step 1**: Brief description of first step
- Detail about what happens
- Any prerequisites or conditions
2. **Step 2**: Brief description of second step
- Key actions taken
- Expected outputs
3. **Step 3**: Brief description of final step
- Validation or verification
- Success criteria
## Examples
### Example 1: Basic Usage
**User Request**: "Example of what user might say"
**Action**: What Claude does in response
**Output**:
```
Expected output or result
```
### Example 2: Advanced Usage
**User Request**: "More complex user request"
**Action**:
1. First action taken
2. Second action taken
3. Final action
**Output**:
```
Expected output showing more complex results
```
## Best Practices
- ✅ Do this for best results
- ✅ Follow this pattern
- ❌ Avoid this common mistake
- ❌ Don't do this
## Troubleshooting
### Common Issue 1
**Problem**: Description of the problem
**Solution**: How to fix it
### Common Issue 2
**Problem**: Description of another problem
**Solution**: Steps to resolve
## References
- [Related Documentation](link-to-docs)
- [Official Guide](link-to-guide)
- [Additional Resources](link-to-resources)
---
**Version**: 1.0
**Last Updated**: YYYY-MM-DD
\ No newline at end of file
.claude/skills/system-create_skill_file/templates/workflow-skill-template.md deleted 100644 → 0
---
name: your-workflow-skill
description: Guides Claude through a multi-step workflow for [specific task]. Activates when user needs to [trigger scenario] or mentions [key terms].
---
# Your Workflow Skill Title
> Automates a complex multi-step process with decision points and validation
## When to Use This Skill
- User needs to execute a multi-step workflow
- User asks to "[workflow trigger phrase]"
- User is working on [specific type of project or task]
- Task requires validation and error handling at each step
## Workflow Overview
```
┌─────────────┐
│ Start │
└──────┬──────┘
│
▼
┌─────────────────┐
│ Preparation │
│ & Validation │
└────────┬────────┘
│
┌────▼────┐
│ Step 1 │
└────┬────┘
│
┌────▼────┐
│ Step 2 │──┐
└────┬────┘ │ (Loop if needed)
│ │
└───────┘
│
┌────▼────┐
│ Step 3 │
└────┬────┘
│
▼
┌─────────────┐
│ Complete │
│ & Report │
└─────────────┘
```
## Detailed Workflow
### Preparation Phase
Before starting the main workflow:
- [ ] Check prerequisite 1
- [ ] Validate prerequisite 2
- [ ] Ensure prerequisite 3 is met
If any prerequisite fails:
- Stop execution
- Report which prerequisite failed
- Provide remediation steps
### Step 1: [Step Name]
**Purpose**: What this step accomplishes
**Actions**:
1. Action 1
2. Action 2
3. Action 3
**Validation**:
- Check condition 1
- Verify condition 2
**On Success**: → Proceed to Step 2
**On Failure**: → [Error handling procedure]
### Step 2: [Step Name]
**Purpose**: What this step accomplishes
**Actions**:
1. Action 1
2. Action 2
**Decision Point**:
- If condition A: → Action X
- If condition B: → Action Y
- Otherwise: → Default action
**Validation**:
- Verify expected output
- Check for errors
**On Success**: → Proceed to Step 3
**On Failure**: → [Error handling procedure]
### Step 3: [Step Name]
**Purpose**: Final actions and cleanup
**Actions**:
1. Finalize changes
2. Run validation tests
3. Generate summary report
**Success Criteria**:
- All tests pass
- No errors in logs
- Expected artifacts created
## Examples
### Example 1: Standard Workflow Execution
**User Request**: "Run the [workflow name]"
**Execution**:
**Preparation Phase** ✓
```
✓ Prerequisite 1 met
✓ Prerequisite 2 validated
✓ Ready to begin
```
**Step 1: [Step Name]** ✓
```
→ Action 1 completed
→ Action 2 completed
→ Validation passed
```
**Step 2: [Step Name]** ✓
```
→ Decision: Condition A detected
→ Executing Action X
→ Validation passed
```
**Step 3: [Step Name]** ✓
```
→ Finalization complete
→ All tests passed
→ Summary generated
```
**Result**: Workflow completed successfully
### Example 2: Workflow with Error Recovery
**User Request**: "Execute [workflow name]"
**Execution**:
**Step 1** ✓
```
→ Completed successfully
```
**Step 2** ⚠️
```
→ Action 1 completed
→ Action 2 failed: [Error message]
```
**Error Recovery**:
1. Identified root cause: [Explanation]
2. Applied fix: [Fix description]
3. Retrying Step 2...
**Step 2 (Retry)** ✓
```
→ Completed after fix
```
**Step 3** ✓
```
→ Completed successfully
```
**Result**: Workflow completed with 1 retry
## Error Handling
### Error Categories
| Category | Action |
|----------|--------|
| **Recoverable** | Attempt automatic fix, retry up to 3 times |
| **User Input Needed** | Pause workflow, ask user for guidance |
| **Critical** | Stop workflow, rollback changes if possible |
### Common Errors
**Error 1: [Error Name]**
- **Cause**: What causes this error
- **Detection**: How to identify it
- **Recovery**: Steps to fix
1. Recovery action 1
2. Recovery action 2
3. Retry from failed step
**Error 2: [Error Name]**
- **Cause**: What causes this error
- **Detection**: How to identify it
- **Recovery**: Manual intervention required
- Ask user: "[Question to ask]"
- Wait for user input
- Apply user's guidance
- Resume workflow
## Rollback Procedure
If the workflow fails critically:
1. **Identify last successful step**
- Step 1: ✓ Completed
- Step 2: ❌ Failed at action 3
2. **Undo changes from failed step**
- Revert action 1
- Revert action 2
- Clean up partial state
3. **Verify system state**
- Confirm rollback successful
- Check for side effects
4. **Report to user**
```
Workflow failed at Step 2, action 3
Reason: [Error message]
All changes have been rolled back
System is back to pre-workflow state
```
## Workflow Variations
### Variation 1: Quick Mode
**When to use**: User needs faster execution, can accept lower validation
**Changes**:
- Skip optional validations
- Use cached data where available
- Reduce logging verbosity
**Trade-offs**:
- ⚡ 50% faster
- ⚠️ Less detailed error messages
### Variation 2: Strict Mode
**When to use**: Production deployments, critical changes
**Changes**:
- Enable all validations
- Require explicit user confirmation at each step
- Generate detailed audit logs
**Trade-offs**:
- 🛡️ Maximum safety
- 🐢 Slower execution
## Monitoring and Logging
Throughout the workflow:
```
[TIMESTAMP] [STEP] [STATUS] Message
[2025-01-31 14:30:01] [PREP] [INFO] Starting preparation phase
[2025-01-31 14:30:02] [PREP] [OK] All prerequisites met
[2025-01-31 14:30:03] [STEP1] [INFO] Beginning Step 1
[2025-01-31 14:30:05] [STEP1] [OK] Step 1 completed successfully
[2025-01-31 14:30:06] [STEP2] [INFO] Beginning Step 2
[2025-01-31 14:30:08] [STEP2] [WARN] Condition B detected, using fallback
[2025-01-31 14:30:10] [STEP2] [OK] Step 2 completed with warnings
[2025-01-31 14:30:11] [STEP3] [INFO] Beginning Step 3
[2025-01-31 14:30:15] [STEP3] [OK] Step 3 completed successfully
[2025-01-31 14:30:16] [COMPLETE] [OK] Workflow finished successfully
```
## Post-Workflow Report
After completion, generate a summary:
```markdown
# Workflow Execution Report
**Workflow**: [Workflow Name]
**Started**: 2025-01-31 14:30:01
**Completed**: 2025-01-31 14:30:16
**Duration**: 15 seconds
**Status**: ✓ Success
## Steps Executed
1. ✓ Preparation Phase (1s)
2. ✓ Step 1: [Step Name] (2s)
3. ✓ Step 2: [Step Name] (4s) - 1 warning
4. ✓ Step 3: [Step Name] (4s)
## Warnings
- Step 2: Condition B detected, used fallback action
## Artifacts Generated
- `/path/to/output1.txt`
- `/path/to/output2.json`
- `/path/to/report.html`
## Next Steps
- Review generated artifacts
- Deploy to production (if applicable)
- Archive logs to `/logs/workflow-20250131-143001.log`
```
## Best Practices
### Do
- ✅ Validate inputs before starting workflow
- ✅ Provide clear progress updates at each step
- ✅ Log all decisions and actions
- ✅ Handle errors gracefully with recovery options
- ✅ Generate summary report at completion
### Don't
- ❌ Skip validation steps to save time
- ❌ Continue after critical errors
- ❌ Assume prerequisites are met without checking
- ❌ Lose partial progress on failure
- ❌ Leave system in inconsistent state
## Advanced Features
### Parallel Execution
Some steps can run in parallel:
```
Step 1 ─┬─→ Step 2A ─┐
│ ├─→ Step 3
└─→ Step 2B ─┘
```
**Requirements**:
- Steps 2A and 2B must be independent
- Both must complete before Step 3
**Implementation**:
1. Start Step 2A in background
2. Start Step 2B in background
3. Wait for both to complete
4. Verify both succeeded
5. Proceed to Step 3
### Conditional Branching
```
Step 1 → Decision
├─→ [Condition A] → Path A → Step 3
├─→ [Condition B] → Path B → Step 3
└─→ [Default] → Path C → Step 3
```
## Testing This Workflow
To test the workflow without side effects:
1. Use `--dry-run` flag to simulate execution
2. Check that all steps are logged correctly
3. Verify error handling with intentional failures
4. Confirm rollback procedure works
Example:
```bash
workflow-runner --dry-run --inject-error step2
```
Expected output:
```
[DRY RUN] Step 1: Would execute [actions]
[DRY RUN] Step 2: Injected error as requested
[DRY RUN] Error Recovery: Would attempt fix
[DRY RUN] Rollback: Would undo Step 1 changes
```
---
**Version**: 1.0
**Last Updated**: YYYY-MM-DD
**Maintainer**: Team Name
\ No newline at end of file
document/content/docs/faq/app.en.mdx 0 → 100644
---
title: App Usage
description: Common questions about using FastGPT apps, including simple apps, workflows, and plugins
---
## How do I get the Question Classification node to work correctly across multi-turn conversations?
The Question Classification node has access to conversation context. When two consecutive questions are closely related, the model can usually classify them accurately based on their connection. For example, if a user asks "How do I use this feature?" followed by "What are the limitations?", the model leverages context to understand and respond correctly.
However, when consecutive questions have little relation to each other, classification accuracy may drop. To handle this, you can use a global variable to store the classification result. In subsequent classification steps, check the global variable first — if a result exists, reuse it; otherwise, let the model classify on its own.
Tip: Build batch test scripts to evaluate your question classification accuracy.
## When does scheduled execution trigger?
If a user opens a shared link and stays on the page, scheduled execution still works as expected — it takes effect after the app is published and runs in the background.
## In V4.8.18-FIX2, it says "Fixed HTTP node `{{}}` variable reference compatibility. Please switch to the / pattern for variables — `{{}}` syntax is deprecated." Does this only affect HTTP nodes, or all nodes?
Only HTTP nodes use this syntax.
## My workflow app works fine in preview but breaks after publishing to a no-login window.
This is usually caused by not publishing correctly. Click **Save and Publish** in the top-right corner of the workflow editor.
## How do I make "Suggested Questions" display in Chinese?
Make sure you're on V4.8.17 or later, then change the suggested questions prompt to Chinese.
![](/imgs/quizApp2.png)
## How do I stop AI responses from using Markdown formatting?
Edit the Knowledge Base default prompt. The built-in standard template instructs the model to use Markdown. You can remove that requirement:
| | |
| --- | --- |
| ![](/imgs/image-83.png) | ![](/imgs/image-84.png) |
## Why does my app behave differently across different sources?
Q: The app produces different results in debug mode vs. production, or when called via API.
A: This is usually caused by differences in context. Check the conversation logs, find the relevant entry, and compare the run details side by side.
| | | |
| --- | --- | --- |
| ![](/imgs/image-85.png) | ![](/imgs/image-86.png) | ![](/imgs/image-87.png) |
The Knowledge Base response settings require a custom prompt. Without one, the default prompt (which includes Markdown formatting instructions) is used.
## How do I route follow-up questions directly to the Knowledge Base instead of going through Question Classification again?
Scenario: A workflow starts with a Question Classification node that routes to different branches, each with its own Knowledge Base and AI Chat. After the first AI response, you want subsequent questions to skip classification and go straight to the Knowledge Base with chat history as context.
Solution: Add a condition check — if it's the first message (history count is 0), route through Question Classification. Otherwise, go directly to the Knowledge Base and AI Chat.
## Can I set up real-time polling to fetch webhook messages every 3000ms?
Scheduled execution doesn't support that kind of frequency. To build a real-time chatbot in WeCom, low-code workflows won't cut it — you'll need to write custom code that calls FastGPT's API Key for responses. WeCom doesn't provide an auto-listen interface for group messages (though you can trigger message pushes by @mentioning the bot). You can either send messages to the app and receive pushes via the [message callback API](https://developer.work.weixin.qq.com/document/path/90238), or poll for group messages using [this API](https://developer.work.weixin.qq.com/document/path/98914) and push responses via [this API](https://developer.work.weixin.qq.com/document/path/90248).
## Can workflows connect to a database?
Yes. Workflows support database connections. The database connection plugin can implement text-to-SQL, but it's risky — write operations are not recommended.
![](/imgs/quizApp1.png)
## How does the Loop node work?
Think of it like a `for` loop — you pass in an array, and the loop body executes once for each element. Variables inside the loop are scoped locally to each iteration.
## Formulas aren't rendering correctly
Add a prompt to guide the model to output formulas in LaTeX/Markdown format:
```bash
Latex inline: \(x^2\)
Latex block: $$e=mc^2$$
```
document/content/docs/faq/chat.en.mdx 0 → 100644
---
title: Chat Interface
description: Common FastGPT chat interface questions
---
## I updated my app in the workspace, but the chat isn't reflecting the changes?
You need to publish the app first. Chat only picks up changes after publishing.
## Browser doesn't support voice input
1. Make sure microphone permissions are enabled in both your browser and OS settings.
2. Confirm the browser has permission to use the microphone for this site, and that the correct microphone source is selected.
3. The site must have an SSL certificate for microphone access to work.
document/content/docs/faq/dataset.en.mdx 0 → 100644
---
title: Knowledge Base Usage
description: Common Knowledge Base usage questions
---
## Uploaded file content shows garbled characters
Re-save the file with UTF-8 encoding.
## What's the difference between the File Processing Model and the Index Model in Knowledge Base settings?
* **File Processing Model**: Used for **Enhanced Processing** and **Q&A Splitting** during data ingestion. Enhanced Processing generates related questions and summaries; Q&A Splitting generates question-answer pairs.
* **Index Model**: Used for vectorization — it processes and organizes text data into a structure optimized for fast retrieval.
## Does the Knowledge Base support Excel files?
Yes. You can upload xlsx and other spreadsheet formats, not just CSV.
## How are Knowledge Base tokens calculated?
All token counts use the GPT-3.5 tokenizer as the standard.
## I accidentally deleted the rerank model. How do I add it back?
![](/imgs/dataset3.png)
Add the rerank model configuration in your `config.json` file, then you'll be able to select it again.
## If I created apps and Knowledge Bases on the cloud platform, will my data be deleted if I don't renew right away?
On the free plan, Knowledge Base data is cleared after 30 days of inactivity (no login). Apps are not affected. Paid plans automatically downgrade to the free plan upon expiration.
![](/imgs/dataset4.png)
## The AI stops responding mid-answer when there are too many relevant Knowledge Base results.
FastGPT calculates the maximum response length as:
Max Response = min(Configured Max Response, Max Context Window - History)
For example, with an 18K context model, input + output share the same window. As output grows, available input shrinks.
To fix this:
1. Check your configured max response (response limit) setting.
2. Reduce input to free up space for output — specifically, reduce the number of chat history turns included in the workflow.
Where to find the max response setting:
![](/imgs/dataset1.png)
![](/imgs/dataset2.png)
For self-hosted deployments, you can reserve headroom when configuring model context limits. For example, set a 128K model to 120K — the remaining space will be allocated to output.
## I'm hitting context limit errors before reaching the configured number of chat history turns.
FastGPT calculates the maximum response length as:
Max Response = min(Configured Max Response, Max Context Window - History)
For example, with an 18K context model, input + output share the same window. As output grows, available input shrinks.
To fix this:
1. Check your configured max response (response limit) setting.
2. Reduce input to free up space for output — specifically, reduce the number of chat history turns included in the workflow.
Where to find the max response setting:
![](/imgs/dataset1.png)
![](/imgs/dataset2.png)
For self-hosted deployments, you can reserve headroom when configuring model context limits. For example, set a 128K model to 120K — the remaining space will be allocated to output.
document/content/docs/faq/error.en.mdx 0 → 100644
---
title: Errors
---
1. ### "Current group upstream load is saturated, please try again later" (request id: 202407100753411462086782835521)
This is an OneAPI channel issue. Try switching to a different model or a different relay provider.
1. ### "Connection Error" in logs when using the API
Most likely the API key is pointing to OpenAI's API, but the server is deployed in mainland China and can't reach overseas endpoints. Use a relay service or reverse proxy to resolve the connectivity issue.
document/content/docs/faq/external_channel_integration.en.mdx 0 → 100644
---
title: External Channel Integration
description: How to integrate FastGPT with external channels and platforms
---
1. ### Images don't display inline when using CoW for image-text conversations
Use prompts to instruct the model not to output in Markdown format. To display images directly, you'll need to customize CoW to extract image URLs and send them as native image messages.
1. ### Can I access user Q&A records?
Yes — check the conversation logs in your app.
![](/imgs/integration1.png)
document/content/docs/faq/index.en.mdx 0 → 100644
---
title: FAQ
description: FastGPT frequently asked questions
---
import { Redirect } from '@/components/docs/Redirect';
<Redirect to="/docs/faq/app" />
document/content/docs/faq/meta.en.json 0 → 100644
{
"root": true,
"title": "FAQ",
"description": "FastGPT FAQ",
"pages": [
"app",
"chat",
"dataset",
"external_channel_integration",
"error",
"points_consumption",
"other"
]
}
document/content/docs/faq/other.en.mdx 0 → 100644
---
title: Other Questions
---
## What's the OneAPI official website?
There's no official website — just the open-source README on GitHub: https://github.com/songquanpeng/one-api
## Is multi-user support available?
The community edition does not support multiple users. Multi-user support is only available in the commercial edition.
document/content/docs/faq/points_consumption.en.mdx 0 → 100644
---
title: Points Consumption
description: Understanding how points are consumed in FastGPT
---
1. ### I connected OneAPI, so why is FastGPT still consuming points?
Vector database searches consume points by default. Check your usage records and billing details for more information.
![](/imgs/points1.png)
document/content/docs/introduction/cloud.en.mdx 0 → 100644
---
title: FastGPT Cloud Service
description: FastGPT Cloud Service
---
## Service URLs
- [China Mainland: https://fastgpt.cn](https://fastgpt.cn)
- [International: https://fastgpt.io](https://fastgpt.io)
Register based on your needs. Accounts are not shared between the two versions.
document/content/docs/introduction/commercial.en.mdx 0 → 100644
---
title: 'FastGPT Commercial Edition'
description: 'FastGPT Commercial Edition overview'
---
import { Alert } from '@/components/docs/Alert';
## Overview
FastGPT Commercial Edition is an enhanced version built on top of the Community Edition with additional exclusive features. Simply install the commercial image and configure the internal network address on your existing Community Edition setup to get started.
## Feature Comparison
| | Community Edition | Commercial Edition | Cloud Service |
| ------------------------------ | ------------------------------------------ | ------ | ------- |
| **App Building** | | | |
| Workflow orchestration | ✅ | ✅ | ✅ |
| Share links and API | ✅ | ✅ | ✅ |
| App publishing security config | ❌ | ✅ | ✅ |
| Third-party publishing (Lark, WeChat Official Account) | ❌ | ✅ | ✅ |
| Run log dashboard | ❌ | ✅ | ✅ |
| App evaluation | ❌ | ✅ | ✅ |
| **Knowledge Base** | | | |
| Knowledge base | ✅ | ✅ | ✅ |
| Third-party knowledge base scheduled sync | ❌ | ✅ | ✅ |
| Knowledge base index enhancement | ❌ | ✅ | ✅ |
| Website sync | ❌ | ✅ | ✅ |
| Image knowledge base | ❌ | ✅ | ✅ |
| **General Features** | | | |
| Multi-model configuration | ✅ | ✅ | ✅ |
| Model log dashboard | ✅ | ✅ | ✅ |
| Model content moderation | ❌ | ✅ | ✅ |
| **Enterprise Features** | | | |
| Custom branding | ❌ | ✅ | In design |
| Multi-tenancy & billing | ❌ | ✅ | ✅ |
| Team spaces & permissions | ❌ | ✅ | ✅ |
| Admin dashboard | ❌ | ✅ | Not needed |
| SSO login | ❌ | ✅ | In design |
| Commercial license | [View open source license](/docs/protocol/open-source) | Full | Full |
## Pricing
FastGPT Commercial Edition offers 3 pricing models based on deployment type. Below are the common details for each. If you have further questions, [contact us](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc).
**Included with all plans**
1. SaaS commercial license — use for any commercial purpose during the license period.
2. Free initial deployment assistance.
3. Priority support ticket handling.
**Plan-specific features**
| Deployment Type | Included Features | Time to Launch | Starting Price |
| ---------------------- | ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| Sealos Fully Managed | 1. Free upgrades during license period.<br />2. No ops or database management needed. | Half day | Starting at ¥10,000/month (3-month minimum)<br />or<br />Starting at ¥120,000/year<br />8C32G resources; additional resources billed separately. |
| Sealos Fully Managed (Multi-node) | 1. Free upgrades during license period.<br />2. No ops or database management needed. | Half day | Starting at ¥22,000/month (3-month minimum)<br />or<br />Starting at ¥264,000/year<br />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) |
<Alert icon="🤖" context="success">
- "6 versions of upgrade support" means the FastGPT team assists with 6 upgrades — not that the software stops working after 6 versions. Most upgrades are straightforward enough to handle yourself.
- Fully managed is ideal for teams without dedicated ops staff — just focus on your business.
- Self-hosted gives you full control with deployment on your own servers.
- Single-node is suitable for small to mid-sized teams providing internal services; you'll manage database backups yourself.
- High-availability is designed for public-facing services, including visual monitoring, replicas, load balancing, and automated database backups.
</Alert>
## Contact Us
Fill out the [inquiry form](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc) and we'll get back to you shortly.
## Technical Support
### App Customization
We can build custom workflow orchestrations tailored to your needs, delivered as a complete app configuration. Pricing is negotiable based on scope.
### Technical Services (Custom Development, Maintenance, Migration, Third-party Integration)
¥2,000 – ¥3,000 per person per day
### Upgrade Fees
Most upgrades just require pulling the new image and running the initialization script — no extra steps needed.
For cross-version or complex upgrades, follow the documentation to upgrade yourself, or pay for support at the standard technical service rate.
## FAQ
### How is delivery handled?
Full application = Community Edition image + Commercial Edition image
We provide a Commercial Edition image that requires a License to start.
### How does custom development work?
You can modify the Community Edition source code, but the Commercial Edition image cannot be modified. Since the full version = Community Edition + Commercial Edition image, you can customize part of the codebase. However, if you fork the code, you'll need to handle code merges yourself during future upgrades.
### Sealos Usage Costs
Sealos cloud services use pay-as-you-go billing. Here's the pricing table:
![alt text](/imgs/image-58.png)
## Admin Dashboard Screenshots
| | | |
| ------------------------------- | ------------------------------- | ------------------------------- |
| ![alt text](/imgs/image-55.png) | ![alt text](/imgs/image-56.png) | ![alt text](/imgs/image-57.png) |
document/content/docs/introduction/development/configuration.en.mdx 0 → 100644
---
title: Configuration File Guide
description: FastGPT configuration parameters explained
---
Since environment variables aren't ideal for complex configurations, newer versions of FastGPT use ConfigMap-style mounted configuration files. You can find the default config at `projects/app/data/config.json`. See the [Docker Compose deployment guide](/docs/introduction/development/docker/) for how to mount the config file.
**In development**, copy the example config `config.json` to `config.local.json` for it to take effect.
The example below includes system parameters and model configurations:
## Config File Example (v4.8.20+)
> Starting from v4.8.20, models are configured through the UI.
```json
{
"feConfigs": {
"lafEnv": "https://laf.dev" // Laf environment. Use https://laf.run (Hangzhou Alibaba Cloud) or your private Laf instance. Laf OpenAPI requires the latest version of Laf.
},
"systemEnv": {
"vectorMaxProcess": 15, // Vector processing thread count
"qaMaxProcess": 15, // Q&A splitting thread count
"vlmMaxProcess": 15, // Vision-language model max processing threads
"tokenWorkers": 50, // Token calculation worker count — keeps memory occupied, don't set too high
"hnswEfSearch": 100, // Vector search parameter (PG and OB only). Higher = more accurate but slower. 100 gives 99%+ accuracy.
"customPdfParse": {
// Added in v4.9.0
"url": "", // Custom PDF parsing service URL
"key": "", // Custom PDF parsing service key
"doc2xKey": "", // Doc2x service key
"price": 0 // PDF parsing service price
}
}
}
```
## Custom PDF Parsing Configuration
Custom PDF parsing takes priority over Doc2x. If you're using Doc2x, don't configure a custom PDF service.
### Using Sealos PDF Parsing Service
#### 1. Get a Sealos AI Proxy API Key
[Open Sealos PDF Parser](https://hzh.sealos.run/?uid=fnWRt09fZP&openapp=system-aiproxy) and apply for an API key.
#### 2. Update FastGPT Configuration
Set `systemEnv.customPdfParse.url` to `https://aiproxy.hzh.sealos.run/v1/parse/pdf?model=parse-pdf`
Set `systemEnv.customPdfParse.key` to the API key from Sealos AI Proxy.
### Using Doc2x for PDF Parsing
`Doc2x` is a professional PDF parsing service.
#### 1. Sign Up for Doc2x
[Open Doc2x website](https://doc2x.noedgeai.com?inviteCode=9EACN2) and apply for an API key.
#### 2. Update FastGPT Configuration
Community Edition users: add `systemEnv.customPdfParse.doc2xKey` to your `config.json` with the API key, then restart the service.
Commercial Edition users: fill in the Doc2x service key in the Admin dashboard following the form instructions.
#### 3. Start Using It
When importing data to your knowledge base or configuring file uploads in your app, check `Enhanced PDF Parsing`. PDFs will then be parsed using the Doc2x service.
### Using Marker for PDF Parsing
[View the Marker integration tutorial](/docs/introduction/development/custom-models/marker)
document/content/docs/introduction/development/custom-models/bge-rerank.en.mdx 0 → 100644
---
title: Integrating bge-rerank Reranking Model
description: Integrating bge-rerank reranking model with FastGPT
---
## Recommended Configuration by Model
| Model Name | RAM | VRAM | Disk Space | Start Command |
|------|---------|---------|----------|--------------------------|
| bge-reranker-base | >=4GB | >=4GB | >=8GB | python app.py |
| bge-reranker-large | >=8GB | >=8GB | >=8GB | python app.py |
| bge-reranker-v2-m3 | >=8GB | >=8GB | >=8GB | python app.py |
## Source Code Deployment
### 1. Environment Setup
- Python 3.9 or 3.10
- CUDA 11.7
- Network access to download models
### 2. Download Code
Code repositories for the 3 models:
1. [https://github.com/labring/FastGPT/tree/main/plugins/model/rerank-bge/bge-reranker-base](https://github.com/labring/FastGPT/tree/main/plugins/model/rerank-bge/bge-reranker-base)
2. [https://github.com/labring/FastGPT/tree/main/plugins/model/rerank-bge/bge-reranker-large](https://github.com/labring/FastGPT/tree/main/plugins/model/rerank-bge/bge-reranker-large)
3. [https://github.com/labring/FastGPT/tree/main/plugins/model/rerank-bge/bge-reranker-v2-m3](https://github.com/labring/FastGPT/tree/main/plugins/model/rerank-bge/bge-reranker-v2-m3)
### 3. Install Dependencies
```sh
pip install -r requirements.txt
```
### 4. Download Models
HuggingFace repositories for the 3 models:
1. [https://huggingface.co/BAAI/bge-reranker-base](https://huggingface.co/BAAI/bge-reranker-base)
2. [https://huggingface.co/BAAI/bge-reranker-large](https://huggingface.co/BAAI/bge-reranker-large)
3. [https://huggingface.co/BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3)
Clone the model into the corresponding code directory. Directory structure:
```
bge-reranker-base/
app.py
Dockerfile
requirements.txt
```
### 5. Run
```bash
python app.py
```
On successful startup, you should see an address like this:
![](/imgs/rerank1.png)
> `http://0.0.0.0:6006` is the connection address.
## Docker Deployment
**Image names:**
1. registry.cn-hangzhou.aliyuncs.com/fastgpt/bge-rerank-base:v0.1 (4 GB+)
2. registry.cn-hangzhou.aliyuncs.com/fastgpt/bge-rerank-large:v0.1 (5 GB+)
3. registry.cn-hangzhou.aliyuncs.com/fastgpt/bge-rerank-v2-m3:v0.1 (5 GB+)
**Port**
6006
**Environment Variables**
```
ACCESS_TOKEN=your_access_token (used in request header: Authorization: Bearer ${ACCESS_TOKEN})
```
**Run Command Example**
```sh
# auth token set to mytoken
docker run -d --name reranker -p 6006:6006 -e ACCESS_TOKEN=mytoken --gpus all registry.cn-hangzhou.aliyuncs.com/fastgpt/bge-rerank-base:v0.1
```
**docker-compose.yml Example**
```
version: "3"
services:
reranker:
image: registry.cn-hangzhou.aliyuncs.com/fastgpt/bge-rerank-base:v0.1
container_name: reranker
# GPU runtime. If the host doesn't have GPU drivers installed, comment out the deploy section.
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
ports:
- 6006:6006
environment:
- ACCESS_TOKEN=mytoken
```
## Integrate with FastGPT
1. Open the FastGPT model configuration and add a new reranking model.
2. Fill in the model configuration form: set the Model ID to `bge-reranker-base` and the address to `{{host}}/v1/rerank`, where host is your deployed domain or IP:Port.
![alt text](/imgs/image-102.png)
## FAQ
### 403 Error
The custom request token in FastGPT does not match the ACCESS_TOKEN environment variable.
### Docker reports `Bus error (core dumped)`
Try adding the `shm_size` option to your `docker-compose.yml` to increase the shared memory size in the container.
```
...
services:
reranker:
...
container_name: reranker
shm_size: '2gb'
...
```
document/content/docs/introduction/development/custom-models/chatglm2-m3e.en.mdx 0 → 100644
---
title: Integrating ChatGLM2 and M3E Models
description: Integrating private ChatGLM2 and m3e-large models with FastGPT
---
## Introduction
FastGPT uses OpenAI's LLM and embedding models by default. For private deployment, you can use ChatGLM2 and m3e-large as replacements. The following method was contributed by community user @不做了睡大觉. This image bundles both M3E-Large and ChatGLM2-6B models, ready to use out of the box.
## Deploy the Image
- Image: `stawky/chatglm2-m3e:latest`
- China mirror: `registry.cn-hangzhou.aliyuncs.com/fastgpt_docker/chatglm2-m3e:latest`
- Port: 6006
```
# Set the security token (used as the channel key in OneAPI)
Default: sk-aaabbbcccdddeeefffggghhhiiijjjkkk
You can also set it via the environment variable: sk-key. Refer to Docker documentation for how to pass environment variables.
```
## Connect to OneAPI
Documentation: [One API](/docs/introduction/development/modelconfig/one-api/)
Add a channel for chatglm2 and m3e-large respectively, with the following parameters:
![](/imgs/model-m3e1.png)
Here, m3e is used as the embedding model and chatglm2 as the language model.
## Test
curl examples:
```bash
curl --location --request POST 'https://domain/v1/embeddings' \
--header 'Authorization: Bearer sk-aaabbbcccdddeeefffggghhhiiijjjkkk' \
--header 'Content-Type: application/json' \
--data-raw '{
"model": "m3e",
"input": ["What is laf"]
}'
```
```bash
curl --location --request POST 'https://domain/v1/chat/completions' \
--header 'Authorization: Bearer sk-aaabbbcccdddeeefffggghhhiiijjjkkk' \
--header 'Content-Type: application/json' \
--data-raw '{
"model": "chatglm2",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
Set Authorization to sk-aaabbbcccdddeeefffggghhhiiijjjkkk. The model field should match the custom model name you entered in One API.
## Integrate with FastGPT
Edit the config.json file. Add chatglm2 to `llmModels` and M3E to `vectorModels`:
```json
"llmModels": [
// Other chat models
{
"model": "chatglm2",
"name": "chatglm2",
"maxToken": 8000,
"price": 0,
"quoteMaxToken": 4000,
"maxTemperature": 1.2,
"defaultSystemChatPrompt": ""
}
],
"vectorModels": [
{
"model": "text-embedding-ada-002",
"name": "Embedding-2",
"price": 0.2,
"defaultToken": 500,
"maxToken": 3000
},
{
"model": "m3e",
"name": "M3E (for testing)",
"price": 0.1,
"defaultToken": 500,
"maxToken": 1800
}
],
```
## Usage
**M3E model:**
1. Select the M3E model when creating a Knowledge Base.
Note: once selected, the embedding model for the Knowledge Base cannot be changed.
![](/imgs/model-m3e2.png)
2. Import data
3. Test search
![](/imgs/model-m3e3.png)
4. Bind the Knowledge Base to an app
Note: an app can only bind Knowledge Bases that use the same embedding model -- cross-model binding is not supported. You may also need to adjust the similarity threshold, as different embedding models produce different similarity (distance) scores. Test and tune accordingly.
![](/imgs/model-m3e4.png)
**ChatGLM2 model:**
Simply select chatglm2 as the model.
document/content/docs/introduction/development/custom-models/chatglm2.en.mdx 0 → 100644
---
title: Integrating ChatGLM2-6B
description: Integrating the private ChatGLM2-6B model with FastGPT
---
import { Alert } from '@/components/docs/Alert';
## Introduction
FastGPT lets you use your own OpenAI API KEY to quickly call OpenAI APIs. It currently integrates GPT-3.5, GPT-4, and embedding models for building Knowledge Bases. However, for data security reasons, you may not want to send all data to cloud-based LLMs.
So how do you connect a private model to FastGPT? This guide walks through integrating Tsinghua's ChatGLM2 as an example.
## ChatGLM2-6B Overview
ChatGLM2-6B is the second-generation version of the open-source bilingual (Chinese-English) chat model ChatGLM-6B. For details, see the [ChatGLM2-6B project page](https://github.com/THUDM/ChatGLM2-6B).
<Alert context="warning">
Note: ChatGLM2-6B weights are fully open for academic research. Commercial use requires official written permission. This tutorial only demonstrates one integration method and does not grant any license.
</Alert>
## Recommended Configuration
According to official data, generating 8192 tokens requires 12.8GB VRAM at FP16, 8.1GB at int8, and 5.1GB at int4. Quantization slightly affects performance, but not significantly.
Recommended configurations:
| Type | RAM | VRAM | Disk Space | Start Command |
|------|---------|---------|----------|--------------------------|
| fp16 | >=16GB | >=16GB | >=25GB | python openai_api.py 16 |
| int8 | >=16GB | >=9GB | >=25GB | python openai_api.py 8 |
| int4 | >=16GB | >=6GB | >=25GB | python openai_api.py 4 |
## Deployment
### Environment Requirements
- Python 3.8.10
- CUDA 11.8
- Network access to download models
### Source Code Deployment
1. Set up the environment as described above;
2. Download the [Python file](https://github.com/labring/FastGPT/blob/main/plugins/model/llm-ChatGLM2/openai_api.py)
3. Run `pip install -r requirements.txt`;
4. Open the Python file and configure the token in the `verify_token` method -- this adds a layer of authentication to prevent unauthorized access;
5. Run `python openai_api.py --model_name 16`. Choose the number based on the configuration table above.
Wait for the model to download and load. If you encounter errors, try asking GPT for help.
On successful startup, you should see an address like this:
![](/imgs/chatglm2.png)
> `http://0.0.0.0:6006` is the connection address.
### Docker Deployment
**Image and Port**
+ Image: `stawky/chatglm2:latest`
+ China mirror: `registry.cn-hangzhou.aliyuncs.com/fastgpt_docker/chatglm2:latest`
+ Port: 6006
```
# Set the security token (used as the channel key in OneAPI)
Default: sk-aaabbbcccdddeeefffggghhhiiijjjkkk
You can also set it via the environment variable: sk-key. Refer to Docker documentation for how to pass environment variables.
```
## Connect to One API
Add a channel for chatglm2 with the following parameters:
![](/imgs/model-m3e1.png)
Here, chatglm2 is used as the language model.
## Test
curl example:
```bash
curl --location --request POST 'https://domain/v1/chat/completions' \
--header 'Authorization: Bearer sk-aaabbbcccdddeeefffggghhhiiijjjkkk' \
--header 'Content-Type: application/json' \
--data-raw '{
"model": "chatglm2",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
Set Authorization to sk-aaabbbcccdddeeefffggghhhiiijjjkkk. The model field should match the custom model name you entered in One API.
## Integrate with FastGPT
Edit the config.json file and add chatglm2 to `llmModels`:
```json
"llmModels": [
// Existing models
{
"model": "chatglm2",
"name": "chatglm2",
"maxContext": 4000,
"maxResponse": 4000,
"quoteMaxToken": 2000,
"maxTemperature": 1,
"vision": false,
"defaultSystemChatPrompt": ""
}
]
```
## Usage
Simply select chatglm2 as the model.
document/content/docs/introduction/development/custom-models/m3e.en.mdx 0 → 100644
---
title: Integrating M3E Embedding Model
description: Integrating the private M3E embedding model with FastGPT
---
## Introduction
FastGPT uses OpenAI's embedding model by default. For private deployment, you can replace it with the M3E embedding model. M3E is a lightweight model with low resource requirements -- it can even run on CPU. The following tutorial is based on an image provided by community contributor "睡大觉".
## Deploy the Image
Image: `stawky/m3e-large-api:latest`
China mirror: `registry.cn-hangzhou.aliyuncs.com/fastgpt_docker/m3e-large-api:latest`
Port: 6008
Environment variables:
```
# Set the security token (used as the channel key in OneAPI)
Default: sk-aaabbbcccdddeeefffggghhhiiijjjkkk
You can also set it via the environment variable: sk-key. Refer to Docker documentation for how to pass environment variables.
```
## Connect to One API
Add a channel with the following parameters:
![](/imgs/model-m3e1.png)
## Test
curl example:
```bash
curl --location --request POST 'https://domain/v1/embeddings' \
--header 'Authorization: Bearer xxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
"model": "m3e",
"input": ["What is laf"]
}'
```
Set Authorization to your sk-key. The model field should match the custom model name you entered in One API.
## Integrate with FastGPT
Edit the config.json file and add the M3E model to `vectorModels`:
```json
"vectorModels": [
{
"model": "text-embedding-ada-002",
"name": "Embedding-2",
"price": 0.2,
"defaultToken": 500,
"maxToken": 3000
},
{
"model": "m3e",
"name": "M3E (for testing)",
"price": 0.1,
"defaultToken": 500,
"maxToken": 1800
}
]
```
## Usage
1. Select the M3E model when creating a Knowledge Base.
Note: once selected, the embedding model for the Knowledge Base cannot be changed.
![](/imgs/model-m3e2.png)
2. Import data
3. Test search
![](/imgs/model-m3e3.png)
4. Bind the Knowledge Base to an app
Note: an app can only bind Knowledge Bases that use the same embedding model -- cross-model binding is not supported. You may also need to adjust the similarity threshold, as different embedding models produce different similarity (distance) scores. Test and tune accordingly.
![](/imgs/model-m3e4.png)
document/content/docs/introduction/development/custom-models/marker.en.mdx 0 → 100644
---
title: Integrating Marker PDF Parsing
description: Use Marker to parse PDF documents with image extraction and layout recognition
---
## Background
PDF is a relatively complex file format. FastGPT's built-in PDF parser relies on the pdfjs library, which uses logical parsing and cannot effectively handle complex PDF files. When parsing PDFs containing images, tables, formulas, or other non-plain-text content, the results are often poor.
There are several PDF parsing solutions available. [Marker](https://github.com/VikParuchuri/marker) uses the Surya model for vision-based parsing, effectively extracting images, tables, formulas, and other complex content.
Starting from `FastGPT v4.9.0`, community edition users can add the `systemEnv.customPdfParse` configuration in `config.json` to use Marker for PDF parsing. Commercial edition users can configure this directly in the Admin panel via the form. You need to pull the latest Marker image, as the API format has changed.
## Tutorial
### 1. Install Marker
Refer to the [Marker installation guide](https://github.com/labring/FastGPT/tree/main/plugins/model/pdf-marker) to install the Marker model. The bundled API is already compatible with FastGPT's custom parsing service.
Quick Docker installation:
```dockerfile
docker pull crpi-h3snc261q1dosroc.cn-hangzhou.personal.cr.aliyuncs.com/marker11/marker_images:v0.2
docker run --gpus all -itd -p 7231:7232 --name model_pdf_v2 -e PROCESSES_PER_GPU="2" crpi-h3snc261q1dosroc.cn-hangzhou.personal.cr.aliyuncs.com/marker11/marker_images:v0.2
```
### 2. Add FastGPT Configuration
```json
{
xxx
"systemEnv": {
xxx
"customPdfParse": {
"url": "http://xxxx.com/v2/parse/file", // Custom PDF parsing service URL for Marker v0.2
"key": "", // Custom PDF parsing service key
"doc2xKey": "", // doc2x service key
"price": 0 // PDF parsing service price
}
}
}
```
Restart the service after making changes.
### 3. Test
Upload a PDF file through the Knowledge Base and enable the `Enhanced PDF Parsing` option.
![alt text](/imgs/marker2.png)
After uploading, you should see the following logs (LOG_LEVEL must be set to info or debug):
```
[Info] 2024-12-05 15:04:42 Parsing files from an external service
[Info] 2024-12-05 15:07:08 Custom file parsing is complete, time: 1316ms
```
You'll notice that PDFs parsed by Marker include image links:
![alt text](/imgs/image-10.png)
Similarly, in apps you can enable `Enhanced PDF Parsing` in the file upload settings.
![alt text](/imgs/marker3.png)
## Results
Using Tsinghua's [ChatDev Communicative Agents for Software Develop.pdf](https://arxiv.org/abs/2307.07924) as an example:
| | | |
| ------------------------------- | ------------------------------- | ------------------------------- |
| ![alt text](/imgs/image-11.png) | ![alt text](/imgs/image-12.png) | ![alt text](/imgs/image-13.png) |
| ![alt text](/imgs/image-14.png) | ![alt text](/imgs/image-15.png) | ![alt text](/imgs/image-16.png) |
The top row shows chunked results; the bottom row shows the original PDF. Images, formulas, and tables are all extracted effectively.
Note that [Marker](https://github.com/VikParuchuri/marker) is licensed under `GPL-3.0 license`. Please ensure compliance with the license when using it.
## Legacy Marker Usage
For FastGPT versions before V4.9.0, you can use the following method for Marker parsing.
Install and run the Marker service:
```dockerfile
docker pull crpi-h3snc261q1dosroc.cn-hangzhou.personal.cr.aliyuncs.com/marker11/marker_images:v0.1
docker run --gpus all -itd -p 7231:7231 --name model_pdf_v1 -e PROCESSES_PER_GPU="2" crpi-h3snc261q1dosroc.cn-hangzhou.personal.cr.aliyuncs.com/marker11/marker_images:v0.1
```
Then modify the FastGPT environment variables:
```
CUSTOM_READ_FILE_URL=http://xxxx.com/v1/parse/file
CUSTOM_READ_FILE_EXTENSION=pdf
```
- CUSTOM_READ_FILE_URL - The custom parsing service URL. Replace the host with your parsing service address; the path must remain unchanged.
- CUSTOM_READ_FILE_EXTENSION - Supported file extensions. Use commas to separate multiple file types.
document/content/docs/introduction/development/custom-models/meta.en.json 0 → 100644
{
"title": "Local Model Usage",
"pages": [
"marker",
"mineru",
"xinference",
"bge-rerank",
"chatglm2",
"m3e",
"chatglm2-m3e",
"ollama"
]
}
document/content/docs/introduction/development/custom-models/mineru.en.mdx 0 → 100644
---
title: Integrating MinerU PDF Parsing
description: Use MinerU to parse PDF documents with image extraction, layout recognition, table recognition, and formula recognition
---
## Background
PDF is a relatively complex file format. FastGPT's built-in PDF parser relies on the pdfjs library, which uses logical parsing and cannot effectively handle complex PDF files. When parsing PDFs containing images, tables, formulas, or other non-plain-text content, the results are often poor.
There are several PDF parsing solutions available. [MinerU](https://github.com/opendatalab/MinerU) uses YOLO, PaddleOCR, and table recognition models for vision-based parsing, effectively extracting images, tables, formulas, and other complex content.
Community edition users can add the `systemEnv.customPdfParse` configuration in `config.json` to use MinerU for PDF parsing. Commercial edition users can configure this directly in the Admin panel via the form -- details are covered in the tutorial below.
## Tutorial
Hardware requirements: 16GB+ GPU VRAM, minimum 16GB+ RAM (32GB+ recommended). See the [official page](https://github.com/opendatalab/MinerU) for other requirements.
### 1. Install MinerU
Quick Docker installation:
Pull the fastgpt-mineru image --> Create and start the parsing service container --> Add the deployed URL to the FastGPT configuration file
```dockerfile
docker pull crpi-h3snc261q1dosroc.cn-hangzhou.personal.cr.aliyuncs.com/fastgpt_ck/mineru:v1
docker run --gpus all -itd -p 7231:8001 --name mode_pdf_minerU crpi-h3snc261q1dosroc.cn-hangzhou.personal.cr.aliyuncs.com/fastgpt_ck/mineru:v1
```
This MinerU integration uses pipeline mode with built-in parallelization inside the Docker container. It creates multiple processes based on the number of GPUs to handle uploaded PDFs concurrently.
### 2. Add FastGPT Configuration
```json
{
xxx
"systemEnv": {
xxx
"customPdfParse": {
"url": "http://xxxx.com/v2/parse/file", // Custom PDF parsing service URL for MinerU
"key": "", // Custom PDF parsing service key
"doc2xKey": "", // doc2x service key
"price": 0 // PDF parsing service price
}
}
}
```
For the commercial edition, configure as shown below:
![alt text](/imgs/mineru6.png)
**Note:** Services added via the configuration file require a restart to take effect.
### 3. Test
Upload a PDF file through the Knowledge Base and enable the `Enhanced PDF Parsing` option.
![alt text](/imgs/mineru1.png)
After uploading, you should see the following logs (LOG_LEVEL must be set to info or debug):
```
[Info] 2024-12-05 15:04:42 Parsing files from an external service
[Info] 2024-12-05 15:07:08 Custom file parsing is complete, time: 1316ms
```
Similarly, in apps you can enable `Enhanced PDF Parsing` in the file upload settings.
![alt text](/imgs/mineru2.png)
## Results
Using Tsinghua's [ChatDev Communicative Agents for Software Develop.pdf](https://arxiv.org/abs/2307.07924) as an example:
| | | |
| ------------------------------- | ------------------------------- | ------------------------------- |
| ![alt text](/imgs/mineru3-1.png) | ![alt text](/imgs/mineru4-1.png) | ![alt text](/imgs/mineru5-1.png) |
| ![alt text](/imgs/mineru3.png) | ![alt text](/imgs/mineru4.png) | ![alt text](/imgs/mineru5.png) |
The top row shows chunked results; the bottom row shows the original PDF. Images, formulas, and OCR handwriting are all extracted effectively.
Note that [MinerU](https://github.com/opendatalab/MinerU) is licensed under `GPL-3.0 license`. Please ensure compliance with the license when using it.
document/content/docs/introduction/development/custom-models/ollama.en.mdx 0 → 100644
---
title: Integrating Local Models with Ollama
description: Deploy your own models using Ollama
---
[Ollama](https://ollama.com/) is an open-source AI model deployment tool focused on simplifying the deployment and usage of large language models. It supports one-click download and running of various LLMs.
## Installing Ollama
Ollama supports multiple installation methods, but Docker is recommended. If you install Ollama directly on your host machine, you'll need to figure out how to let the FastGPT Docker container access Ollama on the host, which can be tricky.
### Docker Installation (Recommended)
Use Ollama's official Docker image for one-click installation and startup (make sure Docker is installed on your machine):
```bash
docker pull ollama/ollama
docker run --rm -d --name ollama -p 11434:11434 ollama/ollama
```
If your FastGPT is deployed in Docker, make sure the Ollama container is on the same network as FastGPT. Otherwise, FastGPT may not be able to access it:
```bash
docker run --rm -d --name ollama --network (your FastGPT container network) -p 11434:11434 ollama/ollama
```
### Host Installation
If you prefer not to use Docker, you can install directly on the host machine.
#### MacOS
If you're on macOS with Homebrew installed:
```bash
brew install ollama
ollama serve # Start the service after installation
```
#### Linux
On Linux, you can use a package manager. For Ubuntu:
```bash
curl https://ollama.com/install.sh | sh # Downloads and runs the official install script
ollama serve # Start the service after installation
```
#### Windows
On Windows, download the installer from the Ollama official website. Run the installer and follow the wizard. After installation, start the service in Command Prompt or PowerShell:
```bash
ollama serve # After installation, visit http://localhost:11434 in your browser to verify Ollama is running
```
#### Additional Notes
If you installed Ollama as a host application (not via Docker), make sure Ollama listens on 0.0.0.0.
##### 1. Linux
If Ollama runs as a systemd service, edit the service file with `sudo systemctl edit ollama.service`. Add `Environment="OLLAMA_HOST=0.0.0.0"` under the [Service] section. Save and exit, then run `sudo systemctl daemon-reload` and `sudo systemctl restart ollama` to apply.
##### 2. MacOS
Open a terminal and run `launchctl setenv ollama_host "0.0.0.0"`, then restart the Ollama application.
##### 3. Windows
Open "Edit system environment variables" from the Start menu or search bar. In "System Properties", click "Environment Variables". Under "System variables", click "New" and create a variable named OLLAMA_HOST with value 0.0.0.0. Click "OK" to save, then restart Ollama from the Start menu.
### Pull Model Images
After installing Ollama, no models are available locally -- you need to pull them:
```bash
# For Docker deployment, enter the container first: docker exec -it [Ollama container name] /bin/sh
ollama pull [model name]
```
![](/imgs/Ollama-pull.png)
### Test Communication
After installation, verify connectivity by entering the FastGPT container and trying to reach Ollama:
```bash
docker exec -it [FastGPT container name] /bin/sh
curl http://XXX.XXX.XXX.XXX:11434 # Container: "http://[container name]:[port]", Host: "http://[host IP]:[port]" (host IP cannot be localhost)
```
If you see that the Ollama service is running, communication is working.
## Integrating Ollama with FastGPT
### 1. Check Available Models
First, check which models Ollama has:
```bash
# For Docker-deployed Ollama: docker exec -it [Ollama container name] /bin/sh
ollama ls
```
![](/imgs/Ollama-models1.png)
### 2. AI Proxy Integration
If you're using FastGPT's default configuration from [here](/docs/introduction/development/docker.md), AI Proxy is enabled by default.
![](/imgs/Ollama-aiproxy1.png)
Make sure your FastGPT can access the Ollama container. If not, refer to the [installation section](#installing-ollama) above -- check whether the host isn't listening on 0.0.0.0 or the containers aren't on the same network.
![](/imgs/Ollama-aiproxy2.png)
In FastGPT, go to Account -> Model Providers -> Model Configuration -> Add Model. Make sure the model ID matches the model name in OneAPI. See details [here](/docs/introduction/development/modelConfig/intro.md).
![](/imgs/Ollama-models2.png)
![](/imgs/Ollama-models3.png)
Run FastGPT, then go to Account -> Model Providers -> Model Channels -> Add Channel. Select Ollama as the channel type, add your pulled model, and fill in the proxy address. For container-deployed Ollama, the address is http://address:port. Note: container deployment uses "http://[container name]:[port]", host installation uses "http://[host IP]:[port]" (host IP cannot be localhost).
![](/imgs/Ollama-aiproxy3.png)
Create an app in the workspace and select the model you added. The model name shown is the alias you set. Note: the same model cannot be added multiple times -- the system uses the alias from the most recent addition.
![](/imgs/Ollama-models4.png)
### 3. OneAPI Integration
If you want to use OneAPI, pull the OneAPI image and run it on the same network as FastGPT:
```bash
# Pull the OneAPI image
docker pull intel/oneapi-hpckit
# Run the container on the FastGPT network
docker run -it --network [FastGPT network] --name container_name intel/oneapi-hpckit /bin/bash
```
In the OneAPI page, add a new channel with type Ollama. Enter your Ollama model name (must match exactly), then fill in the Ollama proxy address below -- default is http://address:port, without /v1. Test the channel after adding. This example uses Docker-deployed Ollama; for host-installed Ollama, use http://[host IP]:[port].
![](/imgs/Ollama-oneapi1.png)
After adding the channel, click Token -> Add Token, fill in the name, and configure as needed.
![](/imgs/Ollama-oneapi2.png)
Edit the FastGPT docker-compose.yml file: comment out AI Proxy, set OPENAI_BASE_URL to your OneAPI address (default http://address:port/v1 -- /v1 is required), and set KEY to your OneAPI token.
![](/imgs/Ollama-oneapi3.png)
Then [jump to section 5](#5-model-addition-and-usage) to add and use models.
### 4. Direct Integration
If you don't want to use AI Proxy or OneAPI, you can connect directly. Edit the FastGPT docker-compose.yml: comment out AI Proxy code, set OPENAI_BASE_URL to your Ollama address (default http://address:port/v1 -- /v1 is required), and set KEY to any value (Ollama has no authentication by default; if you've enabled it, use the correct key). Everything else is the same as the OneAPI approach -- just add your model in FastGPT. This example uses Docker-deployed Ollama; for host-installed Ollama, use http://[host IP]:[port].
![](/imgs/Ollama-direct1.png)
After completing the setup, [click here](#5-model-addition-and-usage) to add and use models.
### 5. Model Addition and Usage
In FastGPT, go to Account -> Model Providers -> Model Configuration -> Add Model. Make sure the model ID matches the model name in OneAPI.
![](/imgs/Ollama-models2.png)
![](/imgs/Ollama-models3.png)
Create an app in the workspace and select the model you added. The model name shown is the alias you set. Note: the same model cannot be added multiple times -- the system uses the alias from the most recent addition.
![](/imgs/Ollama-models4.png)
### 6. Additional Notes
For the Ollama proxy addresses above: host-installed Ollama uses "http://[host IP]:[port]", container-deployed Ollama uses "http://[container name]:[port]".
document/content/docs/introduction/development/custom-models/xinference.en.mdx 0 → 100644
---
title: Integrating Local Models with Xinference
description: One-stop local LLM private deployment
---
[Xinference](https://github.com/xorbitsai/inference) is an open-source model inference platform. Beyond LLMs, it can also deploy Embedding and ReRank models, which are critical for enterprise-grade RAG. Xinference also provides advanced features like Function Calling and supports distributed deployment, meaning it can scale horizontally as your application usage grows.
## Installing Xinference
Xinference supports multiple inference engines as backends for different deployment scenarios. Below we introduce these backends by use case.
### 1. Server
If you're deploying LLMs on a Linux or Windows server, you can choose Transformers or vLLM as Xinference's inference backend:
- [Transformers](https://huggingface.co/docs/transformers/index): By integrating Hugging Face's Transformers library, Xinference can quickly adopt the most cutting-edge NLP models, including LLMs.
- [vLLM](https://vllm.ai/): An open-source library developed by UC Berkeley for efficiently serving LLMs. It introduces the PagedAttention algorithm for improved memory management of attention keys and values. Throughput can reach 24x that of Transformers, making vLLM suitable for production environments with high-concurrency access.
If your server has an NVIDIA GPU, refer to [this article for CUDA installation instructions](https://xorbits.cn/blogs/langchain-streamlit-doc-chat) to maximize GPU acceleration with Xinference.
#### Docker Deployment
Use Xinference's official Docker image for one-click installation and startup (make sure Docker is installed):
```bash
docker run -p 9997:9997 --gpus all xprobe/xinference:latest xinference-local -H 0.0.0.0
```
#### Direct Deployment
First, prepare a Python 3.9+ environment. We recommend installing conda first, then creating a Python 3.11 environment:
```bash
conda create --name py311 python=3.11
conda activate py311
```
Install Xinference with Transformers and vLLM as inference backends:
```bash
pip install "xinference[transformers]"
pip install "xinference[vllm]"
pip install "xinference[transformers,vllm]" # Install both
```
PyPI automatically installs PyTorch with Transformers and vLLM, but the auto-installed CUDA version may not match your environment. If so, manually install per PyTorch's [installation guide](https://pytorch.org/get-started/locally/).
Start the Xinference service:
```bash
xinference-local -H 0.0.0.0
```
Xinference starts locally on port 9997 by default. With the `-H 0.0.0.0` parameter, non-local clients can access the service via the machine's IP address.
### 2. Personal Devices
To deploy LLMs on your MacBook or personal computer, we recommend CTransformers as Xinference's inference backend. CTransformers is a C++ implementation of Transformers using GGML.
[GGML](https://ggml.ai/) is a C++ library that enables LLMs to [run on consumer hardware](https://github.com/ggerganov/llama.cpp/discussions/205). Its key feature is model quantization -- reducing weight precision to lower resource requirements. For example, representing a high-precision float (like 0.0001) requires more space than a low-precision one (like 0.1). Since LLMs must be loaded into memory for inference, you need sufficient disk space for storage and enough RAM for execution. GGML supports many quantization strategies, each offering different efficiency-performance trade-offs.
Install CTransformers as Xinference's backend:
```bash
pip install xinference
pip install ctransformers
```
Since GGML is a C++ library, Xinference uses `llama-cpp-python` for language bindings. Different hardware platforms require different compilation parameters:
- Apple Metal (MPS): `CMAKE_ARGS="-DLLAMA_METAL=on" pip install llama-cpp-python`
- Nvidia GPU: `CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python`
- AMD GPU: `CMAKE_ARGS="-DLLAMA_HIPBLAS=on" pip install llama-cpp-python`
After installation, run `xinference-local` to start the Xinference service on your Mac.
## Creating and Deploying Models (Qwen-14B Example)
### 1. Launch via WebUI
After starting Xinference, open `http://127.0.0.1:9997` in your browser to access the Xinference Web UI.
Go to the "Launch Model" tab, search for qwen-chat, select the launch parameters, then click the rocket button in the lower left of the model card to deploy. The default Model UID is qwen-chat (used to access the model later).
![](/imgs/xinference-launch-model.png)
On first launch, Xinference downloads model parameters from HuggingFace, which takes a few minutes. Model files are cached locally for subsequent launches. Xinference also supports downloading from other sources like [modelscope](https://inference.readthedocs.io/en/latest/models/sources/sources.html).
### 2. Launch via Command Line
You can also use Xinference's CLI to launch models. The default Model UID is qwen-chat.
```bash
xinference launch -n qwen-chat -s 14 -f pytorch
```
Beyond WebUI and CLI, Xinference also provides Python SDK and RESTful API. For more details, see the [Xinference documentation](https://inference.readthedocs.io/en/latest/getting_started/index.html).
## Integrate Local Models with One API
For One API deployment and setup, refer to [here](/docs/introduction/development/modelconfig/one-api/).
Add a channel for qwen1.5-chat. Set the Base URL to the Xinference service endpoint and register qwen-chat (the model's UID).
![](/imgs/one-api-add-xinference-models.jpg)
Test with this command:
```bash
curl --location --request POST 'https://[oneapi_url]/v1/chat/completions' \
--header 'Authorization: Bearer [oneapi_token]' \
--header 'Content-Type: application/json' \
--data-raw '{
"model": "qwen-chat",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
Replace [oneapi_url] with your One API address and [oneapi_token] with your One API token. The model field should match the custom model name you entered in One API.
## Integrate Local Models with FastGPT
Add the qwen-chat model to the `llmModels` section of FastGPT's `config.json`:
```json
...
"llmModels": [
{
"model": "qwen-chat", // Model name (matches the channel model name in OneAPI)
"name": "Qwen", // Display name
"avatar": "/imgs/model/Qwen.svg", // Model logo
"maxContext": 125000, // Max context length
"maxResponse": 4000, // Max response length
"quoteMaxToken": 120000, // Max quote content tokens
"maxTemperature": 1.2, // Max temperature
"charsPointsPrice": 0, // n points/1k tokens (Commercial Edition)
"censor": false, // Enable content moderation (Commercial Edition)
"vision": true, // Supports image input
"datasetProcess": true, // Use as Knowledge Base processing model (QA). At least one model must be true, or Knowledge Base will error
"usedInClassify": true, // Use for question classification (at least one must be true)
"usedInExtractFields": true, // Use for content extraction (at least one must be true)
"usedInToolCall": true, // Use for tool calling (at least one must be true)
"toolChoice": true, // Supports tool choice (used in classification, extraction, tool calling)
"functionCall": false, // Supports function calling (used in classification, extraction, tool calling. toolChoice takes priority; if false, falls back to functionCall; if still false, uses prompt mode)
"customCQPrompt": "", // Custom classification prompt (for models without tool/function calling support)
"customExtractPrompt": "", // Custom content extraction prompt
"defaultSystemChatPrompt": "", // Default system prompt for conversations
"defaultConfig": {} // Default config sent with API requests (e.g., GLM4's top_p)
}
],
...
```
Restart FastGPT to select the Qwen model in app configuration:
## ![](/imgs/fastgpt-list-models.png)
- Reference: [FastGPT + Xinference: One-Stop Local LLM Private Deployment and Application Development](https://xorbits.cn/blogs/fastgpt-weather-chat)
document/content/docs/introduction/development/design/dataset.en.mdx 0 → 100644
---
title: Dataset Design
description: FastGPT dataset file and data design
---
## Relationship Between Files and Data
In FastGPT, files are stored using MongoDB's GridFS, while the actual data is stored in PostgreSQL. Each row in PG has a `file_id` column that references the corresponding file. For backward compatibility and to support manual input and annotated data, `file_id` has some special values:
- manual: Manually entered data
- mark: Manually annotated data
Note: `file_id` is only written at data insertion time and cannot be modified afterward.
## File Import Process
1. Upload the file to MongoDB GridFS and obtain a `file_id`. The file is marked as `unused` at this point.
2. The browser parses the file to extract text and chunks.
3. Each chunk is tagged with the `file_id`.
4. Click upload: the file status changes to `used`, and the data is pushed to the mongo `training` collection to await processing.
5. The training thread pulls data from mongo, generates vectors, and inserts them into PG.
document/content/docs/introduction/development/design/design_plugin.en.mdx 0 → 100644
---
title: System Plugin Design
description: FastGPT system plugin design
---
## Background
Previously, all FastGPT features lived within the Next.js framework, organized as a Monorepo. System plugins existed as a sub-repo under FastGPT/packages/plugin.
As the user base grew, this approach revealed several limitations:
1. Although FastGPT releases weekly, system plugins had to ship alongside FastGPT, severely limiting plugin iteration speed.
2. Community contributors who wanted to add plugins had to run the entire FastGPT application and submit PRs directly to the main repo.
3. Users who wanted custom plugins had to maintain a FastGPT fork and manually handle updates and merges, increasing development complexity.
4. Due to Next.js/webpack limitations, plugins couldn't be mounted at runtime -- no hot-swapping.
## Design
We decided to extract system plugins into a separate repository:
[FastGPT-plugin](https://github.com/labring/fastgpt-plugin)
Key goals of the split:
1. Decoupling and modularization: not just system tools, but also other plugin types like Knowledge Base plugins, RAG, etc. can be hot-loaded modules.
2. Independent versioning: FastGPT-plugin can release more frequently than FastGPT, and hot-swapping enables plugin updates without a full release.
3. Lower development complexity: contributors only need to run the debug suite provided in FastGPT-plugin, without setting up the full FastGPT environment.
4. Plugin marketplace: enables a future marketplace where users can publish and discover plugins.
## Technology Stack
1. ts-rest as the RPC framework, with an SDK for the FastGPT main project to consume.
2. zod for runtime type validation.
3. bun for bundling -- each tool compiles into a single `.pkg` file for hot-swapping.
## Project Structure
- **modules**
- **tool** FastGPT system tools
- **api** API implementation logic
- **packages** System tool directory (each is a package)
- getTime
- dalle3
- ...
- **type** Type definitions
- **utils** Utilities
- **model** Model presets
- **scripts** Scripts (build, create new tools)
- **sdk**: SDK definition for external consumers, published to npm
- **runtime**: Runtime express service
- **lib**: Library files with utility functions
- **test**: Tests
For system tool structure, see [How to Develop System Plugins](/docs/introduction/guide/plugins/dev_system_tool).
## Technical Details
### ts-rest: Contract-Based API with Auto-Generated OpenAPI and Client
[ts-rest](https://ts-rest.com/) is a TypeScript RESTful API framework. After defining a contract, you can write handler logic, auto-generate OpenAPI specs, and export a typed client via createClient.
`tRPC` is a similar TypeScript RPC framework, but it uses a proprietary request format that makes integration with other tools inconvenient. ts-rest is essentially a thin wrapper around RESTful APIs and can directly generate OpenAPI specs.
### Zod Type Validation
We use zod for type validation. Zod provides runtime type checking along with advanced features like parameter transformation and object merging.
### Worker-Based Parallel Execution and Environment Isolation
To prevent plugins from interfering with each other while improving concurrency, FastGPT-plugin uses Worker threads for plugin execution. Each tool runs in an independent Worker when called, providing:
1. Environment isolation: each plugin runs in its own Worker process, so plugins don't affect each other.
2. Parallel processing: plugins can run concurrently, improving overall performance.
### Bundling with Bun
Bundling each plugin into a single `.pkg` file is a key design decision. This allows plugins to be distributed and loaded directly via network mounting.
## Future Plans
1. Visual development tools: provide visual plugin development and debugging tools to lower the barrier to entry.
2. Plugin marketplace: a marketplace where developers can publish and share plugins.
3. More plugin types: beyond system tools, expand to Knowledge Base plugins, model plugins, RAG plugins, and more.
document/content/docs/introduction/development/design/meta.en.json 0 → 100644
{
"title": "Design Solutions",
"pages": [
"dataset",
"design_plugin"
]
}
document/content/docs/introduction/development/intro.en.mdx 0 → 100644
---
title: Local Development Setup
description: Develop and debug FastGPT locally
---
import { Alert } from '@/components/docs/Alert';
import FastGPTLink from '@/components/docs/linkFastGPT';
This guide covers how to set up your development environment to build and test <FastGPTLink>FastGPT</FastGPTLink>.
## Prerequisites
Install and configure these dependencies on your machine to build <FastGPTLink>FastGPT</FastGPTLink>:
- [Git](https://git-scm.com/)
- [Docker](https://www.docker.com/)
- [Node.js v20.14.0](https://nodejs.org) (match this version closely; use [nvm](https://github.com/nvm-sh/nvm) to manage Node versions)
- [pnpm](https://pnpm.io/) recommended version 9.4.0 (current official dev environment)
We recommend developing on *nix environments (Linux, macOS, Windows WSL).
## Local Development
### 1. Fork the FastGPT Repository
Fork the [FastGPT repository](https://github.com/labring/FastGPT).
### 2. Clone the Repository
Clone your forked repository from GitHub:
```
git clone git@github.com:<your_github_username>/FastGPT.git
```
### 3. Start the Development Environment with Docker
If you're already running FastGPT locally via Docker, stop it first to avoid port conflicts.
Navigate to `FastGPT/deploy/dev` and run `docker compose up -d` to start FastGPT's dependencies:
```bash
cd FastGPT/deploy/dev
docker compose up -d
```
<Alert context="warning">
1. If you can't pull images, use the China mirror version: `docker compose -f docker-compose.cn.yml up -d`
2. For MongoDB, add the `directConnection=true` parameter to your connection string to connect to the replica set.
</Alert>
### 4. Initial Configuration
All files below are in the `projects/app` directory.
```bash
# Make sure you're in projects/app
pwd
# Should output /xxxx/xxxx/xxx/FastGPT/projects/app
```
**1. Environment Variables**
Copy `.env.template` to create `.env.local` in the same directory. Only changes in `.env.local` take effect.
See `.env.template` for variable descriptions.
If you haven't modified variables in docker-compose.yaml, the defaults in `.env.template` work as-is. Otherwise, match the values in your `yml` file.
```bash
cp .env.template .env.local
```
**2. config.json Configuration File**
Copy `data/config.json` to create `data/config.local.json`. For detailed parameters, see [Configuration Guide](/docs/introduction/development/configuration).
```bash
cp data/config.json data/config.local.json
```
This file usually doesn't need changes. Key `systemEnv` parameters:
- `vectorMaxProcess`: Max vector generation processes. Depends on database and key concurrency — for a 2c4g server, set to 10–15.
- `qaMaxProcess`: Max QA generation processes
- `vlmMaxProcess`: Max image understanding model processes
- `hnswEfSearch`: Vector search parameter (PG and OB only). Higher values = better accuracy but slower speed.
### 5. Run
See `dev.md` in the project root. The first compile may take a while — be patient.
```bash
# Run from the code root directory to install all dependencies
# If isolate-vm installation fails, see: https://github.com/laverdet/isolated-vm?tab=readme-ov-file#requirements
pwd # Should be in the code root directory
pnpm i
cd projects/app
pnpm dev
```
Next.js runs on port 3000 by default. Visit http://localhost:3000
### 6. Build
We recommend using Docker for builds.
```bash
# Without proxy
docker build -f ./projects/app/Dockerfile -t fastgpt . --build-arg name=app
# With Taobao proxy
docker build -f ./projects/app/Dockerfile -t fastgpt. --build-arg name=app --build-arg proxy=taobao
```
Without Docker, you'd need to manually execute all the run-stage commands from the `Dockerfile` (not recommended).
## Contributing to the Open Source Repository
1. Make sure your code is forked from the [FastGPT](https://github.com/labring/FastGPT) repository.
2. Keep commits small and focused — each should address one issue.
3. Submit a PR to FastGPT's main branch. The FastGPT team and community will review it with you.
If you run into issues like merge conflicts, check GitHub's [pull request tutorial](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests). Once your PR is merged, you'll be listed in the [contributors table](https://github.com/labring/FastGPT/graphs/contributors).
## QA
### System Time Anomaly
If your default timezone is `Asia/Shanghai`, system time may be incorrect in non-Linux environments. For local development, change your timezone to UTC (+0).
### Can't Connect to Local Database
1. For remote databases, check if the port is open.
2. For local databases, try changing `host` to `localhost` or `127.0.0.1`.
3. For local connections to remote MongoDB, add `directConnection=true` to connect to replica sets.
4. Use `mongocompass` for MongoDB connection testing and visual management.
5. Use `navicat` for PostgreSQL connection and management.
### sh ./scripts/postinstall.sh Permission Denied
FastGPT runs a `postinstall` script after `pnpm i` to auto-generate ChakraUI types. If you get a permission error, run `chmod -R +x ./scripts/` first, then `pnpm i`.
If that doesn't work, manually execute the contents of `./scripts/postinstall.sh`.
_On Windows, use git bash to add execute permissions and run the script._
### TypeError: Cannot read properties of null (reading 'useMemo')
Delete all `node_modules` and reinstall with Node 18 — newer Node versions may have issues. Local dev workflow:
1. Root directory: `pnpm i`
2. Copy `config.json` -> `config.local.json`
3. Copy `.env.template` -> `.env.local`
4. `cd projects/app`
5. `pnpm dev`
### Error response from daemon: error while creating mount source path 'XXX': mkdir XXX: file exists
This may be caused by leftover files from a previous container stop. Make sure all related containers are stopped, then manually delete the files or restart Docker.
## Join the Community
Having trouble? Join the Lark group to connect with developers and users.
<img
width="400px"
src="https://oss.laf.run/otnvvf-imgs/fastgpt-feishu1.png"
className="medium-zoom-image"
/>
## 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.)
<details>
<summary>Code Structure Details</summary>
```
.
├── .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
```
</details>
document/content/docs/introduction/development/meta.en.json 0 → 100644
{
"title": "Community Edition",
"description": "FastGPT Community Edition",
"icon": "🔧",
"pages": [
"sealos",
"docker",
"faq",
"intro",
"configuration",
"object-storage",
"signoz",
"modelConfig",
"custom-models",
"proxy",
"migration",
"design"
]
}
document/content/docs/introduction/development/migration/docker_db.en.mdx 0 → 100644
---
title: Docker Database Migration (Simple Method)
description: FastGPT Docker database backup and migration
---
## 1. Stop Services
```bash
docker-compose down
```
## 2. Copy Directories
Docker-deployed databases mount local directories into containers via volumes. To migrate, simply copy these directories.
`PG data`: pg/data
`Mongo data`: mongo/data
Just copy the entire pg and mongo directories to the new location.
document/content/docs/introduction/development/migration/docker_mongo.en.mdx 0 → 100644
---
title: Docker MongoDB Migration (Dump Mode)
description: FastGPT Docker MongoDB migration
---
## Author
[https://github.com/samqin123](https://github.com/samqin123)
[Related PR -- open this to discuss with the author](https://github.com/labring/FastGPT/pull/1426)
## Overview
How to use mongodump to migrate FastGPT's MongoDB from Environment A to Environment B.
Prerequisites:
- Environment A: Your existing FastGPT deployment (e.g., on Alibaba Cloud) that needs to be migrated.
- Environment B: The new FastGPT deployment (e.g., on Tencent Cloud, or a NAS like Synology/QNAP). Note: NAS deployments may require MongoDB 4.2 or 4.4, while cloud deployments support the default FastGPT MongoDB version.
- Environment C: Your local machine, used as a staging area to hold files and coordinate the transfer.
## 1. Prepare: Access Docker MongoDB [Environment A]
```
docker exec -it mongo sh
mongo -u 'username' -p 'password'
>> show dbs
```
Confirm you can see the fastgpt database and note the database name for export.
##### Preparation:
Create a temporary directory for import/export on both the container and the host, e.g., data/backup [Environment A + Environment C].
#### Create the directory in [Environment A] for the dump operation
Enter the FastGPT Docker container:
```
docker exec -it fastgpt sh
mkdir -p /data/backup
```
Once created, exported MongoDB data will appear in the `data/backup` directory under your local FastGPT installation folder (auto-synced via volume mount). If it doesn't sync automatically, you can manually create the directory and use `docker cp` to copy files out (this rarely happens).
#### Then set up the [Environment C] host directory for syncing uploaded files into the container.
Navigate to the FastGPT directory, go into the mongo folder, and create a backup subdirectory:
```
mkdir -p /fastgpt/data/backup
```
Also create a directory in the new [Environment B]:
```
mkdir -p /fastgpt/mongobackup
```
###2. Export Data from [Environment A]
Enter Environment A and use mongodump to export the MongoDB database.
#### 2.1 Export
Run mongodump to export data files to the temporary directory (data/backup).
[The export path is set to /data/backup in the command. Since the FastGPT config already has data persistence set up, the exported files will sync to the host's fastgpt/mongo/data/backup directory.]
Single command to export (run on the host, no need to enter the container):
```
docker exec -it mongo bash -c "mongodump --db fastgpt -u 'username' -p 'password' --authenticationDatabase admin --out /data/backup"
```
You can also enter the container and combine directory creation with the export:
```
1.docker exec -it fastgpt sh
2.mkdir -p /data/backup
3. mongodump --host 127.0.0.1:27017 --db fastgpt -u "username" -p "password" --authenticationDatabase admin --out /data/backup
```
##### Fallback: if files don't auto-sync, manually copy them to the host [Environment A]:
```
docker cp mongo:/data/backup [local-fastgpt-dir]:/fastgpt/data/backup>
```
2.2 For beginners, it's recommended to compress the directory and download it to your local staging environment [A -> C] for verification. This ensures you have a backup and can check file counts. Experienced users can transfer directly to the new server [A -> B].
2.2.1 Navigate to the [Environment A] source system's local fastgpt/mongo/data directory:
```
cd /usr/fastgpt/mongo/data
```
Compress the files:
```
tar -czvf ../fastgpt-mongo-backup-$(date +%Y-%m-%d).tar.gz ./
```
Download the archive to your local machine [A -> C] for verification. Experienced users can sync directly to Environment B's fastgpt data directory.
```
scp -i /Users/path/[your-pem-file] root@[cloud-server-ip]:/usr/fastgpt/mongo/fastgptbackup-2024-05-03.tar.gz /[local-path]/Downloads/fastgpt
```
Experienced users can transfer directly to the new environment:
```
scp -i /Users/path/[your-pem-file] root@[old-server-ip]:/usr/fastgpt/mongo/fastgptbackup-2024-05-03.tar.gz root@[new-server-ip]:/Downloads/fastgpt2
```
2.2 [Environment C] Verify the archive is complete. If not, re-export. Cross-environment scp transfers can occasionally lose data.
After downloading the archive to Environment C, extract it to a custom directory, e.g., user/fastgpt/mongobackup/data:
```
tar -xvzf fastgptbackup-2024-05-03.tar.gz -C user/fastgpt/mongobackup/data
```
The extracted files should be .bson files. Verify the file count matches the source. If they don't match, the new FastGPT environment will have no data after import.
<img width="1561" alt="image" src="https://github.com/labring/FastGPT/assets/103937568/cbb8a93c-5834-4a0d-be6c-c45c701f593e" />
If everything looks good, upload the archive to Environment B's designated directory (e.g., /fastgpt/mongobackup). Do not place it in fastgpt/data/ -- that directory will be cleared later, and having extra files there will cause import errors.
```
scp -rfv [local-path]/Downloads/fastgpt/fastgptbackup-2024-05-03.tar.gz root@[new-server-ip]:/Downloads/fastgpt/backup
```
## 3. Import and Restore
### 3.1. Extract the archive on the new FastGPT environment
```
tar -xvzf fastgptbackup-2024-05-03.tar.gz -C user/fastgpt/mongobackup/data
```
Verify the file count again against your earlier check.
Experienced users can use tar to verify archive integrity. The above steps are for beginners to facilitate comparison.
### 3.2 Manually copy files into the new FastGPT Docker container [Environment C]
Since the files aren't in the data/ directory, they won't auto-sync into the container. Also ensure the container's data directory is clean, or the import will fail.
```
docker cp user/fastgpt/mongobackup/data mongo:/tmp/backup
```
### 3.3 Initialize docker compose -- run it once to create the new mongo/data persistence directory
If the mongo/db directory isn't freshly initialized, mongorestore may fail. If you encounter errors, try initializing mongo.
Commands:
```
cd /fastgpt-install-dir/mongo/data
rm -rf *
```
4. Restore with mongorestore [Environment C]
Run this from the host to import in one command (you can also run it inside the container):
```
docker exec -it mongo mongorestore -u "username" -p "password" --authenticationDatabase admin /tmp/backup/ --db fastgpt
```
<img width="1668" alt="image" src="https://github.com/labring/FastGPT/assets/103937568/32c2cdb8-bf80-4d31-9269-4bf3909cf04e" />
Note: if the imported file count seems too low, the import likely failed. A failed import means you can log in to FastGPT but see no data.
5. Restart containers [Environment C]
```
docker compose restart
docker logs -f mongo # Strongly recommended: check mongo logs before logging in. If mongo has errors, the web UI will also show errors.
```
If mongo starts normally, you should see output like this (not "mongo is restarting" -- that indicates an error):
<img width="1736" alt="iShot_2024-05-09_19 21 26" src="https://github.com/labring/FastGPT/assets/103937568/94ee00db-43de-48bd-a1fc-22dfe86aaa90" />
Error state:
<img width="508" alt="iShot_2024-05-09_19 23 13" src="https://github.com/labring/FastGPT/assets/103937568/2e2afc9f-484c-4b63-93ee-1c14aef03de0" />
6. After starting the FastGPT container, log in to the web UI. If all your original data is displayed, the migration was successful.
<img width="1728" alt="iShot_2024-05-09_19 23 51" src="https://github.com/labring/FastGPT/assets/103937568/846b6157-6b6a-4468-a1d9-c44d681ebf7c" />
document/content/docs/introduction/development/migration/meta.en.json 0 → 100644
{
"title": "Migration & Backup",
"pages": [
"docker_db",
"docker_mongo"
]
}
document/content/docs/introduction/development/modelConfig/ai-proxy.en.mdx 0 → 100644
---
title: Connect Models via AI Proxy
description: Connect Models via AI Proxy
---
Starting from `FastGPT 4.8.23`, AI Proxy was introduced to further simplify model configuration.
Similar to One API, AI Proxy serves as an OpenAI API management and distribution system that provides access to all LLMs through the standard OpenAI API format, ready to use out of the box.
## Deployment
### Docker Version
The `docker-compose.yml` file already includes the AI Proxy configuration and can be used directly. [View the latest yml configuration](https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-pgvector.yml)
If upgrading from an older version, copy the AI Proxy section from the yml and add it to your existing yml file.
## How It Works
AI Proxy core modules:
1. Channel Management: Manage API keys and available model lists from various model providers.
2. Model Invocation: Select the corresponding channel based on the requested model; construct the request body according to the channel's API format and send the request; format the response into a standard format before returning.
3. Call Logs: Detailed logging of model invocations, with the ability to record input parameters and error messages on failure for easier debugging.
Workflow:
![aiproxy12](/imgs/aiproxy1.png)
## Using AI Proxy in FastGPT
AI Proxy features can be found on the `Account - Model Providers` page.
### 1. Create a Channel
On the `Model Providers` configuration page, click `Model Channels` to enter the channel configuration page.
![aiproxy1](/imgs/aiproxy-1.png)
Click "Add Channel" in the upper right corner to enter the channel configuration page.
![aiproxy2](/imgs/aiproxy-2.png)
Using Alibaba Cloud models as an example:
![aiproxy3](/imgs/aiproxy-3.png)
1. Channel Name: The display name for the channel, used for identification only;
2. Provider: The provider corresponding to the model. Different providers have different default addresses and API key formats;
3. Models: The specific models available for this channel. The system includes mainstream models by default. If the desired option is not in the dropdown, click "Add Model" to [add a custom model](/docs/introduction/development/modelconfig/intro/#add-custom-models);
4. Model Mapping: Map the model requested by FastGPT to the actual model provided. For example:
```json
{
"gpt-4o-test": "gpt-4o"
}
```
The model in FastGPT is `gpt-4o-test`, and the request to AI Proxy also uses `gpt-4o-test`. When AI Proxy sends the request upstream, the actual `model` is `gpt-4o`.
5. Proxy Address: The actual request address. The system provides default addresses for each mainstream channel. No need to fill in if no changes are required.
6. API Key: The API credentials obtained from the model provider. Note that some providers require multiple key combinations — follow the prompts to enter them.
Click "Add" to see the newly configured channel under "Model Channels".
![aiproxy4](/imgs/aiproxy-4.png)
### 2. Channel Testing
You can then test the channel to ensure the configured models are working properly.
![aiproxy5](/imgs/aiproxy-5.png)
Click "Model Test" to see the list of configured models, then click "Start Test".
![aiproxy6](/imgs/aiproxy-6.png)
After the test completes, the results and request duration for each model will be displayed.
![aiproxy7](/imgs/aiproxy-7.png)
### 3. Enable Models
Finally, in `Model Configuration`, you can enable the corresponding models to use them on the platform. For more model configuration details, see [Model Configuration](/docs/introduction/development/modelconfig/intro).
![aiproxy8](/imgs/aiproxy-8.png)
## Other Features
### Priority
Range: 1-100. Higher values are more likely to be selected first.
![aiproxy9](/imgs/aiproxy-9.png)
### Enable/Disable
In the control menu on the right side of a channel, you can enable or disable it. Disabled channels will no longer provide model services.
![aiproxy10](/imgs/aiproxy-10.png)
### Call Logs
The `Call Logs` page displays request records sent to models, including input/output tokens, request time, duration, request address, and more. Failed requests include detailed input parameters and error messages for debugging, but are only retained for 1 hour (configurable via environment variables).
![aiproxy11](/imgs/aiproxy-11.png)
## Migrating from OneAPI to AI Proxy
You can send an HTTP request from any terminal. Replace `{{host}}` with the AI Proxy address and `{{admin_key}}` with the value of `ADMIN_KEY` in AI Proxy.
The body parameter `dsn` is the MySQL connection string for OneAPI.
```bash
curl --location --request POST '{{host}}/api/channels/import/oneapi' \
--header 'Authorization: Bearer {{admin_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"dsn": "mysql://root:s5mfkwst@tcp(dbconn.sealoshzh.site:33123)/mydb"
}'
```
A successful execution returns `"success": true`.
The migration script is not fully precise — it only performs simple data mapping, primarily migrating `proxy addresses`, `models`, and `API keys`. Manual verification after migration is recommended.
document/content/docs/introduction/development/modelConfig/meta.en.json 0 → 100644
{
"title": "Model Configuration Solutions",
"pages": [
"ai-proxy",
"intro",
"one-api",
"siliconCloud",
"ppio"
]
}
document/content/docs/introduction/development/modelConfig/one-api.en.mdx 0 → 100644
---
title: Connect Models via OneAPI
description: Connect Models via OneAPI
---
FastGPT uses a model-separated deployment approach. FastGPT only supports the OpenAI model specification (models not available in OpenAI follow a more generic specification), and uses [One API](https://github.com/songquanpeng/one-api) to unify access to different model interfaces.
[One API](https://github.com/songquanpeng/one-api) is an OpenAI API management and distribution system that provides access to all LLMs through the standard OpenAI API format, ready to use out of the box.
## Relationship Between FastGPT and One API
Think of One API as a gateway. The relationship between FastGPT and One API:
![](/imgs/sealos-fastgpt.webp)
## Deployment
### Sealos Version
* Beijing region: [Deploy OneAPI](https://hzh.sealos.run/?openapp=system-template%3FtemplateName%3Done-api)
* Singapore region (GPT available): [Deploy OneAPI](https://cloud.sealos.io/?openapp=system-template%3FtemplateName%3Done-api&uid=fnWRt09fZP)
![alt text](/imgs/image-59.png)
After deployment, open the OneAPI access link to proceed with the next steps.
## OneAPI Basic Tutorial
### Concepts
1. Channels:
1. In OneAPI, a channel corresponds to one `Api Key`, which can be from GPT, Microsoft, ChatGLM, ERNIE Bot, etc. A single `Api Key` can typically call multiple models from the same provider.
2. One API routes requests to channels based on the `model` specified in the request. If a model maps to multiple channels, one is selected at random.
2. Tokens: Credentials required to access One API. You only need this single credential to access all models configured in One API. In FastGPT, you only need to configure the `baseurl` and `token` from One API. Do not set any model scope restrictions on the token, as this can cause errors.
![alt text](/imgs/image-60.png)
### General Workflow
1. Client sends a request to One API.
2. One API matches the request to a channel based on the `model` parameter (must match exactly with the models in the channel). If multiple channels match, one is selected at random (same priority).
3. One API sends the request to the actual endpoint.
4. One API returns the result to the client.
### 1. Log in to One API
![step5](/imgs/oneapi-step5.png)
### 2. Create a Channel
Add a channel in One API. Click [Add Base Models] directly — don't forget the embedding models.
![step6](/imgs/oneapi-step6.png)
### 3. Create a Token
| | |
| --- | --- |
| ![step7](/imgs/oneapi-step7.png) | ![alt text](/imgs/image-61.png) |
### 4. Adjust Account Balance
One API defaults to $200 for the root user. You can edit this as needed.
![alt text](/imgs/image-62.png)
### 5. Update FastGPT Environment Variables
With the One API token, FastGPT can send requests to One API by modifying the `baseurl` and `key`, and One API will forward them to the appropriate models. Update these two environment variables:
```bash
# Make sure to include v1. If on the same network, you can use the internal address.
OPENAI_BASE_URL=https://xxxx.cloud.sealos.io/v1
# The key below is the token provided by One API
CHAT_API_KEY=sk-xxxxxx
```
## Connect Other Models
**Example: Adding ERNIE Bot:**
### 1. Add a Model Channel in OneAPI
Select "Baidu Wenxin Qianfan" as the type.
![](/imgs/oneapi-demo1.png)
### 2. Update FastGPT Model Configuration
Open FastGPT model configuration and enable the Wenxin Qianfan model. If the model is not built-in, you can add it manually through the "Add Model" option.
![alt text](/imgs/image-103.png)
## Other Provider Integration References
This section covers tutorials for connecting various providers to OneAPI. After configuration, don't forget to enable the models in FastGPT's model configuration.
### Alibaba Qwen (Tongyi Qianwen)
Qwen is now compatible with the GPT format and can be connected directly using the OpenAI type. As shown below, select `OpenAI` as the type and fill in the Alibaba Cloud proxy address.
You can directly use Alibaba Cloud's language models and the `text-embedding-v3` embedding model (confirmed to be normalized and ready to use).
![alt text](/imgs/image-63.png)
### SiliconCloud — Open Source Model Collection
[SiliconCloud](https://cloud.siliconflow.cn/i/TR9Ym0c4) is a platform specializing in open source model inference with its own acceleration engine. It offers a wide range of models, making it ideal for low-cost testing of open source models. Integration steps:
1. [Register a SiliconCloud account](https://cloud.siliconflow.cn/i/TR9Ym0c4)
2. Go to the console and get your API key: https://cloud.siliconflow.cn/account/ak
3. Add a new OneAPI channel, select `OpenAI` as the type, set the proxy to `https://api.siliconflow.cn`, and use the API key from step 2.
![alt text](/imgs/image-64.png)
Since OneAPI doesn't include SiliconCloud model names by default, you can enter custom model names. Here's how to find the model names:
1. Open the [SiliconCloud model list](https://siliconflow.cn/zh-cn/models)
2. Click on a model to open its details.
3. Copy the model name into OneAPI.
| | | |
| --- | --- | --- |
| ![alt text](/imgs/image-65.png) | ![alt text](/imgs/image-66.png)| ![alt text](/imgs/image-67.png) |
document/content/docs/introduction/development/modelConfig/ppio.en.mdx 0 → 100644
---
title: Connect Models via PPIO LLM API
description: Connect Models via PPIO LLM API
---
import { Alert } from '@/components/docs/Alert';
FastGPT can also connect models through the PPIO LLM API.
<Alert context="warning">
The following content is adapted from [FastGPT Integration with PPIO LLM
API](https://ppinfra.com/docs/third-party/fastgpt-use) and may not always be up to date.
</Alert>
FastGPT is a platform that simplifies the entire AI development, deployment, and usage workflow into visual operations. Developers don't need to dive deep into algorithms, and users don't need to master complex technologies — it turns AI into an easy-to-use tool through a one-stop service.
PPIO Cloud provides simple and easy-to-use API interfaces that allow developers to easily call models like DeepSeek.
- For developers: No need to restructure your architecture. Complete integration for all scenarios from text generation to decision reasoning with just 3 interfaces — design AI workflows like building blocks.
- For the ecosystem: Automatically adapts resource requirements from small applications to enterprise systems, letting intelligence grow naturally with your business.
The tutorial below provides a complete integration guide (including key configuration) to help you quickly connect FastGPT with the PPIO API.
## 1. Prerequisites
(1) Get the API endpoint
Fixed at: `https://api.ppinfra.com/v3/openai/chat/completions`.
(2) Get the API Key
Log in to the PPIO Cloud console [API Key Management](https://www.ppinfra.com/settings/key-management) page and click the create button.
Use invitation code [VOJL20] when registering to receive a 50 yuan voucher.
<img
src="https://static.ppinfra.com/docs/image/llm/BKWqbzI5PoYG6qxwAPxcinQDnob.png"
alt="Create API Key"
/>
(3) Generate and save the API Key
<Alert context="warning">
Keys are stored encrypted on the server. Please save your key when it is generated. If lost, you can delete it and create a new one in the console.
</Alert>
<img
src="https://static.ppinfra.com/docs/image/llm/OkUwbbWrcoCY2SxwVMIcM2aZnrs.png"
alt="Generate API Key"
/>
<img
src="https://static.ppinfra.com/docs/image/llm/GExfbvcosoJhVKxpzKVczlsdn3d.png"
alt="Save API Key"
/>
(4) Get the model IDs you need
DeepSeek series:
- DeepSeek R1: deepseek/deepseek-r1/community
- DeepSeek V3: deepseek/deepseek-v3/community
For other model IDs, max context, and pricing, see: [Model List](https://ppinfra.com/model-api/pricing)
## 2. Deploy the Latest FastGPT to Your Local Environment
<Alert context="warning">
Please use version v4.8.22 or above. Deployment reference: [Deploy FastGPT](/docs/introduction/development/intro/)
</Alert>
## 3. Model Configuration (Choose One of the Two Methods Below)
(1) Connect PPIO models via OneAPI: Refer to the OneAPI documentation to update FastGPT environment variables. After generating a token in One API, FastGPT can send requests to One API by modifying the baseurl and key, and One API will forward them to the appropriate models. Update these two environment variables (make sure to include v1; if on the same network, you can use the internal address):
OPENAI_BASE_URL= http://OneAPI-IP:OneAPI-PORT/v1
The key below is the token provided by One API: CHAT_API_KEY=sk-UyVQcpQWMU7ChTVl74B562C28e3c46Fe8f16E6D8AeF8736e
- After restarting FastGPT, select PPIO Cloud in the model providers as shown below:
<img
src="https://static.ppinfra.com/docs/image/llm/Fvqzb3kTroys5Uxkjlzco7kwnsb.png"
alt="Select PPIO Cloud"
/>
- Test connectivity
Using DeepSeek as an example, select deepseek/deepseek-r1/community in the model list, click the position marked 2 in the image to test connectivity. A green success indicator confirms the connection is working and you can proceed with configuring conversations.
<img
src="https://static.ppinfra.com/docs/image/llm/FzKGbGsSPoX4Eexobj2cxcaTnib.png"
alt="Test Connectivity"
/>
(2) Connect PPIO models without OneAPI
Select PPIO Cloud in the model providers as shown below:
<img
src="https://static.ppinfra.com/docs/image/llm/QbcdbPqRsoAmuyx2nlycQWFanrc.png"
alt="Select PPIO Cloud"
/>
- Configure the model: Enter `https://api.ppinfra.com/v3/openai/chat/completions` in the custom request URL field.
<img
src="https://static.ppinfra.com/docs/image/llm/ZVyAbDIaxo7ksAxLI3HcexYYnZf.png"
alt="Configure Model"
/>
<img
src="https://static.ppinfra.com/docs/image/llm/Ha9YbggkwoQsVdx1Z4Gc9zUSnle.png"
alt="Configure Model"
/>
- Test connectivity
<img
src="https://static.ppinfra.com/docs/image/llm/V1f0b89uloab9uxxj7IcKT0rn3e.png"
alt="Test Connectivity"
/>
A green success indicator confirms the connection is working and you can proceed with configuring conversations.
## 4. Configure Conversations
(1) Create a new workspace
<img
src="https://static.ppinfra.com/docs/image/llm/ZaGpbBH6QoVubIx2TsLcwYEInfe.png"
alt="Create Workspace"
/>
(2) Start chatting
<img
src="https://static.ppinfra.com/docs/image/llm/HzcTb4gobokVRQxTlU7cD5OunMf.png"
alt="Start Chatting"
/>
## PPIO New User Benefits
After completing the tutorial configuration steps, you'll unlock two benefits: 1. Enjoy the combination of PPIO's high-speed channel with FastGPT's capabilities; 2. Activate the "New User Referral Reward" — invite friends to register using your exclusive invitation code, and both you and your friend will receive a 50 yuan voucher to boost your AI tool efficiency!
New user exclusive: Register now with invitation code [VOJL20] and receive a 50 yuan voucher instantly!
document/content/docs/introduction/development/modelConfig/siliconCloud.en.mdx 0 → 100644
---
title: Try Open Source Models with SiliconCloud
description: Try Open Source Models with SiliconCloud
---
[SiliconCloud](https://cloud.siliconflow.cn/i/TR9Ym0c4) is a platform focused on providing open source model inference, with its own acceleration engine. It helps users test and use open source models quickly at low cost. In our experience, their models offer solid speed and stability, with a wide variety covering language, embedding, reranking, TTS, STT, image generation, and video generation models — meeting all model requirements in FastGPT.
If you want to use SiliconCloud for only some models, see [OneAPI Integration with SiliconCloud](/docs/introduction/development/modelconfig/one-api/#siliconcloud--open-source-model-collection).
This guide covers deploying FastGPT entirely with SiliconCloud models.
## 1. Register a SiliconCloud Account
1. [Register a SiliconCloud account](https://cloud.siliconflow.cn/i/TR9Ym0c4)
2. Go to the console and get your API key: https://cloud.siliconflow.cn/account/ak
## 2. Update FastGPT Environment Variables
```bash
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
# Enter the API Key from the SiliconCloud console
CHAT_API_KEY=sk-xxxxxx
```
## 3. Update FastGPT Model Configuration
The system includes a few SiliconCloud models by default for quick testing. You can add more models manually if needed.
Here we enable `Qwen2.5 72b` for both text and vision models; `bge-m3` as the embedding model; `bge-reranker-v2-m3` as the reranking model; `fish-speech-1.5` as the TTS model; and `SenseVoiceSmall` as the STT model.
![alt text](/imgs/image-104.png)
## 4. Testing
### Test Chat and Image Recognition
Create a simple app, select the corresponding model, enable image upload, and test:
| | |
| ------------------------------- | ------------------------------- |
| ![alt text](/imgs/image-68.png) | ![alt text](/imgs/image-70.png) |
The 72B model performs quite fast. Without several 4090 GPUs locally, just the output alone would take around 30 seconds — not to mention the environment setup.
### Test Knowledge Base Import and Q&A
Create a knowledge base (since only one embedding model is configured, the embedding model selector won't appear on the page):
| | |
| ------------------------------- | ------------------------------- |
| ![alt text](/imgs/image-72.png) | ![alt text](/imgs/image-71.png) |
Import a local file — just select the file and click through the steps. 79 indexes were completed in about 20 seconds. Now let's test knowledge base Q&A.
Go back to the app we just created, select the knowledge base, adjust the parameters, and start a conversation:
| | | |
| ------------------------------- | ------------------------------- | ------------------------------- |
| ![alt text](/imgs/image-73.png) | ![alt text](/imgs/image-75.png) | ![alt text](/imgs/image-76.png) |
After the conversation, click the citation at the bottom to view citation details, including retrieval and reranking scores:
| | |
| ------------------------------- | ------------------------------- |
| ![alt text](/imgs/image-77.png) | ![alt text](/imgs/image-78.png) |
### Test Text-to-Speech
In the same app, find "Voice Playback" in the left sidebar configuration. Click to select a voice model from the popup and preview it:
![alt text](/imgs/image-79.png)
### Test Speech-to-Text
In the same app, find "Voice Input" in the left sidebar configuration. Click to enable voice input from the popup:
![alt text](/imgs/image-80.png)
Once enabled, a microphone icon appears in the chat input box. Click it to start voice input:
| | |
| ------------------------------- | ------------------------------- |
| ![alt text](/imgs/image-81.png) | ![alt text](/imgs/image-82.png) |
## Summary
If you want to quickly try open source models or get started with FastGPT without applying for API keys from multiple providers, SiliconCloud is a great option for a fast start.
If you plan to self-host models and FastGPT in the future, you can use SiliconCloud for initial testing and validation, then proceed with hardware procurement later — reducing POC time and cost.
document/content/docs/introduction/development/object-storage.en.mdx 0 → 100644
---
title: Object Storage Configuration & Common Issues
description: How to configure and connect to various object storage providers via environment variables, and common configuration issues
---
import { Alert } from '@/components/docs/Alert';
import FastGPTLink from '@/components/docs/linkFastGPT';
## Object Storage Configuration
This guide covers environment variable configuration for object storage providers supported by FastGPT, including self-hosted MinIO, AWS S3, Alibaba Cloud OSS, and Tencent Cloud COS.
### Common Required Environment Variables
> - Temporary credential authentication (e.g., STS) is not supported. Ensure service security on your own.
> - Private bucket reuse is not supported. If you set the private and public bucket names to the same value, ensure the bucket policy is at least **public read, private write**.
- `STORAGE_VENDOR` Enum value. Options: `minio`, `aws-s3`, `oss`, `cos`.
- `STORAGE_REGION` Region where the object storage service is located, e.g., `us-east-1`. Refer to your provider's region list. For self-hosted MinIO, any value works.
- `STORAGE_ACCESS_KEY_ID` Access Key ID for the service credentials
- `STORAGE_SECRET_ACCESS_KEY` Secret Access Key for the service credentials
- `STORAGE_PUBLIC_BUCKET` FastGPT public resource bucket name
- `STORAGE_PRIVATE_BUCKET` FastGPT private resource bucket name
### Self-Hosted MinIO and AWS S3
> MinIO has strong AWS S3 protocol support, so MinIO and AWS S3 configurations are nearly identical — differences come from provider-specific or self-hosted requirements.
> In theory, any object storage with S3 protocol support comparable to MinIO will work, such as SeaweedFS, RustFS, etc.
- `STORAGE_S3_ENDPOINT` Internal connection address. Can be a container ID, e.g., `http://fastgpt-minio:9000`
- `STORAGE_EXTERNAL_ENDPOINT` An address accessible by both **server** and **client** to reach the bucket. Use a fixed host IP or domain name — don't use `127.0.0.1` or `localhost` (containers can't access loopback addresses). This address is used when generating signed file upload URLs.
- `STORAGE_S3_FORCE_PATH_STYLE` [Optional] Virtual-hosted-style or path-style routing. If vendor is `minio`, this is fixed to `true`.
- `STORAGE_S3_MAX_RETRIES` [Optional] Maximum request retry attempts. Default: 3
**Complete Example**
> If using Sealos object storage, set `STORAGE_VENDOR` to `aws-s3`
```dotenv
STORAGE_VENDOR=minio
STORAGE_REGION=us-east-1
STORAGE_ACCESS_KEY_ID=your_access_key
STORAGE_SECRET_ACCESS_KEY=your_secret_key
STORAGE_PUBLIC_BUCKET=fastgpt-public
STORAGE_PRIVATE_BUCKET=fastgpt-private
STORAGE_EXTERNAL_ENDPOINT=http://127.0.0.1:9000
STORAGE_S3_ENDPOINT=http://127.0.0.1:9000
STORAGE_S3_FORCE_PATH_STYLE=true
STORAGE_S3_MAX_RETRIES=3
```
### Alibaba Cloud OSS
> - [CORS Configuration](https://help.aliyun.com/zh/oss/user-guide/configure-cross-origin-resource-sharing/?spm=5176.8466032.console-base_help.dexternal.1bcd1450Wau6J6#b58400ec36rqf)
- `STORAGE_OSS_ENDPOINT` Alibaba Cloud OSS hostname. Default is usually `{region}.aliyuncs.com`, e.g., `oss-cn-hangzhou.aliyuncs.com`. If using a custom domain, enter it here, e.g., `your-domain.com`
- `STORAGE_OSS_CNAME` Whether custom domain is enabled
- `STORAGE_OSS_SECURE` Whether TLS is enabled. Disable if your domain doesn't have a certificate.
- `STORAGE_OSS_INTERNAL` [Optional] Whether to use internal network access. Enable if your service is also on Alibaba Cloud to save bandwidth. Default: disabled
**Complete Example**
```dotenv
STORAGE_VENDOR=oss
STORAGE_REGION=oss-cn-hangzhou
STORAGE_ACCESS_KEY_ID=your_access_key
STORAGE_SECRET_ACCESS_KEY=your_secret_key
STORAGE_PUBLIC_BUCKET=fastgpt-public
STORAGE_PRIVATE_BUCKET=fastgpt-private
STORAGE_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
STORAGE_OSS_CNAME=false
STORAGE_OSS_SECURE=false
STORAGE_OSS_INTERNAL=false
```
### Tencent Cloud COS
> - [CORS Configuration](https://cloud.tencent.com/document/product/436/13318)
- `STORAGE_COS_PROTOCOL` Options: `https:`, `http:` — don't forget the `:`. If your custom domain doesn't have a certificate, don't use `https:`
- `STORAGE_COS_USE_ACCELERATE` [Optional] Enable global acceleration domain. Default: false. If true, the bucket must have global acceleration enabled.
- `STORAGE_COS_CNAME_DOMAIN` [Optional] Custom domain, e.g., `your-domain.com`
- `STORAGE_COS_PROXY` [Optional] Proxy server, e.g., `http://localhost:7897`
**Complete Example**
```dotenv
STORAGE_VENDOR=cos
STORAGE_REGION=ap-shanghai
STORAGE_ACCESS_KEY_ID=your_access_key
STORAGE_SECRET_ACCESS_KEY=your_secret_key
STORAGE_PUBLIC_BUCKET=fastgpt-public
STORAGE_PRIVATE_BUCKET=fastgpt-private
STORAGE_COS_PROTOCOL=http:
STORAGE_COS_USE_ACCELERATE=false
STORAGE_COS_CNAME_DOMAIN=
STORAGE_COS_PROXY=
```
document/content/docs/introduction/development/proxy/cloudflare.en.mdx 0 → 100644
---
title: Cloudflare Worker Proxy
description: Use Cloudflare Worker as a Proxy
---
[Reference tutorial by "不做了睡觉"](https://gravel-twister-d32.notion.site/FastGPT-API-ba7bb261d5fd4fd9bbb2f0607dacdc9e)
**Workers configuration file**
```js
const TELEGRAPH_URL = 'https://api.openai.com';
addEventListener('fetch', (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
// Security check
if (request.headers.get('auth') !== 'auth_code') {
return new Response('UnAuthorization', { status: 403 });
}
const url = new URL(request.url);
url.host = TELEGRAPH_URL.replace(/^https?:\/\//, '');
const modifiedRequest = new Request(url.toString(), {
headers: request.headers,
method: request.method,
body: request.body,
redirect: 'follow'
});
const response = await fetch(modifiedRequest);
const modifiedResponse = new Response(response.body, response);
// Add CORS headers
modifiedResponse.headers.set('Access-Control-Allow-Origin', '*');
return modifiedResponse;
}
```
**Update FastGPT environment variables**
> Don't forget to include v1!
```bash
OPENAI_BASE_URL=https://xxxxxx/v1
OPENAI_BASE_URL_AUTH=auth_code
```
document/content/docs/introduction/development/proxy/http_proxy.en.mdx 0 → 100644
---
title: HTTP Proxy
description: Use an HTTP Proxy for Routing
---
If you have a proxy tool (like [Clash](https://github.com/Dreamacro/clash) or [sing-box](https://github.com/SagerNet/sing-box)), you can use an HTTP proxy to access OpenAI. Just add these two environment variables:
```bash
AXIOS_PROXY_HOST=
AXIOS_PROXY_PORT=
```
Using Clash as an example, it's recommended to route only `api.openai.com` through the proxy and direct-connect everything else. Example configuration:
```yaml
mixed-port: 7890
allow-lan: false
bind-address: '*'
mode: rule
log-level: warning
dns:
enable: true
ipv6: false
nameserver:
- 8.8.8.8
- 8.8.4.4
cache-size: 400
proxies:
-
proxy-groups:
- { name: '♻️ Auto Select', type: url-test, proxies: [HK-V01×1.5], url: 'https://api.openai.com', interval: 3600}
rules:
- 'DOMAIN-SUFFIX,api.openai.com,♻️ Auto Select'
- 'MATCH,DIRECT'
```
Then add these two environment variables to FastGPT:
```bash
AXIOS_PROXY_HOST=127.0.0.1
AXIOS_PROXY_PORT=7890
```
document/content/docs/introduction/development/proxy/meta.en.json 0 → 100644
{
"title": "Proxy Solutions",
"description": "FastGPT private deployment proxy solutions",
"pages": [
"nginx",
"http_proxy",
"cloudflare"
]
}
document/content/docs/introduction/development/proxy/nginx.en.mdx 0 → 100644
---
title: Nginx Proxy
description: Deploy Nginx on Sealos as a Proxy
---
## Log in to Sealos
[Sealos](https://cloud.sealos.io?uid=fnWRt09fZP)
## Create an Application
Open "App Launchpad" and click "New Application":
![](/imgs/sealos3.webp)
![](/imgs/sealos4.png)
### Fill in Basic Configuration
Make sure to enable external access and copy the provided external access address.
![](/imgs/sealos5.png)
### Add Configuration File
1. Copy the configuration below. Replace the content after `server_name` with the external access address from step 2.
```nginx
user nginx;
worker_processes auto;
worker_rlimit_nofile 51200;
events {
worker_connections 1024;
}
http {
resolver 8.8.8.8;
proxy_ssl_server_name on;
access_log off;
server_names_hash_bucket_size 512;
client_header_buffer_size 64k;
large_client_header_buffers 4 64k;
client_max_body_size 50M;
proxy_connect_timeout 240s;
proxy_read_timeout 240s;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
server {
listen 80;
server_name tgohwtdlrmer.cloud.sealos.io; # Replace with the Sealos external address
location ~ /openai/(.*) {
proxy_pass https://api.openai.com/$1$is_args$args;
proxy_set_header Host api.openai.com;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# For streaming responses
proxy_set_header Connection '';
proxy_http_version 1.1;
chunked_transfer_encoding off;
proxy_buffering off;
proxy_cache off;
# For regular responses
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
}
}
}
```
2. Open Advanced Configuration.
3. Click "Add Config File".
4. File name: `/etc/nginx/nginx.conf`.
5. File value: the code you just copied.
6. Click Confirm.
![](/imgs/sealos6.png)
### Deploy the Application
After filling everything in, click "Deploy" in the upper right corner to complete deployment.
## Update FastGPT Environment Variables
1. Go to the deployed app's details and copy the external address.
> Note: This is an API address — opening it directly in a browser won't work. To verify, visit: `*.cloud.sealos.io/openai/api`. If you see `Invalid URL (GET /api)`, it's working correctly.
![](/imgs/sealos7.png)
2. Update the environment variable (this is FastGPT's environment variable, not Sealos'):
```bash
OPENAI_BASE_URL=https://tgohwtdlrmer.cloud.sealos.io/openai/v1
```
**Done!**
document/content/docs/introduction/development/sealos.en.mdx 0 → 100644
---
title: Deploy with Sealos
description: One-click FastGPT deployment using Sealos
---
import { Alert } from '@/components/docs/Alert';
## Deployment Architecture
![](/imgs/sealos-fastgpt.webp)
## Multi-Model Support
FastGPT uses the one-api project to manage model pools, supporting OpenAI, Azure, mainstream domestic models, and local models.
See: [Quick OneAPI Deployment on Sealos](/docs/introduction/development/modelconfig/one-api)
## One-Click Deployment
With Sealos, you don't need to purchase servers or domains. It supports high concurrency and dynamic scaling, and databases use KubeBlocks with far better I/O performance than simple Docker container deployments. Choose a region below based on your needs.
### Singapore Region
Singapore servers are overseas with direct access to OpenAI, but users in mainland China need a VPN. International pricing is slightly higher. Click below to deploy 👇
<a
href="https://template.cloud.sealos.io/deploy?templateName=fastgpt&uid=fnWRt09fZP"
rel="external"
target="_blank"
>
<img
src="https://cdn.jsdelivr.net/gh/labring-actions/templates@main/Deploy-on-Sealos.svg"
alt="Deploy on Sealos"
/>
</a>
### 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 👇
<a
href="https://bja.sealos.run/?openapp=system-template%3FtemplateName%3Dfastgpt&uid=fnWRt09fZP"
rel="external"
target="_blank"
>
<img
src="https://raw.githubusercontent.com/labring-actions/templates/main/Deploy-on-Sealos.svg"
alt="Deploy on Sealos"
/>
</a>
### 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.
![](/imgs/sealos1.png)
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.
![](/imgs/sealos-deploy1.jpg)
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.
![](/imgs/sealos2.png)
### 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](./modelConfig/intro/)
## 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.
![](/imgs/onSealos1.png)
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.
![](/imgs/fastgptonsealos1.png)
<Alert icon="🤖" context="success">
On Sealos, FastGPT runs 1 service and 2 databases. When pausing or deleting, handle the databases together. (You can start them during the day and pause at night to save costs.)
</Alert>
### How to Update/Upgrade FastGPT
[Upgrade script documentation](./upgrading/) — read the docs first to determine which version to upgrade to. Do not skip versions.
For example, if you're on version 4.5 and want to upgrade to 4.5.1: change the image version to v4.5.1, run the upgrade script, wait for completion, then continue upgrading. If the target version doesn't require initialization, skip it.
Upgrade steps:
1. Check the [update documentation](./upgrading/index/) to confirm the target version — avoid skipping versions.
2. Open Sealos app management
3. There are 2 apps: fastgpt, fastgpt-pro
4. Click the 3 dots on the right side of the app, then **Change**. Or click details, then **Change** in the top right.
5. Modify the image version number
![](/imgs/onsealos2.png)
6. Click **Change/Restart** to automatically pull the latest image and update
7. Run the initialization script for the corresponding version (if applicable)
### How to Get the FastGPT Access Link
Open the corresponding app and click the external access address.
![](/imgs/onsealos3.png)
### Configure a Custom Domain
Click **Change** on the app -> **Custom Domain** -> enter domain -> configure domain CNAME -> confirm -> confirm change.
![](/imgs/onsealos4.png)
### How to Modify Config Files
Open Sealos app management -> find the app -> **Change** -> scroll down to advanced configuration where you'll find config files -> add new or click an existing config file to edit -> click confirm change in the top right.
![](/imgs/onsealos5.png)
[Config file reference](./configuration/)
### Modify Site Name and Favicon
Add these environment variables to the app:
```
SYSTEM_NAME=FastGPT
SYSTEM_DESCRIPTION=
SYSTEM_FAVICON=/favicon.ico
HOME_URL=/dashboard/agent
```
SYSTEM_FAVICON can be a URL.
![](/imgs/onsealos6.png)
### Mount a Logo
Currently, the browser logo can't be fully replaced — only SVG is supported. Full replacement will be available after visual customization is implemented.
Add a mounted file with path: `/app/projects/app/public/icon/logo.svg`, with the SVG content as the value.
![](/imgs/onsealos7.png)
![](/imgs/onsealos8.png)
### Commercial Edition Config File
```
{
"license": "",
"system": {
"title": "" // System name
}
}
```
### Using OneAPI
[See OneAPI usage guide](/docs/introduction/development/modelconfig/one-api/)
document/content/docs/introduction/development/signoz.en.mdx 0 → 100644
---
title: Integrate SigNoz Service Monitoring
description: FastGPT integration with SigNoz service monitoring
---
## Introduction
[SigNoz](https://signoz.io/) is an open-source Application Performance Monitoring (APM) and observability platform that provides comprehensive service monitoring for FastGPT. Built on the OpenTelemetry standard, it collects, processes, and visualizes telemetry data from distributed systems, including tracing, metrics, and logging.
**Key Features:**
- **Distributed Tracing**: Track the complete call chain of user requests across FastGPT services
- **Performance Monitoring**: Monitor key metrics like API response times and throughput
- **Error Tracking**: Automatically capture and record system exceptions for troubleshooting
- **Log Aggregation**: Centrally collect and manage application logs with structured query support
- **Real-time Alerts**: Set alert rules based on metric thresholds to detect anomalies early
## Deploy SigNoz
You can use [SigNoz](https://signoz.io/) cloud service or self-host it. Here's how to quickly deploy SigNoz on Sealos.
1. Click the card below to deploy SigNoz with one click.
[![](/imgs/Deploy-on-Sealos.svg)](https://hzh.sealos.run/?uid=fnWRt09fZP&openapp=system-template%3FtemplateName%3Dsignoz)
2. Enable external access for SigNoz
After deployment, click **Details** in P1 to open the app details page, then click **Change** in the top right and enable the external address for port 4318 (skip this step if using internal network).
| P1 | P2 | P3 |
| --- | --- | --- |
| ![alt text](/imgs/image-112.png) | ![alt text](/imgs/image-110.png) | ![alt text](/imgs/image-111.png) |
3. Get the SigNoz access address
After the change completes, wait for the public address to be ready, copy it, and enter it in FastGPT. If using internal network, copy the internal address for port 4318 directly.
![alt text](/imgs/image-113.png)
## Configure FastGPT
1. Update FastGPT environment variables
**Log level options**: `trace` | `debug` | `info` | `warning` | `error` | `fatal`
```dotenv
LOG_ENABLE_CONSOLE=true # Enable console logging
LOG_CONSOLE_LEVEL=debug # Minimum log level for console output
LOG_ENABLE_OTEL=true # Enable OTEL log collection
LOG_OTEL_LEVEL=info # Minimum log level for OTEL collection
LOG_OTEL_SERVICE_NAME=fastgpt-client # Service name passed to the OTLP collector
LOG_OTEL_URL=http://localhost:4318/v1/logs # Your OTLP collector address — don't omit /v1/logs
```
2. Restart FastGPT
## Verify the Setup
Go back to the Sealos app management list, open the SigNoz frontend project, and access its public address to open the dashboard.
| | |
| --- | --- |
| ![alt text](/imgs/image-114.png) | ![alt text](/imgs/image-115.png) |
First-time access requires creating an account (data is stored in the local database) — fill in anything.
![alt text](/imgs/image-116.png)
After logging in, if `logs` and `traces` are lit up in the COMPLETED steps on the right side, the configuration is successful.
![alt text](/imgs/image-117.png)
![alt text](/imgs/image-118.png)
## Notes
1. Adjust log retention period
SigNoz monitoring is very disk-intensive. First, avoid storing FastGPT debug logs in SigNoz. Also consider setting the log retention period to 7 days. If SigNoz data stops growing while memory keeps increasing, the disk is full — expand capacity.
![alt text](/imgs/image-119.png)
document/content/docs/introduction/guide/DialogBoxes/htmlRendering.en.mdx 0 → 100644
---
title: Dialog Boxes & HTML Rendering
description: How to embed HTML code blocks in FastGPT via Markdown, with fullscreen, source code toggle, and other interactive features
---
| Source Mode | Preview Mode | Fullscreen Mode |
| --- | --- | --- |
| ![](/imgs/htmlRendering1.png) | ![](/imgs/htmlRendering2.png) | ![](/imgs/htmlRendering3.png) |
### 1. Design Background
While Markdown natively supports embedded HTML tags, many platforms restrict HTML rendering for security reasons -- especially for dynamic content, interactive elements, and external resources. These restrictions limit flexibility when authoring complex documents that need embedded HTML. To address this, FastGPT uses `iframe` to embed and render HTML content, combined with the `sandbox` attribute to ensure safe rendering.
### 2. Feature Overview
This module extends FastGPT's Markdown rendering to support embedded HTML content. Since rendering uses an iframe, the content height cannot be determined automatically, so FastGPT sets a fixed height for the iframe. JavaScript execution within the HTML is not supported.
### 3. Technical Implementation
This module implements HTML rendering and interactivity through:
- **Component Design:** The module displays HTML content via `iframe`-type code blocks using a custom `IframeBlock` component. The `sandbox` attribute ensures embedded content security by restricting behaviors like script execution and form submissions. Helper functions integrate with the Markdown renderer to handle `iframe`-embedded HTML content.
- **Security Mechanism:** The `iframe`'s `sandbox` attribute and `referrerPolicy` prevent potential security risks. The `sandbox` attribute provides fine-grained control, allowing specific capabilities (scripts, forms, popups, etc.) to run in a restricted environment so rendered HTML cannot compromise the system.
- **Display & Interaction:** Users can switch between display modes (fullscreen, preview, source code) for flexible viewing and control of embedded HTML. The `iframe` adapts to the parent container's width while ensuring content displays properly.
### 4. How to Use
Simply use a Markdown code block with the language set to `html`. For example:
```md
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Welcome to FastGPT</title>
</head>
<body>
<nav>
<ul>
<li><a href="#home">Home</a></li>
<li><a href="#about">About Us</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#gallery">Gallery</a></li>
</ul>
</nav>
</body>
</html>
```
```
document/content/docs/introduction/guide/DialogBoxes/meta.en.json 0 → 100644
{
"title": "Dialog Boxes",
"description": "Dialog box components that support multiple interaction methods to enhance user experience in applications.",
"pages": [
"htmlRendering",
"quoteList"
]
}
document/content/docs/introduction/guide/DialogBoxes/quoteList.en.mdx 0 → 100644
---
title: Knowledge Base Chunk Reader
description: FastGPT Chunk Reader feature overview
---
In enterprise AI deployments, the accuracy and transparency of document citations have always been a key concern. The Knowledge Base Chunk Reader introduced in FastGPT 4.9.1 solves this pain point, making AI citations no longer a "black box."
# Why a Chunk Reader?
In traditional AI conversations, when a model cites content from an enterprise knowledge base, users typically only see the cited fragment without the full context. This makes content verification and deeper understanding difficult. The Chunk Reader lets users view the complete source document directly within the conversation and jump to the exact citation location, bringing true explainability to AI citations.
## Limitations of Traditional Citations
Previously, after uploading documents to the knowledge base, traditional citations only displayed the matched chunks with no way to see the surrounding context:
| Question | Citation |
| --- | --- |
| ![](/imgs/chunkReader1.png) | ![](/imgs/chunkReader2.jpg) |
## FastGPT Chunk Reader: Precise Positioning, Seamless Reading
With FastGPT's Chunk Reader, the same knowledge base content and questions are presented in a fundamentally better way:
![](/imgs/chunkReader4.jpg)
When AI cites knowledge base content, click the citation link to open a popup showing the full original text with the cited passage clearly highlighted. This ensures traceability while providing a convenient reading experience.
# Core Features
## Full-Text Display & Positioning
The Chunk Reader lets users see exactly where AI responses draw from in the knowledge base.
In the conversation interface, when AI cites knowledge base content, source information appears below the reply. Click any citation link to open a popup with the complete original text and the cited passage highlighted.
This design ensures answer traceability and makes it easy to verify AI accuracy and review surrounding context.
![](/imgs/chunkReader3.webp)
## Citation Navigation
The top-right corner of the Chunk Reader provides simple navigation controls for switching between multiple citations. The navigation area displays the current citation index and total count (e.g., "7/10"), so you always know your browsing progress.
![](/imgs/chunkReader5.jpg)
## Citation Quality Scoring
Each citation includes a relevance score label showing its ranking among all matched knowledge fragments. Hover over the label to see full scoring details, including why the citation was selected and how its relevance score breaks down.
![](/imgs/chunkReader6.png)
## One-Click Document Export
The Chunk Reader includes a content export feature so valuable information is never lost. Users with read access to the knowledge base can save the full cited document to their local device with a single click.
![](/imgs/chunkReader7.jpg)
# Advanced Features
## Flexible Visibility Control
FastGPT provides flexible citation visibility settings to balance openness and security. For example, with anonymous share links, administrators can precisely control what external visitors can see.
When set to "citation content only," external users clicking a citation link will only see the specific cited text fragments, not the full source document. The Chunk Reader automatically adjusts its display mode accordingly.
| | |
| --- | --- |
| ![](/imgs/chunkReader8.png) | ![](/imgs/chunkReader9.jpg) |
## Instant Annotation
While browsing, authorized users can annotate and correct citation content in real time. The system processes updates without interrupting the conversation. Modified content is clearly marked with an "Updated" label, maintaining both citation accuracy and conversation history integrity.
This seamless knowledge refinement workflow is ideal for team collaboration, allowing the knowledge base to evolve during actual use so AI responses always draw from the latest, most accurate sources.
## Smart Document Performance
For real-world scenarios with ultra-long documents containing thousands of chunks, FastGPT uses advanced performance optimization to keep the Chunk Reader responsive.
The system manages loading intelligently based on citation relevance ranking and database indexing, implementing on-demand rendering -- only content the user actually needs to view is loaded into memory. Whether jumping to a specific citation or scrolling through a document, the experience stays smooth regardless of document size.
This optimization lets FastGPT handle enterprise-scale knowledge bases efficiently, even for professional documents with massive amounts of content.
document/content/docs/introduction/guide/admin/meta.en.json 0 → 100644
{
"title": "Commercial Admin",
"description": "Commercial admin usage tutorial",
"pages": [
"sso",
"teamMode"
]
}
document/content/docs/introduction/guide/admin/teamMode.en.mdx 0 → 100644
---
title: Team Mode
description: FastGPT Team Mode Documentation
---
## Overview
Currently supported team modes:
1. Multi-team mode (default)
2. Single-team mode (one global team)
3. Member sync mode (all members synced from external systems)
<table className="table-hover table-striped-columns" style={{ textAlign: 'center' }}>
<thead>
<tr>
<th rowSpan="2" className="text-center">Team Mode</th>
<th colSpan="2" className="text-center">SMS/Email Registration</th>
<th colSpan="2" className="text-center">Admin Direct Add</th>
<th colSpan="2" className="text-center">SSO Registration</th>
</tr>
<tr>
<th className="text-center">Creates Default Team</th>
<th className="text-center">Joins Root Team</th>
<th className="text-center">Creates Default Team</th>
<th className="text-center">Joins Root Team</th>
<th className="text-center">Creates Default Team</th>
<th className="text-center">Joins Root Team</th>
</tr>
</thead>
<tbody >
<tr>
<td className="text-center">Single-team Mode</td>
<td className="text-center">❌</td>
<td className="text-center">✅</td>
<td className="text-center">❌</td>
<td className="text-center">✅</td>
<td className="text-center">❌</td>
<td className="text-center">✅</td>
</tr>
<tr>
<td className="text-center">Multi-team Mode</td>
<td className="text-center">✅</td>
<td className="text-center">❌</td>
<td className="text-center">✅</td>
<td className="text-center">❌</td>
<td className="text-center">✅</td>
<td className="text-center">❌</td>
</tr>
<tr>
<td className="text-center">Sync Mode</td>
<td className="text-center">❌</td>
<td className="text-center">❌</td>
<td className="text-center">❌</td>
<td className="text-center">❌</td>
<td className="text-center">❌</td>
<td className="text-center">✅</td>
</tr>
</tbody>
</table>
### Multi-team Mode (Default)
In multi-team mode, a default team owned by the user is automatically created when each user is created.
### Single-team Mode
Single-team mode is a new feature introduced in v4.9. To simplify personnel and resource management for enterprises, when single-team mode is enabled, new users no longer get their own default team — instead, they are added to the root user's team.
### Sync Mode
When system configuration is complete and sync mode is enabled, members from external member systems are automatically synced to FastGPT.
For specific sync methods and rules, see [SSO & External Member Sync](/docs/introduction/guide/admin/sso.md).
## Configuration
In `fastgpt-pro`'s System Configuration - Member Configuration, you can configure the team mode.
![](/imgs/teammode.png)
document/content/docs/introduction/guide/course/ai_settings.en.mdx 0 → 100644
---
title: AI Configuration Parameters
description: FastGPT AI configuration parameters explained
---
import { Alert } from '@/components/docs/Alert';
The AI Chat module in FastGPT includes an advanced configuration section with various model parameters. This guide explains what each setting does.
| | | |
| --- | --- | --- |
| ![alt text](/imgs/image-51.png) | ![alt text](/imgs/image-52.png) | ![alt text](/imgs/image-53.png) |
## Stream Response (Workflow AI Chat only)
Previously called "Return AI Content," now renamed to "Stream Response."
This is a toggle. When enabled, the AI Chat module streams its output to the browser (API response) in real time. When disabled, the model is called in non-streaming mode and the output is not sent to the browser. However, the generated content can still be accessed via the [AI Reply] output and connected to other modules for further use.
### Max Context
The maximum number of tokens the model can handle.
### Function Calling
Models that support function calling are more accurate when using tools.
### Temperature
Lower values produce more focused, deterministic responses (in practice, the difference is subtle).
### Max Output Tokens
The maximum number of tokens in the response. Note: this is the response token limit, not the context token limit.
Typically: max output = min(model's max output limit, max context - used context)
Because of this, you generally don't set max context to the model's actual maximum — instead, reserve space for the response. For example, a 128k model might use max_context=115000.
### System Prompt
Placed at the beginning of the context array with role `system` to guide the model's behavior.
### Memory Rounds (Basic Mode only)
Configures how many conversation rounds the model retains. If the context exceeds the model's limit, the system automatically truncates to stay within bounds.
So even if you set 30 rounds, the actual number at runtime may be fewer.
## Citation Template & Citation Prompt
After a Knowledge Base search, you can customize how search results are formatted into prompts. This setting is only available in the AI Chat node within workflows, and only takes effect when Knowledge Base content is referenced.
![alt text](/imgs/image-54.png)
### AI Chat Message Structure
To use these two variables effectively, you need to understand the message format sent to the AI model. It's an array structured as follows in FastGPT:
```json
[
Built-in prompt (from config.json, usually empty)
System prompt (user-defined prompt)
Chat history
Question (composed of citation prompt, citation template, and user question)
]
```
<Alert icon="🍅" context="success">
Tip: Click the context button to view the full context composition for easier debugging.
</Alert>
### Citation Template and Prompt Design
This feature has been removed from Basic Mode and is only configurable in workflows. Click the `settings icon` next to the Knowledge Base citation in the `AI Chat node` to configure it. As models improve, this feature will gradually become less critical.
Citation templates and citation prompts typically work as a pair — the citation prompt depends on the citation template.
FastGPT stores Knowledge Base data in QA pairs (not necessarily in question-answer format — just two variables). When converting to strings, the data is formatted according to the **citation template**. Available variables include: q, a, sourceId (data ID), index (nth entry), source (collection/file name), and score (distance score, 0-1). Reference them as needed using `{{q}}` `{{a}}` `{{sourceId}}` `{{index}}` `{{source}}` `{{score}}`. Here's an example:
See [Knowledge Base Structure](/docs/introduction/guide/knowledge_base/dataset_engine/) for details on how the Knowledge Base is structured.
#### Citation Template
```
{instruction:"{{q}}",output:"{{a}}",source:"{{source}}"}
```
Search results automatically replace q, a, and source with the corresponding content. Each result is separated by `\n`. For example:
```
{instruction:"Who directed the movie 'Suzume'?",output:"The movie 'Suzume' was directed by Makoto Shinkai.",source:"Manual input"}
{instruction:"Who is the protagonist?",output:"The protagonist is a girl named Suzume.",source:""}
{instruction:"Who is the male lead in 'Suzume'?",output:"The male lead in 'Suzume' is Souta Munakata, voiced by Hokuto Matsumura.",source:""}
{instruction:"Who wrote the screenplay for 'Suzume'?",output:"Makoto Shinkai wrote the screenplay.",source:"Manual input"}
```
#### Citation Prompt
The citation template must be used together with a citation prompt. The prompt can describe the template format and specify conversation requirements. Use `{{quote}}` to insert the **citation template** content, and `{{question}}` to insert the question. For example:
```
Your background knowledge:
"""
{{quote}}
"""
Conversation requirements:
1. The background knowledge is up-to-date. "instruction" provides relevant context, and "output" is the expected answer or supplement.
2. Use the background knowledge to answer questions.
3. If the background knowledge cannot answer the question, respond politely.
My question is: "{{question}}"
```
After substitution:
```
Your background knowledge:
"""
{instruction:"Who directed the movie 'Suzume'?",output:"The movie 'Suzume' was directed by Makoto Shinkai.",source:"Manual input"}
{instruction:"Who is the protagonist?",output:"The protagonist is a girl named Suzume.",source:""}
{instruction:"Who is the male lead in 'Suzume'?",output:"The male lead in 'Suzume' is Souta Munakata, voiced by Hokuto Matsumura}
"""
Conversation requirements:
1. The background knowledge is up-to-date. "instruction" provides relevant context, and "output" is the expected answer or supplement.
2. Use the background knowledge to answer questions.
3. If the background knowledge cannot answer the question, respond politely.
My question is: "{{question}}"
```
#### Summary
The citation template defines how each search result is formatted into a string, composed of variables like q, a, index, and source.
The citation prompt combines the `citation template` with `instructions` that typically describe the template format and specify requirements for the model.
### Citation Template and Prompt Design Examples
#### General Template vs. QA Template
We compared the general template and QA template using a set of "Who are you?" manual data entries. We intentionally included a humorous answer — under the general template, GPT-3.5 became less compliant, while under the QA template it still answered correctly. This is because structured prompts provide stronger guidance for LLMs.
<Alert icon="🍅" context="success">
Tip: For best results, use only one data type per Knowledge Base for each scenario to maximize prompt effectiveness.
</Alert>
| General template config & results | QA template config & results |
| --- | --- |
| ![](/imgs/datasetprompt1.jpg) | ![](/imgs/datasetprompt2.jpg) |
| ![](/imgs/datasetprompt3.jpg) | ![](/imgs/datasetprompt5.jpg) |
| ![](/imgs/datasetprompt4.jpg) | ![](/imgs/datasetprompt6.jpg) |
#### Strict Template
With a non-strict template, asking about something not in the Knowledge Base typically causes the model to answer from its own knowledge.
| Non-strict template results | Selecting strict template | Strict template results |
| --- | --- | --- |
| ![](/imgs/datasetprompt7.webp) | ![](/imgs/datasetprompt8.jpg) |![](/imgs/datasetprompt9.jpg) |
#### Prompt Design Tips
1. Use numbered lists for different requirements.
2. Use sequencing words like "first," "then," and "finally."
3. When listing requirements for different scenarios, be thorough. For example, cover all three cases: the background knowledge fully answers the question, partially answers it, or is unrelated.
4. Leverage structured prompts — for instance, in the QA template, `instruction` and `output` clearly tell the model that `output` is the expected answer.
5. Use correct and complete punctuation.
document/content/docs/introduction/guide/course/chat_input_guide.en.mdx 0 → 100644
---
title: Chat Input Guide
description: FastGPT chat input guide
---
![](/imgs/questionGuide.png)
## What is Custom Question Guidance?
You can preset questions for your app. As users type, the system dynamically searches these questions based on their input and displays them as suggestions, helping users ask questions faster.
You can configure the question list directly in FastGPT or provide a custom API endpoint.
## Custom Question List API
The endpoint must be accessible from the user's browser.
**Request:**
```bash
curl --location --request GET 'http://localhost:3000/api/core/chat/inputGuide/query?appId=663c75302caf8315b1c00194&searchKey=you'
```
Where `appId` is the application ID and `searchKey` is the search keyword (max 50 characters).
**Response**
```json
{
"code": 200,
"statusText": "",
"message": "",
"data": [
"it's you",
"who are you",
"you're great",
"hello there",
"who are you!",
"hello"
]
}
```
`data` is an array of matched questions. Return at most 5 results.
**Parameters:**
- appId - Application ID
- searchKey - Search keyword
document/content/docs/introduction/guide/course/fileInput.en.mdx 0 → 100644
---
title: File Input
description: FastGPT file input feature overview
---
Starting from version 4.8.9, FastGPT supports configuring file and image uploads in both `Basic Mode` and `Workflows`. This guide covers how to use the file input feature and explains how document parsing works under the hood.
## Using in Basic Mode
When file upload is enabled in Basic Mode, it uses tool-calling mode — the model decides whether to read the file content.
Find the file upload option on the left panel and click the `Enable`/`Disable` toggle to open the configuration dialog.
![Enable file upload](/imgs/fileinpu-1.png)
Once enabled, a file selection icon appears in the chat input area. Click it to select files for upload.
![Enable file upload](/imgs/fileinpu-2.png)
**Behavior**
Starting from version 4.8.13, Basic Mode forces file parsing and injects the content into the system prompt, preventing cases where the model skips reading the file during multi-turn conversations.
## Using in Workflows
In Workflows, find the `File Input` option in the system configuration panel and click the `Enable`/`Disable` toggle to open the configuration dialog.
![Enable file upload](/imgs/fileinpu-4.jpg)
There are many ways to use files in Workflows. The simplest approach, shown below, connects document parsing via tool calling — achieving the same result as Basic Mode.
| | |
| --------------------- | --------------------- |
| ![](/imgs/image-5.png) | ![](/imgs/image-6.png) |
You can also use Workflows to extract or analyze document content, then pass the results to HTTP requests or other modules to build a document processing pipeline.
![Document parsing](/imgs/image-7.png)
## How Document Parsing Works
Unlike image recognition, LLMs currently cannot parse documents directly. All document "understanding" is achieved by converting documents to text and injecting it into the prompt. The following FAQs explain how this works — understanding the mechanics helps you use document parsing more effectively in Workflows.
### How are uploaded files stored in the database?
In FastGPT's chat history, messages with role=user store their value in this structure:
```ts
type UserChatItemValueItemType = {
type: 'text' | 'file'
text?: {
content: string;
};
file?: {
type: 'img' | 'doc'
name?: string;
url: string;
};
};
```
Uploaded images and documents are stored as URLs — the parsed document content is not stored.
### How are images handled?
The document parsing node does not process images. Image URLs are filtered out. For image recognition, use an LLM that supports vision.
### How does the document parsing node work?
The document parsing node accepts an `array<string>` input (file URLs) and outputs a `string` (the parsed content).
* The node only parses URLs with document-type file extensions. If you upload both documents and images, images are ignored.
* **The document parsing node only processes files from the current workflow run, not files from chat history.**
* How multiple documents are concatenated:
Multiple files are concatenated using the following template — filename + content, separated by `\n******\n`:
```
File: ${filename}
<Content>
${content}
</Content>
```
### How to use document parsing in AI nodes
AI nodes (AI Chat / Tool Calling) have a document URL input that lets you reference document addresses directly.
It accepts an `Array<string>` input. The URLs are parsed and injected into a system message using this prompt template:
```
Use the content in <FilesContent></FilesContent> as reference for this conversation:
<FilesContent>
{{quote}}
</FilesContent>
```
# Changes to File Upload in Version 4.8.13
There are some differences from version 4.8.9. We've maintained backward compatibility to avoid breaking existing workflows, but please update your workflows to follow the new rules as soon as possible — compatibility code will be removed in future versions.
1. Basic Mode now forces file parsing instead of letting the model decide, ensuring documents are always referenced.
2. Document parsing: no longer parses files from chat history.
3. Tool Calling: supports direct document reference selection — no need to attach a document parsing tool. Automatically parses files from chat history.
4. AI Chat: supports direct document reference selection — no need to go through the document parsing node. Automatically parses files from chat history.
5. Standalone plugin execution: no longer supports global files. Plugin inputs now support file-type configuration as a replacement for global file upload.
6. **Workflow calling plugins: uploaded files are no longer automatically passed to plugins. You must manually specify the variable for plugin input.**
7. **Workflow calling sub-workflows: uploaded files are no longer automatically passed to sub-workflows. You can manually select which file URLs to pass.**
document/content/docs/introduction/guide/course/meta.en.json 0 → 100644
{
"title": "Basic Tutorial",
"description": "FastGPT basic tutorial",
"pages": [
"quick-start",
"ai_settings",
"chat_input_guide",
"fileInput"
]
}
document/content/docs/introduction/guide/course/quick-start.en.mdx 0 → 100644
---
title: Quick Start
description: Get started with FastGPT basics
---
For more tips, [watch the video tutorial](https://www.bilibili.com/video/BV1sH4y1T7s9)
## Knowledge Base
Before you begin, prepare a test document — Word, PDF, TXT, Excel, or Markdown all work. For example, a company leave policy, non-confidential sales scripts, or product documentation.
We'll use the FastGPT Chinese README file as an example.
First, create a Knowledge Base.
![](/imgs/create-rep.png)
After creating the Knowledge Base, upload some content.
There are four upload modes:
- Manual Input: Enter QA pairs manually — the most precise method
- QA Split: Upload a text file and let AI generate QA pairs automatically
- Direct Chunking: Upload a text file and split it into segments directly
- CSV Import: Batch import QA pairs
Here we'll use QA Split to let AI generate QA pairs automatically. You can edit them manually later if the quality isn't satisfactory.
![](/imgs/upload-data.png)
After uploading, wait for processing to complete until the file status shows as available.
![](/imgs/upload-data2.png)
## Application
Click the "Application" button to create a new app. There are four templates — select "Knowledge Base + Chat Guide."
![](/imgs/create-app.png)
After creating the app, go to the detail page, find the "Knowledge Base" section, and add the Knowledge Base you just created.
![](/imgs/create-app2.png)
After adding the Knowledge Base, click "Save and Preview" to link your app with the Knowledge Base.
![](/imgs/create-app3.png)
Now you're ready to start chatting.
![](/imgs/create-app4.png)
document/content/docs/introduction/guide/dashboard/basic-mode.en.mdx 0 → 100644
---
title: Basic Mode
description: A quick overview of FastGPT Dashboard's Basic Mode
---
document/content/docs/introduction/guide/dashboard/evaluation.en.mdx 0 → 100644
---
title: 'App Evaluation (Beta)'
description: 'A quick overview of FastGPT app evaluation'
---
Starting from FastGPT v4.11.0, batch app evaluation is supported. By providing multiple QA pairs, the system automatically scores your app's responses, enabling quantitative assessment of app performance.
The system supports three evaluation metrics: answer accuracy, question relevance, and semantic accuracy. The current beta only includes answer accuracy — the remaining metrics will be added in future releases.
## Create an App Evaluation
### Go to the Evaluation Page
![Create app evaluation](/imgs/evaluation1.png)
Navigate to the App Evaluation section under Workspace and click the "Create Task" button in the upper right corner.
### Fill in Evaluation Details
![Create app evaluation](/imgs/evaluation2.png)
On the task creation page, provide the following:
- **Task Name**: A label to identify this evaluation
- **Evaluation Model**: The model used for scoring
- **Target App**: The app to be evaluated
### Prepare Evaluation Data
![Create app evaluation](/imgs/evaluation2.png)
After selecting the target app, a button appears to download the CSV template. The template includes these fields:
- Global variables
- q (question)
- a (expected answer)
- Chat history
**Notes:**
- Maximum of 1,000 QA pairs
- Follow the template format when filling in data
Upload the completed file and click "Start Evaluation" to create the task.
## View Evaluation Results
### Evaluation List
![View app evaluation](/imgs/evaluation4.png)
The evaluation list shows all tasks with key information:
- **Progress**: Current execution status
- **Created By**: The user who created the task
- **Target App**: The app being evaluated
- **Start/End Time**: Execution time range
- **Overall Score**: The task's aggregate score
Use this to compare results across iterations as you improve your app.
### Evaluation Details
![View app evaluation](/imgs/evaluation5.png)
Click "View Details" to open the detail page:
**Task Overview**: The top section shows overall task information, including evaluation configuration and summary statistics.
**Detailed Results**: The bottom section lists each QA pair with its score, showing:
- User question
- Expected output
- App output
document/content/docs/introduction/guide/dashboard/gapier.en.mdx 0 → 100644
---
title: Import Agent Tools with Gapier
description: Quickly import Agent tools into FastGPT using Gapier
---
FastGPT V4.7 introduced tool calling, compatible with GPTs Actions. This means you can directly import GPTs-compatible Agent tools.
Gapier is an online GPTs Actions platform offering 50+ ready-made tools with a daily free quota for testing. Official site: [https://gapier.com/](https://gapier.com/).
![](/imgs/gapierToolResult1.webp)
Let's walk through importing Gapier tools into FastGPT.
## 1. Create a Plugin
| Step1 | Step2 | Step3 |
| --- | --- | --- |
| ![](/imgs/gapierTool1.png) | ![](/imgs/gapierTool2.png) | Log in to [Gapier](https://gapier.com/) and copy the relevant parameters <br/> ![](/imgs/gapierTool3.png) |
| Step4 | Step5 | Step6 |
| Custom request header: Authorization<br/>Value: Bearer your_copied_key <br/> ![](/imgs/gapierTool4.png) | ![](/imgs/gapierTool5.png) | ![](/imgs/gapierTool6.png) |
After creation, if you need to make changes, there's no need to recreate — just modify the parameters and the system will automatically detect and apply the differences.
![](/imgs/gapierTool7.png)
## 2. Bind Tools to an Application
### Basic Mode
| Step1 | Step2 |
| --- | --- |
| ![](/imgs/gapierTool8.png) | ![](/imgs/gapierTool9.webp) |
| Step3 | Step4 |
| ![](/imgs/gapierTool10.webp) | ![](/imgs/gapierTool11.png) |
### Advanced Workflow
| Step1 | Step2 |
| --- | --- |
| ![](/imgs/gapierTool12.webp) | ![](/imgs/gapierTool13.webp) |
| Step3 | Step4 |
| ![](/imgs/gapierTool14.webp) | ![](/imgs/gapierTool15.webp) |
![](/imgs/gapierTool16.webp)
## 3. Tool Calling Notes
### Differences Between Models
Different models use different methods for tool calling. Models that support toolChoice and functionCall produce better results. Models without these capabilities fall back to prompt-based calling, which is less reliable. To ensure smooth operation, FastGPT's built-in prompts only support calling one tool at a time.
Check the official documentation to see which models support functionCall (OneAPI support is also required), and adjust the corresponding fields in the model configuration file (see the configuration field reference for details).
Cloud version users can see whether function calling is supported when selecting a model.
![](/imgs/gapierTool17.webp)
document/content/docs/introduction/guide/dashboard/intro.en.mdx 0 → 100644
---
title: Workflows & Plugins
description: A quick overview of FastGPT Workflows and Plugins
---
Starting from V4.0, FastGPT adopted a new approach to building AI applications. It uses Flow node orchestration (Workflows) to implement complex processes, improving flexibility and extensibility. This does raise the learning curve — users with development experience will find it easier to pick up.
[Watch the video tutorial](https://www.bilibili.com/video/BV1is421u7bQ/)
![](/imgs/flow-intro1.png)
## What is a Node?
In programming terms, a node is like a function or API endpoint — think of it as a **step**. By connecting multiple nodes together, you build a step-by-step process that produces the final AI output.
Below is the simplest AI conversation, consisting of a Workflow Start node and an AI Chat node.
![](/imgs/flow-intro2.png)
Execution flow:
1. The user inputs a question. The [Workflow Start] node executes and saves the user's question.
2. The [AI Chat] node executes. It has two required parameters: "Chat History" and "User Question." Chat history defaults to 6 messages, representing the context length. The user question comes from the [Workflow Start] node.
3. The [AI Chat] node calls the conversation API with the chat history and user question to generate a response.
### Node Categories
Functionally, nodes fall into 2 categories:
1. **System Nodes**: User guidance (configures dialog information) and user question (workflow entry point).
2. **Function Nodes**: Knowledge Base search, AI Chat, and all other nodes. These have inputs and outputs and can be freely combined.
### Node Components
Each node has 3 core parts: inputs, outputs, and triggers.
![](/imgs/flow-intro3.png)
- AI model, prompt, chat history, user question, and Knowledge Base citation are inputs. Inputs can be manual entries or variable references, which include "global variables" and outputs from any previous node.
- New context and AI reply content are outputs. Outputs can be referenced by any subsequent node.
- Each node has four "triggers" (top, bottom, left, right) for connections. Connected nodes execute sequentially based on conditions.
## Key Concept — How Workflows Execute
FastGPT Workflows start from the [Workflow Start] node, triggered when the user inputs a question. There is no **fixed exit point** — the workflow ends when all nodes stop running. If no nodes execute in a given cycle, the workflow completes.
Let's look at how workflows execute and when each node is triggered.
![](/imgs/flow-intro1.png)
As shown above, nodes can "be connected to" and "connect to other nodes." We call incoming connections "predecessor lines" and outgoing connections "successor lines." In the example, the [Knowledge Base Search] node has one predecessor line on the left and one successor line on the right. The [AI Chat] node only has a predecessor line on the left.
Lines in FastGPT Workflows have these states:
- `waiting`: The connected node is waiting to execute.
- `active`: The connected node is ready to execute.
- `skip`: The connected node should be skipped.
Node execution rules:
1. If any predecessor line has `waiting` status, the node waits.
2. If any predecessor line has `active` status, the node executes.
3. If no predecessor lines are `waiting` or `active`, the node is skipped.
4. After execution, successor lines are updated to `active` or `skip`, and predecessor lines reset to `waiting` for the next cycle.
Walking through the example:
1. [Workflow Start] completes and sets its successor line to `active`.
2. [Knowledge Base Search] sees its predecessor line is `active`, executes, then sets its successor line to `active` and predecessor line to `waiting`.
3. [AI Chat] sees its predecessor line is `active` and executes. The workflow ends.
## How to Connect Nodes
1. Each node has connection points on all four sides for convenience. Left and top are predecessor connection points; right and bottom are successor connection points.
2. Click the x in the middle of a connection line to delete it.
3. Left-click to select a connection line.
## How to Read Workflows
1. Read from left to right.
2. Start from the **User Question** node, which represents the user sending text to trigger the workflow.
3. Focus on [AI Chat] and [Specified Reply] nodes — these are where answers are output.
## FAQ
### How do I merge multiple outputs?
1. Text Processing: can merge strings together.
2. Knowledge Base Search Merge: can combine multiple Knowledge Base search results.
3. Other results: cannot be merged directly. Consider passing them to an `HTTP` node for merging. Use [Laf](https://laf.run/) to quickly create a serverless HTTP endpoint.
document/content/docs/introduction/guide/dashboard/mcp_server.en.mdx 0 → 100644
---
title: MCP Server
description: A quick overview of FastGPT MCP Server
---
## What is MCP Server?
MCP (Model Context Protocol) was released by Anthropic in early November 2024. It standardizes communication between AI models and external systems, simplifying integration. With OpenAI officially supporting MCP, more and more AI vendors are adopting the protocol.
MCP has two main components: Client and Server. The Client is the AI model consumer — it uses MCP Client to give the model the ability to call external systems. The Server provides and runs those external system integrations.
FastGPT's MCP Server feature lets you select `multiple` applications built on FastGPT and expose them via MCP protocol for external consumption.
Currently, FastGPT's MCP Server uses the SSE transport protocol, with plans to migrate to `HTTP Streamable` in the future.
## Using MCP Server in FastGPT
### 1. Create an MCP Server
After logging into FastGPT, open `Workspace` and click `MCP Server` to access the management page. Here you can see all your MCP Servers and the number of applications each one manages.
![Create MCP server](/imgs/mcp_server1.png)
You can customize the MCP Server name and select which applications to associate.
| | |
|---|---|
| ![](/imgs/mcp_server2.png) | ![](/imgs/mcp_server3.png) |
### 2. Get the MCP Server URL
After creating an MCP Server, click `Start Using` to get the access URL.
| | |
|---|---|
| ![](/imgs/mcp_server4.png) | ![](/imgs/mcp_server5.png) |
#### 3. Use the MCP Server
Use the URL in any MCP-compatible client to call your FastGPT applications — for example, `Cursor` or `Cherry Studio`. Here's how to set it up in Cursor.
Open Cursor's settings page and click MCP to enter the MCP configuration page. Click the new MCP Server button to open a JSON configuration file. Paste the `integration script` from step 2 into the `JSON file` and save.
Return to Cursor's MCP management page and you'll see your MCP Server listed. Make sure to set it to `enabled`.
| | | |
|---|---|---|
| ![](/imgs/mcp_server6.png) | ![](/imgs/mcp_server7.png) | ![](/imgs/mcp_server8.png) |
Open Cursor's chat panel and switch to `Agent` mode — only this mode triggers MCP Server calls.
After sending a question about `fastgpt`, you'll see Cursor invoke an MCP tool (described as: query fastgpt knowledge base), which calls the FastGPT application to process the question and return results.
| | |
|---|---|
| ![](/imgs/mcp_server9.png) | ![](/imgs/mcp_server10.png) |
## Self-Hosted MCP Server Setup
Self-hosted FastGPT deployments require version `v4.9.6` or higher to use MCP Server.
### Update docker-compose.yml
Add the `fastgpt-mcp-server` service to your `docker-compose.yml`:
```yml
fastgpt-mcp-server:
container_name: fastgpt-mcp-server
image: ghcr.io/labring/fastgpt-mcp_server:latest
ports:
- 3005:3000
networks:
- fastgpt
restart: always
environment:
- FASTGPT_ENDPOINT=http://fastgpt:3000
```
### Update FastGPT Configuration
In your `config.json`, add: `"feconfigs.mcpServerProxyEndpoint": "<your fastgpt-mcp-server URL>"` (no trailing slash). For example:
```json
{
"feConfigs": {
"lafEnv": "https://laf.dev",
"mcpServerProxyEndpoint": "https://mcp.fastgpt.cn"
}
}
```
### Restart FastGPT
Since you modified a mounted config file, force a full restart:
```bash
docker-compose down
docker-compose up -d
```
After restarting, the MCP Server option will appear in the Workspace.
document/content/docs/introduction/guide/dashboard/mcp_tools.en.mdx 0 → 100644
---
title: MCP Tools
description: A quick guide to integrating MCP tools with FastGPT
---
Starting from FastGPT v4.9.6, a new application type called MCP Tools has been added. It lets you provide an MCP SSE URL to batch-create tools that models can easily call. Here's how to create MCP tools and have AI use them.
## Create an MCP Tools Collection
First, select "New MCP Tools Collection." We'll use the Amap (Gaode Maps) MCP Server as an example: [Amap MCP Server](https://lbs.amap.com/api/mcp-server/create-project-and-key)
You'll need an MCP URL, e.g., https://mcp.amap.com/sse?key=xxx
![Create MCP tools](/imgs/mcp_tools1.png)
Enter the URL in the dialog and click Parse. The system will discover and list the available tools.
Click Create to finish setting up the MCP tools and collection.
## Test MCP Tools
Inside the MCP Tools collection, you can debug each tool individually.
![Test MCP tools](/imgs/mcp_tools3.png)
For example, select the maps_weather tool and click Run to see the weather data for Hangzhou.
## AI Calling Tools
### Call Individual Tools
![Call individual tools](/imgs/mcp_tools4.png)
Using maps_weather and maps_text_search as examples, ask the AI two different questions. The AI intelligently selects the appropriate tool, retrieves the needed information, and responds based on the results.
| | |
|---|---|
| ![](/imgs/mcp_tools5.png) | ![](/imgs/mcp_tools6.png) |
### Call an Entire Tools Collection
FastGPT also supports calling an entire MCP Tools collection. The AI automatically picks the right tool to execute.
Click the MCP Tools collection to add a collection-type node, then connect it using the Tool Calling node.
| | |
|---|---|
| ![](/imgs/mcp_tools7.png) | ![](/imgs/mcp_tools8.png) |
The AI similarly selects the appropriate tool, retrieves the needed information, and responds based on the results.
document/content/docs/introduction/guide/dashboard/meta.en.json 0 → 100644
{
"title": "Dashboard",
"description": "FastGPT dashboard and workflow node usage guide",
"pages": [
"basic-mode",
"intro",
"workflow",
"mcp_server",
"mcp_tools",
"gapier",
"evaluation"
]
}
document/content/docs/introduction/guide/dashboard/workflow/ai_chat.en.mdx 0 → 100644
---
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
![](/imgs/aichat.png)
## Parameters
## AI Model
Configure available chat models via [config.json](/docs/introduction/development/configuration/) and connect multiple models through [one-api](/docs/introduction/development/modelConfig/one-api).
Click the AI model to configure its parameters.
![](/imgs/aichat02.png)
![](/imgs/aichat2.png)
<Alert icon="🍅" context="success">
For detailed parameter descriptions, see: [AI Parameter Configuration](/docs/introduction/guide/course/ai_settings/)
</Alert>
document/content/docs/introduction/guide/dashboard/workflow/content_extract.en.mdx 0 → 100644
---
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
![](/imgs/extract1.png)
## 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.
document/content/docs/introduction/guide/dashboard/workflow/coreferenceResolution.en.mdx 0 → 100644
---
title: Query Enhancement
description: FastGPT Query Enhancement node overview and usage
---
## Characteristics
- Can be added multiple times
- Has external input
- Trigger-based execution
![](/imgs/coreferenceResolution1.jpg)
## 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:
![](/imgs/coreferenceResolution2.webp)
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:
![](/imgs/coreferenceResolution3.webp)
## 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.
## Examples
- [Integrate Google Search](/docs/use-cases/app-cases/google_search/)
document/content/docs/introduction/guide/dashboard/workflow/custom_feedback.en.mdx 0 → 100644
---
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
| | |
| --------------------- | --------------------- |
| ![](/imgs/customfeedback1.jpg) | ![](/imgs/customfeedback2.jpg) |
| ![](/imgs/customfeedback3.jpg) | ![](/imgs/customfeedback4.jpg) |
## 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.
document/content/docs/introduction/guide/dashboard/workflow/dataset_search.en.mdx 0 → 100644
---
title: Knowledge Base Search
description: FastGPT Knowledge Base Search node overview
---
For detailed parameters and internal logic, see: [FastGPT Knowledge Base Search](/docs/introduction/guide/knowledge_base/rag/)
## Characteristics
- Can be added multiple times (keeps connections tidy in complex workflows)
- Has external input
- Has static configuration
- Trigger-based execution
- Core module
![](/imgs/flow-dataset1.png)
## 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](/docs/introduction/guide/knowledge_base/dataset_engine/#搜索参数)
### 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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment