diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000000..c62a26741d --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "enabledPlugins": { + "skill-creator@claude-plugins-official": true + } +} diff --git a/.claude/skills/doc-i18n/SKILL.md b/.claude/skills/doc-i18n/SKILL.md new file mode 100644 index 0000000000..bc7841abb1 --- /dev/null +++ b/.claude/skills/doc-i18n/SKILL.md @@ -0,0 +1,114 @@ +--- +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 组件结构和属性（如 ``） +- 表格的 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 | + +### 语气 + +- 保持专业但友好的语气，和原文档的风格一致 +- 不要过度正式，也不要过于随意 +- 面向开发者和技术用户，假设读者有基本的技术背景 diff --git a/.claude/skills/system-create_skill_file/SKILL.md b/.claude/skills/system-create_skill_file/SKILL.md deleted file mode 100644 index e089adc08b..0000000000 --- a/.claude/skills/system-create_skill_file/SKILL.md +++ /dev/null @@ -1,475 +0,0 @@ ---- -name: create-skill-file -description: Guides Claude in creating well-structured SKILL.md files following best practices. Provides clear guidelines for naming, structure, and content organization to make skills easy to discover and execute. ---- - -# Claude Agent Skill 编写规范 - -> 如何创建高质量的 SKILL.md 文件 - -## 目录 - -- [快速开始](#快速开始) -- [核心原则](#核心原则) -- [文件结构规范](#文件结构规范) -- [命名和描述规范](#命名和描述规范) -- [内容编写指南](#内容编写指南) -- [质量检查清单](#质量检查清单) - ---- - -## 快速开始 - -### 3步创建 Skill - -**第1步: 创建目录** - -```bash -mkdir -p .claude/skill/your-skill-name -cd .claude/skill/your-skill-name -``` - -**第2步: 创建 SKILL.md** - -```markdown ---- -name: your-skill-name -description: Brief description with trigger keywords and scenarios ---- - -# Your Skill Title - -## When to Use This Skill - -- User asks to [specific scenario] -- User mentions "[keyword]" - -## How It Works - -1. Step 1: [Action] -2. Step 2: [Action] - -## Examples - -**Input**: User request -**Output**: Expected result -``` - -**第3步: 测试** -- 在对话中使用 description 中的关键词触发 -- 观察 Claude 是否正确执行 -- 根据效果调整 - ---- - -## 核心原则 - -### 1. 保持简洁 - -只添加 Claude **不知道**的新知识: -- ✅ 项目特定的工作流程 -- ✅ 特殊的命名规范或格式要求 -- ✅ 自定义工具和脚本的使用方法 -- ❌ 通用编程知识 -- ❌ 显而易见的步骤 - -**示例对比**: - -```markdown -# ❌ 过度详细 -1. 创建 Python 文件 -2. 导入必要的库 -3. 定义函数 -4. 编写主程序逻辑 - -# ✅ 简洁有效 -使用 `scripts/api_client.py` 调用内部 API。 -请求头必须包含 `X-Internal-Token`(从环境变量 `INTERNAL_API_KEY` 获取)。 -``` - -### 2. 设定合适的自由度 - -| 自由度 | 适用场景 | 编写方式 | -|--------|---------|---------| -| **高** | 需要创造性、多种解决方案 | 提供指导原则,不限定具体步骤 | -| **中** | 有推荐模式但允许变化 | 提供参数化示例和默认流程 | -| **低** | 容易出错、需严格执行 | 提供详细的分步指令或脚本 | - -**判断标准**: -- 任务是否有明确的"正确答案"? → 低自由度 -- 是否需要适应不同场景? → 高自由度 -- 错误的代价有多大? → 代价高则用低自由度 - -### 3. 渐进式披露 - -将复杂内容分层组织: - -``` -SKILL.md (主文档, 200-500行) -├── reference.md (详细文档) -├── examples.md (完整示例) -└── scripts/ (可执行脚本) -``` - -**规则**: -- SKILL.md 超过 500行 → 拆分子文件 -- 子文件超过 100行 → 添加目录 -- 引用深度 ≤ 1层 - ---- - -## 文件结构规范 - -### YAML Frontmatter - -```yaml ---- -name: skill-name-here -description: Clear description of what this skill does and when to activate it ---- -``` - -**字段规范**: - -| 字段 | 要求 | 说明 | -|------|------|------| -| `name` | 小写字母、数字、短横线,≤64字符 | 必须与目录名一致 | -| `description` | 纯文本,≤1024字符 | 用于检索和激活 | - -**命名禁忌**: -- ❌ XML 标签、保留字(`anthropic`, `claude`) -- ❌ 模糊词汇(`helper`, `utility`, `manager`) -- ❌ 空格或下划线(用短横线 `-`) - -**Description 技巧**: - -```yaml -# ❌ 过于泛化 -description: Helps with code tasks - -# ✅ 具体且包含关键词 -description: Processes CSV files and generates Excel reports with charts. Use when user asks to convert data formats or create visual reports. - -# ✅ 说明触发场景 -description: Analyzes Python code for security vulnerabilities using bandit. Activates when user mentions "security audit" or "vulnerability scan". -``` - -### 目录组织 - -**基础结构**(简单 Skill): -``` -skill-name/ -└── SKILL.md -``` - -**标准结构**(推荐): -``` -skill-name/ -├── SKILL.md -├── templates/ -│ └── template.md -└── scripts/ - └── script.py -``` - ---- - -## 命名和描述规范 - -### Skill 命名 - -**推荐格式**: 动名词形式 (verb-ing + noun) - -``` -✅ 好的命名: -- processing-csv-files -- generating-api-docs -- managing-database-migrations - -❌ 不好的命名: -- csv (过于简短) -- data_processor (使用下划线) -- helper (过于模糊) -``` - -### Description 编写 - -**必须使用第三人称**: - -```yaml -# ❌ 错误 -description: I help you process PDFs - -# ✅ 正确 -description: Processes PDF documents and extracts structured data -``` - -**4C 原则**: -- **Clear** (清晰): 避免术语和模糊词汇 -- **Concise** (简洁): 1-2句话说明核心功能 -- **Contextual** (上下文): 说明适用场景 -- **Complete** (完整): 功能 + 触发条件 - ---- - -## 内容编写指南 - -### "When to Use" 章节 - -明确说明触发场景: - -```markdown -## When to Use This Skill - -- User asks to analyze Python code for type errors -- User mentions "mypy" or "type checking" -- User is working in a Python project with type hints -- User needs to add type annotations -``` - -**模式**: -- 直接请求: "User asks to X" -- 关键词: "User mentions 'keyword'" -- 上下文: "User is working with X" -- 任务类型: "User needs to X" - -### 工作流设计 - -**简单线性流程**: - -```markdown -## How It Works - -1. Scan the project for all `.py` files -2. Run `mypy --strict` on each file -3. Parse error output and categorize by severity -4. Generate summary report with fix suggestions -``` - -**条件分支流程**: - -```markdown -## Workflow - -1. **Check project type** - - If Django → Use `django-stubs` config - - If Flask → Use `flask-stubs` config - - Otherwise → Use default mypy config - -2. **Run type checking** - - If errors found → Proceed to step 3 - - If no errors → Report success and exit -``` - -**Checklist 模式**(验证型任务): - -```markdown -## Pre-deployment Checklist - -Execute in order. Stop if any step fails. - -- [ ] Run tests: `npm test` (must pass) -- [ ] Build: `npm run build` (no errors) -- [ ] Check deps: `npm audit` (no critical vulnerabilities) -``` - -### 示例和模板 - -**输入-输出示例**: - -```markdown -## Examples - -### Example 1: Basic Check - -**User Request**: "Check my code for type errors" - -**Action**: -1. Scan for `.py` files -2. Run `mypy` on all files - -**Output**: - - Found 3 type errors in 2 files: - src/main.py:15: error: Missing return type - src/utils.py:42: error: Incompatible types - -``` - -### 脚本集成 - -**何时使用脚本**: -- 简单命令 → 直接在 SKILL.md 中说明 -- 复杂流程 → 提供独立脚本 - -**脚本编写规范**: - -```python -#!/usr/bin/env python3 -""" -Brief description of what this script does. - -Usage: - python script.py [--option value] -""" - -import argparse - -DEFAULT_VALUE = 80 # Use constants, not magic numbers - -def main(): - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument("directory", help="Directory to process") - parser.add_argument("--threshold", type=int, default=DEFAULT_VALUE) - - args = parser.parse_args() - - # Validate inputs - if not Path(args.directory).is_dir(): - print(f"Error: {args.directory} not found") - return 1 - - # Execute - result = process(args.directory, args.threshold) - - # Report - print(f"Processed {result['count']} files") - return 0 - -if __name__ == "__main__": - exit(main()) -``` - -**关键规范**: -- ✅ Shebang 行和 docstring -- ✅ 类型注解和常量 -- ✅ 参数验证和错误处理 -- ✅ 清晰的返回值(0=成功, 1=失败) - -### 最佳实践 - -**Do**: -- ✅ 提供可执行的命令和脚本 -- ✅ 包含输入-输出示例 -- ✅ 说明验证标准和成功条件 -- ✅ 包含 Do/Don't 清单 - -**Don't**: -- ❌ 包含 Claude 已知的通用知识 -- ❌ 使用抽象描述而非具体步骤 -- ❌ 遗漏错误处理指导 -- ❌ 示例使用伪代码而非真实代码 - ---- - -## 质量检查清单 - -### 核心质量 - -- [ ] `name` 符合命名规范(小写、短横线、≤64字符) -- [ ] `description` 包含触发关键词和场景(≤1024字符) -- [ ] 名称与目录名一致 -- [ ] 只包含 Claude 不知道的信息 -- [ ] 没有冗余或重复内容 - -### 功能完整性 - -- [ ] 有"When to Use"章节,列出 3-5 个触发场景 -- [ ] 有清晰的执行流程或步骤 -- [ ] 至少 2-3 个完整示例 -- [ ] 包含输入和预期输出 -- [ ] 错误处理有指导 - -### 结构规范 - -- [ ] 章节组织清晰 -- [ ] 超过 200行有目录导航 -- [ ] 引用层级 ≤ 1层 -- [ ] 所有路径使用正斜杠 `/` -- [ ] 术语使用一致 - -### 脚本和模板 - -- [ ] 脚本包含使用说明和参数文档 -- [ ] 脚本有错误处理 -- [ ] 避免魔法数字,使用配置 -- [ ] 模板格式清晰易用 - -### 最终检查 - -- [ ] 通读全文,确保流畅易读 -- [ ] 使用实际场景测试触发 -- [ ] 长度适中(200-500行,或已拆分) - ---- - -## 常见问题 - -**Q: Skill 多长才合适?** -- 最小: 50-100行 -- 理想: 200-500行 -- 最大: 500行(超过则拆分) - -**Q: 如何让 Skill 更容易激活?** -- 在 `description` 中使用用户会说的关键词 -- 说明具体场景("when user asks to X") -- 提及相关工具名称 - -**Q: 多个 Skill 功能重叠怎么办?** -- 使用更具体的 `description` 区分 -- 在"When to Use"中说明关系 -- 考虑合并为一个 Skill - -**Q: Skill 需要维护吗?** -- 每季度审查一次,更新过时信息 -- 根据使用反馈迭代 -- 工具或 API 变更时及时更新 - ---- - -## 快速参考 - -### Frontmatter 模板 - -```yaml ---- -name: skill-name -description: Brief description with trigger keywords ---- -``` - -### 基础结构模板 - -```markdown -# Skill Title - -## When to Use This Skill -- Scenario 1 -- Scenario 2 - -## How It Works -1. Step 1 -2. Step 2 - -## Examples -### Example 1 -... - -## References -- [Link](url) -``` - ---- - -## 相关资源 - -- [Claude Agent Skills 官方文档](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) -- [Best Practices Checklist](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) -- [模板文件](templates/) - 开箱即用的模板 - - [基础 skill 的模板](templates/basic-skill-template.md) - - [工作流 skill 的模板](templates/workflow-skill-template.md) -- [示例库](examples/) - 完整的 Skill 示例 - - [优秀示例](examples/good-example.md) - - [常见错误示例](examples/bad-example.md) - ---- diff --git a/.claude/skills/system-create_skill_file/examples/bad-example.md b/.claude/skills/system-create_skill_file/examples/bad-example.md deleted file mode 100644 index c0ae20b1bd..0000000000 --- a/.claude/skills/system-create_skill_file/examples/bad-example.md +++ /dev/null @@ -1,867 +0,0 @@ -# 不好的 Skill 示例与改进建议 - -本文档展示常见的 Skill 编写错误,并提供改进建议。 - ---- - -## 示例 1: 过于模糊的 Skill - -### ❌ 不好的版本 - -```markdown ---- -name: helper -description: Helps with code ---- - -# Code Helper - -This skill helps you with coding tasks. - -## Usage - -Use this when you need help with code. - -## How It Works - -1. Analyzes your code -2. Provides suggestions -3. Helps improve it -``` - -### 问题分析 - -| 问题 | 说明 | 影响 | -|------|------|------| -| **模糊的名称** | "helper" 太泛化,没有说明具体做什么 | Claude 不知道何时激活 | -| **无关键词** | description 缺少具体触发词 | 用户很难激活这个 Skill | -| **无具体场景** | 没说明适用什么类型的代码 | 适用范围不清 | -| **抽象的步骤** | "Provides suggestions" 太模糊 | Claude 不知道具体做什么 | -| **无示例** | 没有实际例子 | 用户和 Claude 都不清楚预期输出 | - -### ✅ 改进版本 - -```markdown ---- -name: python-code-refactoring -description: Refactors Python code to improve readability and maintainability using standard patterns. Activates when user asks to clean up code, improve structure, or mentions refactoring. Focuses on function extraction, variable naming, and removing code smells. ---- - -# Python Code Refactoring Skill - -Improves Python code quality through systematic refactoring. - -## When to Use This Skill - -- User asks to "refactor this code", "clean up this function", or "improve readability" -- User mentions "code smell", "technical debt", or "maintainability" -- User is working with Python code that has: - - Long functions (>50 lines) - - Nested conditionals (>3 levels) - - Repeated code patterns - - Unclear variable names - -## How It Works - -### 1. Identify Refactoring Opportunities - -Scan code for common issues: -- Functions longer than 50 lines -- Repeated code blocks (DRY violations) -- Magic numbers without constants -- Unclear variable names (x, temp, data) -- Deep nesting (>3 levels) - -### 2. Prioritize Changes - -Focus on high-impact refactorings: -- **High**: Extract complex nested logic to functions -- **Medium**: Rename unclear variables -- **Low**: Minor style improvements - -### 3. Apply Refactorings - -**Extract Method**: -```python -# Before -def process_order(order): - # 50 lines of validation logic - # 30 lines of payment processing - # 20 lines of email notification - -# After -def process_order(order): - validate_order(order) - process_payment(order) - send_confirmation_email(order) -``` - -**Replace Magic Numbers**: -```python -# Before -if user.age < 18: - return False - -# After -MINIMUM_AGE = 18 -if user.age < MINIMUM_AGE: - return False -``` - -**Simplify Conditionals**: -```python -# Before -if user.role == 'admin': - return True -elif user.role == 'moderator': - return True -elif user.role == 'editor': - return True -else: - return False - -# After -PRIVILEGED_ROLES = {'admin', 'moderator', 'editor'} -return user.role in PRIVILEGED_ROLES -``` - -### 4. Verify Improvements - -After refactoring: -- Run existing tests (all must pass) -- Check code length reduced -- Verify improved readability - -## Example - -**User Request**: "Refactor this function, it's too long" - -```python -def process_user_registration(data): - if not data.get('email'): - return {'error': 'Email required'} - if '@' not in data['email']: - return {'error': 'Invalid email'} - if not data.get('password'): - return {'error': 'Password required'} - if len(data['password']) < 8: - return {'error': 'Password too short'} - if not any(c.isupper() for c in data['password']): - return {'error': 'Password needs uppercase'} - existing = db.query(User).filter_by(email=data['email']).first() - if existing: - return {'error': 'Email already registered'} - salt = bcrypt.gensalt() - hashed = bcrypt.hashpw(data['password'].encode(), salt) - user = User(email=data['email'], password_hash=hashed) - db.add(user) - db.commit() - token = jwt.encode({'user_id': user.id}, SECRET_KEY) - send_email(data['email'], 'Welcome!', 'Thanks for registering') - return {'success': True, 'token': token} -``` - -**Refactored**: - -```python -def process_user_registration(data): - """Register new user with validation and email confirmation.""" - # Validation - validation_error = validate_registration_data(data) - if validation_error: - return {'error': validation_error} - - # Check uniqueness - if user_exists(data['email']): - return {'error': 'Email already registered'} - - # Create user - user = create_user(data['email'], data['password']) - - # Generate token - token = generate_auth_token(user.id) - - # Send welcome email - send_welcome_email(user.email) - - return {'success': True, 'token': token} - - -def validate_registration_data(data): - """Validate registration data, return error message or None.""" - if not data.get('email'): - return 'Email required' - if '@' not in data['email']: - return 'Invalid email' - if not data.get('password'): - return 'Password required' - return validate_password_strength(data['password']) - - -def validate_password_strength(password): - """Check password meets security requirements.""" - MIN_PASSWORD_LENGTH = 8 - if len(password) < MIN_PASSWORD_LENGTH: - return f'Password must be at least {MIN_PASSWORD_LENGTH} characters' - if not any(c.isupper() for c in password): - return 'Password must contain uppercase letter' - return None - - -def user_exists(email): - """Check if user with given email already exists.""" - return db.query(User).filter_by(email=email).first() is not None - - -def create_user(email, password): - """Create and save new user with hashed password.""" - salt = bcrypt.gensalt() - hashed = bcrypt.hashpw(password.encode(), salt) - user = User(email=email, password_hash=hashed) - db.add(user) - db.commit() - return user - - -def generate_auth_token(user_id): - """Generate JWT authentication token.""" - return jwt.encode({'user_id': user_id}, SECRET_KEY) - - -def send_welcome_email(email): - """Send welcome email to new user.""" - send_email(email, 'Welcome!', 'Thanks for registering') -``` - -**Improvements**: -- ✅ Main function reduced from 20 lines to 15 lines -- ✅ Each function has single responsibility -- ✅ Magic number (8) extracted to constant -- ✅ All functions documented with docstrings -- ✅ Easier to test individual functions -- ✅ Easier to modify validation rules - -## Best Practices - -- ✅ Extract functions with clear names -- ✅ Use constants instead of magic numbers -- ✅ Keep functions under 30 lines -- ✅ Maximum nesting depth of 2-3 levels -- ✅ Write docstrings for extracted functions -``` - -### 改进要点 - -1. ✅ 具体的名称: `python-code-refactoring` 而非 `helper` -2. ✅ 详细的 description: 包含触发词和适用场景 -3. ✅ 明确的触发条件: 列出具体的使用场景 -4. ✅ 可执行的步骤: 每个步骤都有具体操作 -5. ✅ 实际代码示例: 展示完整的重构过程 -6. ✅ 具体的改进指标: 列出可验证的改进效果 - ---- - -## 示例 2: 过度冗长的 Skill - -### ❌ 不好的版本 - -```markdown ---- -name: python-basics -description: Teaches Python programming basics ---- - -# Python Basics - -This skill helps you learn Python programming. - -## Variables - -In Python, you can create variables like this: - -```python -x = 5 -y = "hello" -z = 3.14 -``` - -Python supports different data types: -- Integers (int): whole numbers like 1, 2, 3 -- Floats (float): decimal numbers like 3.14, 2.5 -- Strings (str): text like "hello", 'world' -- Booleans (bool): True or False - -## Conditional Statements - -You can use if statements to make decisions: - -```python -if x > 0: - print("Positive") -elif x < 0: - print("Negative") -else: - print("Zero") -``` - -The if statement checks a condition. If True, it runs the indented code. -The elif means "else if" and provides an alternative condition. -The else runs if none of the above conditions are True. - -## Loops - -Python has two main types of loops: - -### For Loops - -For loops iterate over a sequence: - -```python -for i in range(5): - print(i) -``` - -This prints numbers 0 through 4. The range() function generates numbers. - -### While Loops - -While loops continue while a condition is True: - -```python -i = 0 -while i < 5: - print(i) - i += 1 -``` - -This does the same thing as the for loop above. - -## Functions - -Functions are reusable blocks of code: - -```python -def greet(name): - return f"Hello, {name}!" -``` - -The def keyword defines a function. The function name is greet. -It takes one parameter called name. The return statement sends back a value. - -## Lists - -Lists store multiple items: - -```python -fruits = ["apple", "banana", "orange"] -``` - -You can access items by index: - -```python -first_fruit = fruits[0] # "apple" -``` - -... [continues for 50 more sections about Python basics] -``` - -### 问题分析 - -| 问题 | 说明 | 影响 | -|------|------|------| -| **包含通用知识** | Python 基础知识 Claude 已经知道 | 浪费 token,增加检索成本 | -| **教程式内容** | 像教程而非工作指南 | Claude 不需要学习,需要的是工作指导 | -| **过度详细** | 解释显而易见的概念 | 信息过载,难以找到关键信息 | -| **缺少项目特定信息** | 没有项目相关的规范或约定 | 无法提供项目特定价值 | - -### ✅ 改进版本 - -```markdown ---- -name: project-python-conventions -description: Enforces Python coding conventions specific to this project. Activates when user writes Python code or asks about code style. Covers naming, imports, error handling, and project-specific patterns. ---- - -# Project Python Conventions - -Project-specific Python coding standards and patterns. - -## When to Use This Skill - -- User is writing or reviewing Python code -- User asks about code style or conventions -- User needs guidance on project patterns - -## Import Organization - -Follow this order: - -```python -# 1. Standard library -import os -import sys -from typing import Optional, List - -# 2. Third-party packages -import numpy as np -from fastapi import FastAPI - -# 3. Local application imports -from core.models import User -from utils.helpers import format_date -``` - -## Naming Conventions - -### Project-Specific Rules - -| Type | Pattern | Example | -|------|---------|---------| -| API endpoints | `/api/v1/{resource}` | `/api/v1/users` | -| Database tables | `{resource}_table` | `users_table` | -| Environment variables | `APP_{NAME}` | `APP_DATABASE_URL` | -| Config files | `{env}.config.py` | `prod.config.py` | - -### Forbidden Patterns - -```python -# ❌ Don't use single-letter variables (except i, j, k in loops) -d = get_data() - -# ✅ Do use descriptive names -user_data = get_data() - -# ❌ Don't use abbreviations -usr_mgr = UserManager() - -# ✅ Do use full words -user_manager = UserManager() -``` - -## Error Handling Pattern - -Use project's custom exceptions: - -```python -from core.exceptions import UserNotFoundError, ValidationError - -def get_user(user_id: int) -> User: - """ - Retrieve user by ID. - - Raises: - UserNotFoundError: If user doesn't exist - ValidationError: If user_id is invalid - """ - if not isinstance(user_id, int) or user_id <= 0: - raise ValidationError(f"Invalid user_id: {user_id}") - - user = db.query(User).get(user_id) - if user is None: - raise UserNotFoundError(f"User {user_id} not found") - - return user -``` - -**Never** use bare `except:` - always catch specific exceptions. - -## Database Queries - -Always use the project's query helper: - -```python -# ❌ Don't use raw SQLAlchemy queries -users = db.query(User).filter(User.age > 18).all() - -# ✅ Do use query helper -from core.database import QueryBuilder - -users = QueryBuilder(User).where('age', '>', 18).get() -``` - -## API Response Format - -All API endpoints must return this format: - -```python -{ - "success": True, - "data": { - # ... response data - }, - "error": None, - "meta": { - "timestamp": "2025-01-31T12:00:00Z", - "version": "1.0" - } -} -``` - -Use the response helper: - -```python -from core.responses import success_response, error_response - -@app.get("/users/{id}") -async def get_user(id: int): - try: - user = get_user_data(id) - return success_response(user) - except UserNotFoundError as e: - return error_response(str(e), status_code=404) -``` - -## Testing Patterns - -### Test File Location - -``` -project/ -├── src/ -│ └── services/ -│ └── user_service.py -└── tests/ - └── services/ - └── test_user_service.py -``` - -### Test Naming - -```python -# Format: test_{function_name}_{scenario}_{expected_result} - -def test_get_user_valid_id_returns_user(): - """Test getting user with valid ID returns User object.""" - pass - -def test_get_user_invalid_id_raises_validation_error(): - """Test getting user with invalid ID raises ValidationError.""" - pass - -def test_get_user_nonexistent_id_raises_not_found_error(): - """Test getting non-existent user raises UserNotFoundError.""" - pass -``` - -## References - -- [Full Style Guide](docs/STYLE_GUIDE.md) -- [API Standards](docs/API_STANDARDS.md) -- [Database Conventions](docs/DATABASE.md) -``` - -### 改进要点 - -1. ✅ 只包含项目特定信息: 不教 Python 基础 -2. ✅ 简洁明了: 200 行 vs 原来的 500+ 行 -3. ✅ 实用的规则: 直接可应用的约定 -4. ✅ 清晰的示例: Do/Don't 对比 -5. ✅ 引用详细文档: 用链接而非全部内容 - ---- - -## 示例 3: 缺少上下文的 Skill - -### ❌ 不好的版本 - -```markdown ---- -name: deployment -description: Deploys code ---- - -# Deployment - -## Steps - -1. Build the code -2. Run tests -3. Deploy to server -4. Verify deployment -``` - -### 问题分析 - -| 问题 | 说明 | 影响 | -|------|------|------| -| **无具体命令** | 没说明如何 build, test, deploy | Claude 无法执行 | -| **无环境区分** | 开发、测试、生产部署可能不同 | 可能部署到错误环境 | -| **无错误处理** | 没说明出错时怎么办 | 失败时不知如何恢复 | -| **无验证标准** | "Verify" 太模糊 | 不知道检查什么 | - -### ✅ 改进版本 - -```markdown ---- -name: deploy-to-production -description: Deploys application to production environment on AWS. Activates when user asks to deploy to prod or mentions production deployment. Includes pre-flight checks, blue-green deployment, and rollback procedures. ---- - -# Production Deployment - -Safely deploy application to production with zero downtime. - -## When to Use This Skill - -- User asks to "deploy to production" or "push to prod" -- User mentions "production deployment", "go live" -- User needs to rollback a deployment - -## Prerequisites - -Before deployment, verify: - -```bash -# 1. On main branch -git branch --show-current # Must be "main" - -# 2. All tests pass -npm test # Exit code must be 0 - -# 3. Build succeeds -npm run build # Must complete without errors - -# 4. No uncommitted changes -git status # Must show "nothing to commit" - -# 5. Latest code pulled -git pull origin main # Must be up to date -``` - -If any prerequisite fails, **stop** and fix the issue. - -## Deployment Process - -### Step 1: Pre-flight Checks - -```bash -# Run deployment readiness script -./scripts/preflight-check.sh - -# Expected output: -# ✓ Tests passed -# ✓ Build succeeded -# ✓ Environment variables configured -# ✓ Database migrations ready -# ✓ Ready to deploy -``` - -### Step 2: Database Migrations (if needed) - -```bash -# Connect to production database -aws rds describe-db-instances --db-instance-identifier prod-db - -# Backup before migration -./scripts/backup-database.sh prod - -# Run migrations -NODE_ENV=production npm run migrate - -# Verify migration succeeded -npm run migrate:status -``` - -### Step 3: Blue-Green Deployment - -```bash -# Deploy to green environment (inactive) -aws elasticbeanstalk create-environment \ - --application-name myapp \ - --environment-name myapp-prod-green \ - --solution-stack-name "64bit Amazon Linux 2 v5.x.x running Node.js 18" - -# Wait for green environment to be healthy -aws elasticbeanstalk wait environment-updated \ - --environment-name myapp-prod-green - -# Check green environment health -curl https://myapp-prod-green.aws.com/health -# Expected: {"status": "healthy"} -``` - -### Step 4: Smoke Tests - -```bash -# Run smoke tests against green environment -BASE_URL=https://myapp-prod-green.aws.com npm run test:smoke - -# Tests must include: -# - Health check endpoint -# - Authentication flow -# - Critical API endpoints -# - Database connectivity -``` - -### Step 5: Switch Traffic - -```bash -# Swap URLs (blue becomes green, green becomes blue) -aws elasticbeanstalk swap-environment-cnames \ - --source-environment-name myapp-prod-blue \ - --destination-environment-name myapp-prod-green - -# Wait 5 minutes for DNS propagation -echo "Waiting for DNS propagation..." -sleep 300 - -# Verify production URL serves new version -curl https://myapp.com/version -# Expected: {"version": "1.2.3"} (new version) -``` - -### Step 6: Monitor - -```bash -# Monitor error rates for 15 minutes -aws cloudwatch get-metric-statistics \ - --namespace AWS/ELB \ - --metric-name HTTPCode_Backend_5XX \ - --start-time $(date -u -d '15 minutes ago' +%Y-%m-%dT%H:%M:%S) \ - --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \ - --period 300 \ - --statistics Sum - -# Error rate must be < 1% -``` - -If error rate exceeds 1%: -- **Rollback immediately** (see Rollback section) -- Investigate issue -- Fix and redeploy - -### Step 7: Cleanup - -```bash -# After 24 hours, if no issues: -# Terminate old blue environment -aws elasticbeanstalk terminate-environment \ - --environment-name myapp-prod-blue -``` - -## Rollback Procedure - -If deployment fails: - -```bash -# 1. Swap back to previous version -aws elasticbeanstalk swap-environment-cnames \ - --source-environment-name myapp-prod-green \ - --destination-environment-name myapp-prod-blue - -# 2. Verify old version is serving -curl https://myapp.com/version -# Expected: {"version": "1.2.2"} (old version) - -# 3. Rollback database migrations (if ran) -NODE_ENV=production npm run migrate:rollback - -# 4. Notify team -./scripts/notify-rollback.sh "Deployment rolled back due to [reason]" -``` - -## Example Deployment - -**User Request**: "Deploy v1.2.3 to production" - -**Execution Log**: - -``` -[14:00:00] Starting deployment of v1.2.3 to production -[14:00:05] ✓ Pre-flight checks passed -[14:00:10] ✓ Database backup completed -[14:00:30] ✓ Database migrations applied (3 migrations) -[14:01:00] → Creating green environment -[14:05:00] ✓ Green environment healthy -[14:05:30] ✓ Smoke tests passed (12/12) -[14:06:00] → Switching traffic to green environment -[14:11:00] ✓ DNS propagated -[14:11:05] ✓ Production serving v1.2.3 -[14:11:10] → Monitoring for 15 minutes -[14:26:10] ✓ Error rate: 0.05% (within threshold) -[14:26:15] ✓ Deployment successful -[14:26:20] → Old environment will be terminated in 24h - -Deployment completed successfully in 26 minutes -``` - -## References - -- [AWS Deployment Guide](docs/AWS_DEPLOYMENT.md) -- [Runbook](docs/RUNBOOK.md) -- [On-Call Procedures](docs/ONCALL.md) -``` - -### 改进要点 - -1. ✅ 具体命令: 每个步骤都有可执行的命令 -2. ✅ 环境明确: 专注于生产环境部署 -3. ✅ 验证标准: 说明检查什么和预期结果 -4. ✅ 错误处理: 包含完整的回滚流程 -5. ✅ 实际输出: 展示命令的预期输出 -6. ✅ 监控指标: 定义具体的成功标准 - ---- - -## 常见错误总结 - -### 1. 命名和描述问题 - -| 错误 | 示例 | 改进 | -|------|------|------| -| 过于泛化 | `name: helper` | `name: python-type-hints` | -| 缺少关键词 | `description: Helps with code` | `description: Adds type hints to Python using mypy` | -| 使用第一人称 | `description: I help you...` | `description: Adds type hints...` | - -### 2. 内容问题 - -| 错误 | 说明 | 改进 | -|------|------|------| -| 包含通用知识 | 教 Python 基础语法 | 只包含项目特定规范 | -| 过于抽象 | "分析代码并提供建议" | "检查函数长度、变量命名、重复代码" | -| 缺少示例 | 只有文字描述 | 包含输入-输出示例 | - -### 3. 结构问题 - -| 错误 | 说明 | 改进 | -|------|------|------| -| 无层次结构 | 所有内容混在一起 | 使用标题、列表、代码块组织 | -| 缺少"When to Use" | 不知道何时激活 | 列出 3-5 个触发场景 | -| 无验证步骤 | 不知道如何确认成功 | 说明检查项和预期结果 | - -### 4. 自由度问题 - -| 错误 | 说明 | 改进 | -|------|------|------| -| 创意任务低自由度 | 为架构设计提供分步指令 | 提供指导原则和考虑因素 | -| 危险任务高自由度 | 生产部署没有具体步骤 | 提供详细的检查清单 | -| 不匹配任务类型 | 代码生成用教程式内容 | 提供模板和实际示例 | - ---- - -## 快速检查清单 - -在发布 Skill 之前,问自己: - -### 基础检查 - -- [ ] Name 是否具体且描述性强? -- [ ] Description 包含触发关键词和场景? -- [ ] 有明确的"When to Use"章节? -- [ ] 内容只包含 Claude 不知道的信息? - -### 内容检查 - -- [ ] 是否有实际的代码示例? -- [ ] 步骤是否具体可执行? -- [ ] 是否说明了如何验证成功? -- [ ] 是否包含错误处理指导? - -### 结构检查 - -- [ ] 内容组织清晰(使用标题、列表)? -- [ ] 自由度设定合适(匹配任务类型)? -- [ ] 长度合适(200-500行,或拆分子文件)? -- [ ] 包含 Do/Don't 最佳实践? - -如果有任何一项答"否",参考本文档的改进建议进行修改。 \ No newline at end of file diff --git a/.claude/skills/system-create_skill_file/examples/good-example.md b/.claude/skills/system-create_skill_file/examples/good-example.md deleted file mode 100644 index e3016a1f24..0000000000 --- a/.claude/skills/system-create_skill_file/examples/good-example.md +++ /dev/null @@ -1,908 +0,0 @@ -# 好的 Skill 示例 - -本文档展示几个编写良好的 SKILL.md 示例,说明最佳实践的实际应用。 - ---- - -## 示例 1: 数据库迁移 Skill (高质量基础 Skill) - -```markdown ---- -name: database-migration -description: Manages database schema migrations using Alembic for SQLAlchemy projects. Activates when user asks to create migrations, upgrade/downgrade database, or mentions Alembic. Handles both development and production scenarios with safety checks. ---- - -# Database Migration Skill - -Automates database schema migration management using Alembic. - -## When to Use This Skill - -- User asks to "create migration", "update database schema", or "rollback migration" -- User mentions "Alembic", "database migration", or "schema change" -- User is working in a Python project with SQLAlchemy models -- User needs to apply or revert database changes - -## Quick Start - -Create a new migration: -```bash -alembic revision --autogenerate -m "Description of changes" -``` - -Apply migrations: -```bash -alembic upgrade head -``` - -## How It Works - -### Creating Migrations - -1. **Detect model changes** - - Scan SQLAlchemy models in `models/` directory - - Compare with current database schema - - Identify additions, modifications, deletions - -2. **Generate migration script** - - Run `alembic revision --autogenerate` - - Review generated script for accuracy - - Edit if necessary (Alembic can't auto-detect everything) - -3. **Verify migration** - - Check upgrade() function is correct - - Ensure downgrade() function reverses changes - - Test on development database first - -### Applying Migrations - -1. **Safety checks** - - Backup database (production only) - - Verify no pending migrations - - Check database connectivity - -2. **Execute migration** - - Run `alembic upgrade head` - - Monitor for errors - - Verify schema matches expected state - -3. **Post-migration validation** - - Run application tests - - Check data integrity - - Confirm application starts successfully - -## Examples - -### Example 1: Add New Column - -**User Request**: "Add an email column to the users table" - -**Step 1**: Update the model -```python -# models/user.py -class User(Base): - __tablename__ = 'users' - id = Column(Integer, primary_key=True) - username = Column(String(50), nullable=False) - email = Column(String(120), nullable=True) # ← New field -``` - -**Step 2**: Generate migration -```bash -alembic revision --autogenerate -m "Add email column to users table" -``` - -**Generated migration** (alembic/versions/abc123_add_email.py): -```python -def upgrade(): - op.add_column('users', sa.Column('email', sa.String(120), nullable=True)) - -def downgrade(): - op.drop_column('users', 'email') -``` - -**Step 3**: Review and apply -```bash -# Review the migration file -cat alembic/versions/abc123_add_email.py - -# Apply migration -alembic upgrade head -``` - -**Output**: -``` -INFO [alembic.runtime.migration] Running upgrade xyz789 -> abc123, Add email column to users table -``` - -### Example 2: Complex Migration with Data Changes - -**User Request**: "Split the 'name' column into 'first_name' and 'last_name'" - -**Step 1**: Create empty migration (can't auto-generate data changes) -```bash -alembic revision -m "Split name into first_name and last_name" -``` - -**Step 2**: Write custom migration -```python -def upgrade(): - # Add new columns - op.add_column('users', sa.Column('first_name', sa.String(50))) - op.add_column('users', sa.Column('last_name', sa.String(50))) - - # Migrate existing data - connection = op.get_bind() - users = connection.execute("SELECT id, name FROM users") - for user_id, name in users: - parts = name.split(' ', 1) - first = parts[0] - last = parts[1] if len(parts) > 1 else '' - connection.execute( - "UPDATE users SET first_name = %s, last_name = %s WHERE id = %s", - (first, last, user_id) - ) - - # Make new columns non-nullable and drop old column - op.alter_column('users', 'first_name', nullable=False) - op.alter_column('users', 'last_name', nullable=False) - op.drop_column('users', 'name') - -def downgrade(): - # Add back name column - op.add_column('users', sa.Column('name', sa.String(100))) - - # Restore data - connection = op.get_bind() - users = connection.execute("SELECT id, first_name, last_name FROM users") - for user_id, first, last in users: - full_name = f"{first} {last}".strip() - connection.execute( - "UPDATE users SET name = %s WHERE id = %s", - (full_name, user_id) - ) - - op.alter_column('users', 'name', nullable=False) - op.drop_column('users', 'first_name') - op.drop_column('users', 'last_name') -``` - -**Step 3**: Test thoroughly -```bash -# Apply migration -alembic upgrade head - -# Verify data -python -c "from models import User; print(User.query.first().first_name)" - -# Test rollback -alembic downgrade -1 -python -c "from models import User; print(User.query.first().name)" - -# Reapply -alembic upgrade head -``` - -## Best Practices - -### Do - -- ✅ Always review auto-generated migrations before applying -- ✅ Test migrations on development database first -- ✅ Write reversible downgrade() functions -- ✅ Backup production databases before major migrations -- ✅ Use meaningful migration messages - -### Don't - -- ❌ Trust auto-generated migrations blindly -- ❌ Skip downgrade() implementation -- ❌ Apply untested migrations to production -- ❌ Modify existing migration files after they're committed -- ❌ Use raw SQL without bind parameters - -## Troubleshooting - -### "Target database is not up to date" - -**Problem**: Someone else applied migrations you don't have locally - -**Solution**: -```bash -git pull # Get latest migrations -alembic upgrade head # Apply them locally -``` - -### "Can't locate revision identified by 'xyz'" - -**Problem**: Migration file deleted or branch conflict - -**Solution**: -1. Check if migration file exists in `alembic/versions/` -2. If missing, restore from git history -3. If branch conflict, merge migration branches: - ```bash - alembic merge -m "Merge migration branches" head1 head2 - ``` - -### Migration fails mid-execution - -**Problem**: Error occurred during migration - -**Solution**: -1. Check error message for specifics -2. Manually fix database to consistent state if needed -3. Update migration script to fix the issue -4. Mark migration as completed or retry: - ```bash - # Mark as done without running - alembic stamp head - - # Or fix and retry - alembic upgrade head - ``` - -## Configuration - -### Project Structure -``` -project/ -├── alembic/ -│ ├── versions/ # Migration scripts -│ ├── env.py # Alembic environment -│ └── script.py.mako # Migration template -├── alembic.ini # Alembic configuration -└── models/ # SQLAlchemy models - ├── __init__.py - ├── user.py - └── post.py -``` - -### alembic.ini Configuration -```ini -[alembic] -script_location = alembic -sqlalchemy.url = driver://user:pass@localhost/dbname - -[loggers] -keys = root,sqlalchemy,alembic - -[logger_alembic] -level = INFO -handlers = console -qualname = alembic -``` - -## References - -- [Alembic Documentation](https://alembic.sqlalchemy.org/) -- [SQLAlchemy Documentation](https://docs.sqlalchemy.org/) -- [Project Migration Guidelines](docs/database-migrations.md) -``` - -### 为什么这是好的 Skill? - -1. ✅ **清晰的 description**: 包含触发关键词 ("Alembic", "create migrations") 和场景 ("SQLAlchemy projects") -2. ✅ **具体的触发条件**: "When to Use" 列出 4 个明确场景 -3. ✅ **分步工作流**: 每个操作都有清晰的 1-2-3 步骤 -4. ✅ **实际示例**: 包含简单和复杂两个示例,有完整代码 -5. ✅ **最佳实践**: Do/Don't 清单易于遵循 -6. ✅ **故障排除**: 覆盖 3 个常见问题及解决方案 -7. ✅ **项目特定信息**: 包含配置和目录结构 - ---- - -## 示例 2: API 文档生成 Skill (优秀的工作流 Skill) - -```markdown ---- -name: api-documentation-generation -description: Generates OpenAPI/Swagger documentation from FastAPI or Flask applications. Activates when user asks to create API docs, generate OpenAPI spec, or needs to document REST endpoints. Supports automatic extraction and custom annotations. ---- - -# API Documentation Generation Skill - -Automates creation of comprehensive API documentation from Python web applications. - -## When to Use This Skill - -- User asks to "generate API docs" or "create OpenAPI spec" -- User mentions "Swagger", "OpenAPI", "API documentation" -- User has a FastAPI or Flask application -- User needs to document REST API endpoints - -## Workflow - -### Phase 1: Discovery - -1. **Identify framework** - - Check for FastAPI: `from fastapi import FastAPI` in codebase - - Check for Flask: `from flask import Flask` in codebase - - Check for Flask-RESTful: `from flask_restful import Resource` - -2. **Locate API definitions** - - Scan for route decorators: `@app.get()`, `@app.post()`, `@app.route()` - - Find API routers and blueprints - - Identify request/response models - -3. **Extract metadata** - - Endpoint paths and HTTP methods - - Request parameters (path, query, body) - - Response schemas and status codes - - Authentication requirements - -### Phase 2: Enhancement - -1. **Review docstrings** - - Check if endpoints have docstrings - - Verify docstrings follow format (summary, description, params, returns) - - Flag missing documentation - -2. **Add missing docs** (if user approves) - - Generate docstrings based on type hints - - Infer descriptions from parameter names - - Add example requests/responses - -3. **Validate schemas** - - Ensure Pydantic models are well-documented - - Check for missing field descriptions - - Verify example values are provided - -### Phase 3: Generation - -1. **Generate OpenAPI spec** - ```bash - # For FastAPI - python -c "from main import app; import json; print(json.dumps(app.openapi()))" > openapi.json - - # For Flask with flasgger - python scripts/generate_swagger.py > swagger.json - ``` - -2. **Create Swagger UI** - - Copy Swagger UI static files to `docs/api/` - - Configure to load generated spec - - Test in browser: `http://localhost:8000/docs` - -3. **Generate Markdown docs** - - Use `openapi-to-md` to create human-readable docs - - Organize by tags/resource groups - - Add navigation and table of contents - -### Phase 4: Validation - -1. **Check completeness** - - All endpoints documented? - - All parameters described? - - Example requests provided? - -2. **Validate spec** - ```bash - openapi-spec-validator openapi.json - ``` - -3. **Test interactive docs** - - Try sample requests in Swagger UI - - Verify authentication flows work - - Check response schemas match actual responses - -## Examples - -### Example 1: FastAPI Application - -**User Request**: "Generate API documentation for my FastAPI app" - -**Discovery**: -``` -Found FastAPI application in: main.py -Endpoints discovered: -- GET /users (List users) -- POST /users (Create user) -- GET /users/{id} (Get user by ID) -- PUT /users/{id} (Update user) -- DELETE /users/{id} (Delete user) -``` - -**Enhancement**: -``` -Checking documentation coverage... -✓ GET /users - Well documented -✗ POST /users - Missing response examples -✗ GET /users/{id} - No description -✗ PUT /users/{id} - No description -✗ DELETE /users/{id} - No description - -Would you like me to add missing documentation? -``` - -**User**: Yes - -**Adding docs**: -```python -@app.get("/users/{id}", summary="Get user by ID") -async def get_user(id: int): - """ - Retrieve a single user by their unique ID. - - Args: - id: The unique identifier of the user - - Returns: - User object with id, name, email, and created_at fields - - Raises: - 404: User not found - """ - # ... implementation -``` - -**Generation**: -```bash -Generating OpenAPI specification... -✓ openapi.json created (15.2 KB) -✓ Swagger UI deployed to docs/api/ -✓ Markdown docs created in docs/api/endpoints/ - -View documentation at: http://localhost:8000/docs -``` - -### Example 2: Flask Application with Custom Schemas - -**User Request**: "Document my Flask API and include request/response examples" - -**Discovery**: -``` -Found Flask application with Flask-RESTful -Endpoints: -- GET /api/products -- POST /api/products -- GET /api/products/ -- PATCH /api/products/ -- DELETE /api/products/ -``` - -**Custom Examples Added**: -```python -class ProductList(Resource): - def get(self): - """ - Get all products - - Example Response: - ```json - { - "products": [ - { - "id": 1, - "name": "Widget", - "price": 29.99, - "stock": 100 - } - ], - "total": 1 - } - ``` - """ - pass - - def post(self): - """ - Create a new product - - Example Request: - ```json - { - "name": "New Widget", - "price": 39.99, - "stock": 50 - } - ``` - - Example Response: - ```json - { - "id": 2, - "name": "New Widget", - "price": 39.99, - "stock": 50, - "created_at": "2025-01-31T12:00:00Z" - } - ``` - """ - pass -``` - -**Result**: -``` -Generated documentation: -- openapi.json (with examples) -- Swagger UI at /api/docs -- Postman collection at docs/api/postman_collection.json -- Markdown API reference at docs/api/README.md - -All endpoints now include: -✓ Request examples -✓ Response examples -✓ Error codes -✓ Authentication requirements -``` - -## Configuration - -### FastAPI Projects - -No additional configuration needed! FastAPI auto-generates OpenAPI docs. - -Access at: -- Swagger UI: `http://localhost:8000/docs` -- ReDoc: `http://localhost:8000/redoc` -- OpenAPI JSON: `http://localhost:8000/openapi.json` - -### Flask Projects - -Install flasgger: -```bash -pip install flasgger -``` - -Configure in app: -```python -from flasgger import Swagger - -app = Flask(__name__) -swagger = Swagger(app, template={ - "info": { - "title": "My API", - "description": "API for managing resources", - "version": "1.0.0" - } -}) -``` - -## Best Practices - -- ✅ Use type hints - enables automatic schema generation -- ✅ Write descriptive docstrings for all endpoints -- ✅ Provide example requests and responses -- ✅ Document error codes and edge cases -- ✅ Keep docs in sync with code (auto-generate when possible) - -## Tools Used - -- **FastAPI**: Built-in OpenAPI support -- **flasgger**: Swagger for Flask -- **openapi-spec-validator**: Validates OpenAPI specs -- **openapi-to-md**: Converts OpenAPI to Markdown - -## References - -- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) -- [FastAPI Documentation](https://fastapi.tiangolo.com/) -- [Swagger Documentation](https://swagger.io/docs/) -``` - -### 为什么这是优秀的工作流 Skill? - -1. ✅ **清晰的工作流阶段**: 4 个阶段 (Discovery, Enhancement, Generation, Validation) -2. ✅ **决策点**: Phase 2 询问用户是否添加缺失文档 -3. ✅ **实际输出示例**: 展示了命令输出和生成的代码 -4. ✅ **多框架支持**: 处理 FastAPI 和 Flask 两种情况 -5. ✅ **工具集成**: 列出所需工具及其用途 -6. ✅ **可执行命令**: 提供完整的命令示例 -7. ✅ **验证步骤**: Phase 4 确保生成的文档质量 - ---- - -## 示例 3: 代码审查 Skill (高自由度 Skill) - -```markdown ---- -name: code-review -description: Performs comprehensive code reviews focusing on best practices, security, performance, and maintainability. Activates when user asks to review code, check pull request, or mentions code quality. Provides actionable feedback with severity ratings. ---- - -# Code Review Skill - -Conducts thorough code reviews with focus on quality, security, and best practices. - -## When to Use This Skill - -- User asks to "review my code" or "check this PR" -- User mentions "code review", "code quality", or "best practices" -- User wants feedback on specific code changes -- User needs security or performance analysis - -## Review Criteria - -Code is evaluated across 5 dimensions: - -### 1. Correctness -- Logic errors and bugs -- Edge case handling -- Error handling and validation -- Type safety - -### 2. Security -- SQL injection vulnerabilities -- XSS vulnerabilities -- Authentication/authorization issues -- Sensitive data exposure -- Dependency vulnerabilities - -### 3. Performance -- Algorithm efficiency -- Database query optimization -- Memory leaks -- Unnecessary computations -- Caching opportunities - -### 4. Maintainability -- Code clarity and readability -- Function/class size -- Code duplication -- Naming conventions -- Documentation - -### 5. Best Practices -- Language-specific idioms -- Design patterns -- SOLID principles -- Testing coverage -- Error handling patterns - -## Review Process - -1. **Understand context** - - What does this code do? - - What problem does it solve? - - Are there any constraints or requirements? - -2. **Identify issues** - - Scan for common anti-patterns - - Check against language best practices - - Look for security vulnerabilities - - Assess performance implications - -3. **Prioritize feedback** - - **Critical**: Security issues, data loss risks, crashes - - **High**: Bugs, major performance issues - - **Medium**: Code smells, maintainability concerns - - **Low**: Style preferences, minor optimizations - -4. **Provide suggestions** - - Explain the issue clearly - - Show better alternative (code example) - - Explain why the alternative is better - -## Example Review - -### Code Submitted - -```python -def get_user_data(user_id): - conn = sqlite3.connect('users.db') - cursor = conn.cursor() - query = "SELECT * FROM users WHERE id = " + str(user_id) - cursor.execute(query) - result = cursor.fetchone() - return result -``` - -### Review Feedback - -**❌ CRITICAL: SQL Injection Vulnerability** - -The code concatenates user input directly into SQL query, allowing SQL injection attacks. - -**Bad**: -```python -query = "SELECT * FROM users WHERE id = " + str(user_id) -``` - -**Good**: -```python -query = "SELECT * FROM users WHERE id = ?" -cursor.execute(query, (user_id,)) -``` - -**Why**: Parameterized queries prevent SQL injection by properly escaping user input. - ---- - -**⚠️ HIGH: Resource Leak** - -Database connection is never closed, leading to resource exhaustion under load. - -**Bad**: -```python -conn = sqlite3.connect('users.db') -# ... use connection -# connection never closed -``` - -**Good**: -```python -with sqlite3.connect('users.db') as conn: - cursor = conn.cursor() - # ... use connection - # automatically closed when exiting with block -``` - ---- - -**ℹ️ MEDIUM: Overly Broad SELECT** - -Using `SELECT *` fetches unnecessary data and is fragile to schema changes. - -**Bad**: -```python -query = "SELECT * FROM users WHERE id = ?" -``` - -**Good**: -```python -query = "SELECT id, name, email FROM users WHERE id = ?" -``` - -**Why**: Explicit column selection is more efficient and makes intent clear. - ---- - -**📝 LOW: Missing Error Handling** - -Function doesn't handle case where user doesn't exist. - -**Suggestion**: -```python -def get_user_data(user_id: int) -> Optional[dict]: - """ - Retrieve user data by ID. - - Args: - user_id: The unique identifier of the user - - Returns: - Dictionary with user data, or None if user not found - """ - with sqlite3.connect('users.db') as conn: - cursor = conn.cursor() - query = "SELECT id, name, email FROM users WHERE id = ?" - cursor.execute(query, (user_id,)) - result = cursor.fetchone() - - if result is None: - return None - - return { - 'id': result[0], - 'name': result[1], - 'email': result[2] - } -``` - -### Revised Code - -After applying all suggestions: - -```python -from typing import Optional -import sqlite3 - -def get_user_data(user_id: int) -> Optional[dict]: - """ - Retrieve user data by ID. - - Args: - user_id: The unique identifier of the user - - Returns: - Dictionary with user data, or None if user not found - - Raises: - ValueError: If user_id is not a positive integer - """ - if not isinstance(user_id, int) or user_id <= 0: - raise ValueError(f"Invalid user_id: {user_id}") - - with sqlite3.connect('users.db') as conn: - conn.row_factory = sqlite3.Row # Enable dict-like access - cursor = conn.cursor() - - query = "SELECT id, name, email, created_at FROM users WHERE id = ?" - cursor.execute(query, (user_id,)) - result = cursor.fetchone() - - if result is None: - return None - - return dict(result) # Convert Row to dict -``` - -### Summary - -**Issues Found**: 4 -- 1 Critical (SQL Injection) -- 1 High (Resource Leak) -- 1 Medium (Inefficient Query) -- 1 Low (Missing Error Handling) - -**All Issues Addressed**: ✓ - -## Best Practices - -### When Reviewing - -- 🎯 Focus on impact - prioritize critical issues -- 📝 Be specific - provide code examples -- 🎓 Be educational - explain why, not just what -- 🤝 Be constructive - suggest improvements, don't just criticize -- ⚖️ Be balanced - acknowledge good practices too - -### What to Look For - -**Python-specific**: -- Use of `with` for resource management -- Type hints on function signatures -- Proper exception handling -- List comprehensions vs loops -- Dictionary vs if-elif chains - -**General**: -- DRY principle violations -- Magic numbers -- Long functions (>50 lines) -- Deep nesting (>3 levels) -- Missing tests for critical paths - -## Automated Tools - -Complement manual review with automated tools: - -```bash -# Linting -pylint mycode.py -flake8 mycode.py - -# Type checking -mypy mycode.py - -# Security scanning -bandit -r . -safety check - -# Code complexity -radon cc mycode.py -a -``` - -## References - -- [OWASP Top 10](https://owasp.org/www-project-top-ten/) -- [Python Best Practices](https://docs.python-guide.org/) -- [Clean Code Principles](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882) -``` - -### 为什么这是高自由度 Skill? - -1. ✅ **指导原则而非严格步骤**: 提供评审维度,不限定具体流程 -2. ✅ **情境适应**: 根据代码类型和问题严重性调整重点 -3. ✅ **教育性**: 解释"为什么",帮助 Claude 做出判断 -4. ✅ **优先级框架**: 定义严重性级别,让 Claude 自行判断 -5. ✅ **完整示例**: 展示从问题识别到解决的完整流程 -6. ✅ **工具集成**: 提到自动化工具,但不强制使用 - ---- - -## 总结: 好 Skill 的共同特征 - -| 特征 | 说明 | 示例位置 | -|------|------|---------| -| **清晰触发** | description 包含关键词和场景 | 所有 frontmatter | -| **结构化内容** | 使用标题、列表、代码块组织信息 | 所有示例 | -| **实际示例** | 真实代码,不是伪代码 | Example sections | -| **决策指导** | 告诉 Claude 何时做什么 | 工作流 Skill 的 Phase 2 | -| **可执行命令** | 提供完整的命令,不是抽象描述 | 迁移 Skill 的命令 | -| **错误处理** | 包含故障排除章节 | 所有 Troubleshooting | -| **最佳实践** | Do/Don't 清单 | 所有 Best Practices | -| **工具引用** | 说明使用哪些工具及如何使用 | API 文档 Skill | -| **验证步骤** | 说明如何确认操作成功 | 迁移 Skill 的验证 | -| **合适的自由度** | 根据任务特性选择指导程度 | 代码审查 Skill | diff --git a/.claude/skills/system-create_skill_file/templates/basic-skill-template.md b/.claude/skills/system-create_skill_file/templates/basic-skill-template.md deleted file mode 100644 index 8ff71762d1..0000000000 --- a/.claude/skills/system-create_skill_file/templates/basic-skill-template.md +++ /dev/null @@ -1,95 +0,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 diff --git a/.claude/skills/system-create_skill_file/templates/workflow-skill-template.md b/.claude/skills/system-create_skill_file/templates/workflow-skill-template.md deleted file mode 100644 index 6fd6522bad..0000000000 --- a/.claude/skills/system-create_skill_file/templates/workflow-skill-template.md +++ /dev/null @@ -1,402 +0,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 diff --git a/document/content/docs/faq/app.en.mdx b/document/content/docs/faq/app.en.mdx new file mode 100644 index 0000000000..e6e3eaf7dc --- /dev/null +++ b/document/content/docs/faq/app.en.mdx @@ -0,0 +1,77 @@ +--- +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$$ +``` diff --git a/document/content/docs/faq/chat.en.mdx b/document/content/docs/faq/chat.en.mdx new file mode 100644 index 0000000000..2ca913f9b7 --- /dev/null +++ b/document/content/docs/faq/chat.en.mdx @@ -0,0 +1,14 @@ +--- +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. diff --git a/document/content/docs/faq/dataset.en.mdx b/document/content/docs/faq/dataset.en.mdx new file mode 100644 index 0000000000..0dc2b5ae59 --- /dev/null +++ b/document/content/docs/faq/dataset.en.mdx @@ -0,0 +1,75 @@ +--- +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. diff --git a/document/content/docs/faq/error.en.mdx b/document/content/docs/faq/error.en.mdx new file mode 100644 index 0000000000..ef6479462d --- /dev/null +++ b/document/content/docs/faq/error.en.mdx @@ -0,0 +1,11 @@ +--- +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. diff --git a/document/content/docs/faq/external_channel_integration.en.mdx b/document/content/docs/faq/external_channel_integration.en.mdx new file mode 100644 index 0000000000..76c7c673ec --- /dev/null +++ b/document/content/docs/faq/external_channel_integration.en.mdx @@ -0,0 +1,14 @@ +--- +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) diff --git a/document/content/docs/faq/index.en.mdx b/document/content/docs/faq/index.en.mdx new file mode 100644 index 0000000000..6c1df1df14 --- /dev/null +++ b/document/content/docs/faq/index.en.mdx @@ -0,0 +1,8 @@ +--- +title: FAQ +description: FastGPT frequently asked questions +--- + +import { Redirect } from '@/components/docs/Redirect'; + + diff --git a/document/content/docs/faq/meta.en.json b/document/content/docs/faq/meta.en.json new file mode 100644 index 0000000000..e48398132a --- /dev/null +++ b/document/content/docs/faq/meta.en.json @@ -0,0 +1,14 @@ +{ + "root": true, + "title": "FAQ", + "description": "FastGPT FAQ", + "pages": [ + "app", + "chat", + "dataset", + "external_channel_integration", + "error", + "points_consumption", + "other" + ] +} diff --git a/document/content/docs/faq/other.en.mdx b/document/content/docs/faq/other.en.mdx new file mode 100644 index 0000000000..8bf2e9e666 --- /dev/null +++ b/document/content/docs/faq/other.en.mdx @@ -0,0 +1,11 @@ +--- +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. diff --git a/document/content/docs/faq/points_consumption.en.mdx b/document/content/docs/faq/points_consumption.en.mdx new file mode 100644 index 0000000000..3f933a850d --- /dev/null +++ b/document/content/docs/faq/points_consumption.en.mdx @@ -0,0 +1,10 @@ +--- +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) diff --git a/document/content/docs/introduction/cloud.en.mdx b/document/content/docs/introduction/cloud.en.mdx new file mode 100644 index 0000000000..163a140487 --- /dev/null +++ b/document/content/docs/introduction/cloud.en.mdx @@ -0,0 +1,11 @@ +--- +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. diff --git a/document/content/docs/introduction/commercial.en.mdx b/document/content/docs/introduction/commercial.en.mdx new file mode 100644 index 0000000000..ad1b01b479 --- /dev/null +++ b/document/content/docs/introduction/commercial.en.mdx @@ -0,0 +1,109 @@ +--- +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.
2. No ops or database management needed. | Half day | Starting at ¥10,000/month (3-month minimum)
or
Starting at ¥120,000/year
8C32G resources; additional resources billed separately. | +| Sealos Fully Managed (Multi-node) | 1. Free upgrades during license period.
2. No ops or database management needed. | Half day | Starting at ¥22,000/month (3-month minimum)
or
Starting at ¥264,000/year
32C128G resources; additional resources billed separately. | +| Self-hosted | 1. Free upgrade support for 6 versions. | Within 14 days | [Contact us for pricing](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc) | + + + - "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. + + +## 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) | diff --git a/document/content/docs/introduction/development/configuration.en.mdx b/document/content/docs/introduction/development/configuration.en.mdx new file mode 100644 index 0000000000..057e0c7132 --- /dev/null +++ b/document/content/docs/introduction/development/configuration.en.mdx @@ -0,0 +1,73 @@ +--- +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) diff --git a/document/content/docs/introduction/development/custom-models/bge-rerank.en.mdx b/document/content/docs/introduction/development/custom-models/bge-rerank.en.mdx new file mode 100644 index 0000000000..4425be3b6b --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/bge-rerank.en.mdx @@ -0,0 +1,137 @@ +--- +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' + ... +``` diff --git a/document/content/docs/introduction/development/custom-models/chatglm2-m3e.en.mdx b/document/content/docs/introduction/development/custom-models/chatglm2-m3e.en.mdx new file mode 100644 index 0000000000..3291566f71 --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/chatglm2-m3e.en.mdx @@ -0,0 +1,116 @@ +--- +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. diff --git a/document/content/docs/introduction/development/custom-models/chatglm2.en.mdx b/document/content/docs/introduction/development/custom-models/chatglm2.en.mdx new file mode 100644 index 0000000000..97566e38e7 --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/chatglm2.en.mdx @@ -0,0 +1,120 @@ +--- +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). + + +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. + + +## 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. diff --git a/document/content/docs/introduction/development/custom-models/m3e.en.mdx b/document/content/docs/introduction/development/custom-models/m3e.en.mdx new file mode 100644 index 0000000000..fdc1784de9 --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/m3e.en.mdx @@ -0,0 +1,85 @@ +--- +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) diff --git a/document/content/docs/introduction/development/custom-models/marker.en.mdx b/document/content/docs/introduction/development/custom-models/marker.en.mdx new file mode 100644 index 0000000000..f86f855342 --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/marker.en.mdx @@ -0,0 +1,99 @@ +--- +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. diff --git a/document/content/docs/introduction/development/custom-models/meta.en.json b/document/content/docs/introduction/development/custom-models/meta.en.json new file mode 100644 index 0000000000..36a55a1d1c --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/meta.en.json @@ -0,0 +1,13 @@ +{ + "title": "Local Model Usage", + "pages": [ + "marker", + "mineru", + "xinference", + "bge-rerank", + "chatglm2", + "m3e", + "chatglm2-m3e", + "ollama" + ] +} diff --git a/document/content/docs/introduction/development/custom-models/mineru.en.mdx b/document/content/docs/introduction/development/custom-models/mineru.en.mdx new file mode 100644 index 0000000000..0954becd86 --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/mineru.en.mdx @@ -0,0 +1,82 @@ +--- +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. diff --git a/document/content/docs/introduction/development/custom-models/ollama.en.mdx b/document/content/docs/introduction/development/custom-models/ollama.en.mdx new file mode 100644 index 0000000000..b192712cd6 --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/ollama.en.mdx @@ -0,0 +1,180 @@ +--- +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]". diff --git a/document/content/docs/introduction/development/custom-models/xinference.en.mdx b/document/content/docs/introduction/development/custom-models/xinference.en.mdx new file mode 100644 index 0000000000..6263741680 --- /dev/null +++ b/document/content/docs/introduction/development/custom-models/xinference.en.mdx @@ -0,0 +1,158 @@ +--- +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) diff --git a/document/content/docs/introduction/development/design/dataset.en.mdx b/document/content/docs/introduction/development/design/dataset.en.mdx new file mode 100644 index 0000000000..79835dc35a --- /dev/null +++ b/document/content/docs/introduction/development/design/dataset.en.mdx @@ -0,0 +1,21 @@ +--- +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. diff --git a/document/content/docs/introduction/development/design/design_plugin.en.mdx b/document/content/docs/introduction/development/design/design_plugin.en.mdx new file mode 100644 index 0000000000..4ed8407cbf --- /dev/null +++ b/document/content/docs/introduction/development/design/design_plugin.en.mdx @@ -0,0 +1,82 @@ +--- +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. diff --git a/document/content/docs/introduction/development/design/meta.en.json b/document/content/docs/introduction/development/design/meta.en.json new file mode 100644 index 0000000000..26a4fbfff3 --- /dev/null +++ b/document/content/docs/introduction/development/design/meta.en.json @@ -0,0 +1,7 @@ +{ + "title": "Design Solutions", + "pages": [ + "dataset", + "design_plugin" + ] +} diff --git a/document/content/docs/introduction/development/docker.en.mdx b/document/content/docs/introduction/development/docker.en.mdx new file mode 100644 index 0000000000..380e21f03b --- /dev/null +++ b/document/content/docs/introduction/development/docker.en.mdx @@ -0,0 +1,409 @@ +--- +title: Deploy with Docker +description: Quickly deploy FastGPT using Docker Compose +--- + +import { Alert } from '@/components/docs/Alert'; + +## Prerequisites + +1. Basic networking knowledge: ports, firewalls, etc. +2. Docker and Docker Compose basics + +## Deployment Architecture + +![](/imgs/sealos-fastgpt.webp) + + + +- MongoDB: Stores all data except vectors +- PostgreSQL/Milvus/Oceanbase/SeekDB: Stores vector data +- AIProxy: Aggregates various AI APIs with multi-model support (for any model issues, test with OneAPI first) + + + +## Recommended Specs + +### PgVector Version + +Very lightweight, suitable for knowledge base indexes under 50 million. + +| Environment | Minimum (Single Node) | Recommended | +| ---------------------------------- | --------------------- | ------------ | +| Testing (reduce compute processes) | 2c4g | 2c8g | +| 1M vector groups | 4c8g 50GB | 4c16g 50GB | +| 5M vector groups | 8c32g 200GB | 16c64g 200GB | + +### Milvus Version + +Better performance for 100M+ vectors. + +[View Milvus official recommended specs](https://milvus.io/docs/prerequisite-docker.md) + +| Environment | Minimum (Single Node) | Recommended | +| ---------------- | --------------------- | ----------- | +| Testing | 2c8g | 4c16g | +| 1M vector groups | Not tested | | +| 5M vector groups | | | + +### Zilliz Cloud Version + +Zilliz Cloud is built by the Milvus team — a fully managed SaaS vector database with better performance than Milvus and SLA guarantees. [Try Zilliz Cloud](https://zilliz.com.cn/). + +Since the vector database runs in the cloud, no local resources are needed. + +### SeekDB Version + +SeekDB is a high-performance vector database based on MySQL protocol, fully compatible with OceanBase, supporting efficient vector retrieval. + +| Environment | Minimum (Single Node) | Recommended | +| ---------------------------------- | --------------------- | ------------ | +| Testing (reduce compute processes) | 2c4g | 2c8g | +| 1M vector groups | 4c8g 50GB | 4c16g 50GB | +| 5M vector groups | 8c32g 200GB | 16c64g 200GB | + + + +SeekDB uses MySQL protocol, fully compatible with OceanBase: +- Supports 1536-dimensional vector retrieval +- Built-in HNSW index algorithm +- Batch insert and query optimization +- Automatic retry and connection pool management + + + +## Preparation + +### 1. Ensure Network Access + +If using `OpenAI` or other international model APIs, make sure you can access them, or you'll get `Connection error`. See: [Proxy Solutions](/docs/introduction/development/proxy/nginx) + +### 2. Prepare Docker Environment + + + +```bash +# Install Docker +curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun +systemctl enable --now docker +# Install docker-compose +curl -L https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose +chmod +x /usr/local/bin/docker-compose +# Verify installation +docker -v +docker-compose -v +# If it fails, search online for solutions +``` + + +We recommend [Orbstack](https://orbstack.dev/). Install via Homebrew: + +```bash +brew install orbstack +``` + +Or [download the installer](https://orbstack.dev/download) directly. + + + +We recommend storing source code and data in the Linux filesystem when binding to Linux containers, not the Windows filesystem. + +You can [install Docker Desktop with WSL 2 backend on Windows](https://docs.docker.com/desktop/wsl/). + +Or [install the command-line version of Docker directly in WSL 2](https://nickjanetakis.com/blog/install-docker-in-wsl-2-without-docker-desktop). + + + + +## Start Deployment + +### 1. Get Configuration Files + +#### Method 1: Interactive Script Deployment + +Run in Linux/MacOS/Windows WSL. The script guides you through selecting deployment environment, vector database version, IP address, etc. + +```bash +bash <(curl -fsSL https://doc.fastgpt.cn/deploy/install.sh) +``` + +#### Method 2: Manual Download +If your environment is non-*nix or can't access external networks, manually download `docker-compose.yml`. + +1. Download the `docker-compose.yml` file: + +
+Click to view docker-compose config file download links for different databases + +- **Pgvector** + - China mirror (Alibaba Cloud): [docker-compose.pg.yml](https://doc.fastgpt.cn/deploy/docker/cn/docker-compose.pg.yml) + - Global mirror (dockerhub, ghcr): [docker-compose.pg.yml](https://doc.fastgpt.cn/deploy/docker/global/docker-compose.pg.yml) +- **Oceanbase** + - China mirror (Alibaba Cloud): [docker-compose.ob.yml](https://doc.fastgpt.cn/deploy/docker/cn/docker-compose.ob.yml) + - Global mirror (dockerhub, ghcr): [docker-compose.ob.yml](https://doc.fastgpt.cn/deploy/docker/global/docker-compose.ob.yml) +- **Milvus** + - China mirror (Alibaba Cloud): [docker-compose.milvus.yml](https://doc.fastgpt.cn/deploy/docker/cn/docker-compose.milvus.yml) + - Global mirror (dockerhub, ghcr): [docker-compose.milvus.yml](https://doc.fastgpt.cn/deploy/docker/global/docker-compose.milvus.yml) +- **Zilliz** + - China mirror (Alibaba Cloud): [docker-compose.zilliz.yml](https://doc.fastgpt.cn/deploy/docker/cn/docker-compose.zilliz.yml) + - Global mirror (dockerhub, ghcr): [docker-compose.zilliz.yml](https://doc.fastgpt.cn/deploy/docker/global/docker-compose.zilliz.yml) +- **SeekDB** + - China mirror (Alibaba Cloud): [docker-compose.seekdb.yml](https://doc.fastgpt.cn/deploy/docker/cn/docker-compose.seekdb.yml) + - Global mirror (dockerhub, ghcr): [docker-compose.seekdb.yml](https://doc.fastgpt.cn/deploy/docker/global/docker-compose.seekdb.yml) + +2. Download the `config.json` file: +- [config.json](https://doc.fastgpt.cn/deploy/config/config.json) + +
+ +Download config.json file: +- [config.json](https://doc.fastgpt.cn/deploy/config/config.json) + +### 2. Modify Environment Variables + +For `Zilliz version`, you also need credentials — see [Deploy Zilliz Version: Get Account and Credentials](#deploy-zilliz-version-get-account-and-credentials). Other versions can skip to the next step. + +### 3. Open External Ports / Configure Domain + +These ports must be accessible: + +1. Port 3000 (FastGPT main service) +2. Port 9000 (S3 service) +1. Port 3005 (FastGPT SSE MCP server service) + +### 4. Start Containers + +Run in the same directory as docker-compose.yml. Ensure `docker-compose` version is 2.17+, or automated commands may fail. + +```bash +# Start containers +docker-compose up -d +``` + +### 5. Access FastGPT + +Access FastGPT via the port/domain opened in step 3. +Login username is `root`, password is the `DEFAULT_ROOT_PSW` set in `docker-compose.yml` environment variables. +Each container restart automatically initializes the root user with password `1234` (matching `DEFAULT_ROOT_PSW`). + +### 6. Configure Models + +- After first login, the system prompts that `Language Model` and `Index Model` are not configured and automatically redirects to the model configuration page. At least these two model types are required. +- If the redirect doesn't happen, go to `Account - Model Providers` to configure models. [View tutorial](/docs/introduction/development/modelConfig/ai-proxy) +- Known issue: after first entering the system, the browser tab may become unresponsive. Close the tab and reopen it. + +### 7. Install System Plugins as Needed + +Starting from V4.14.0, the fastgpt-plugin image only provides the runtime environment without pre-installed system plugins. All FastGPT systems must manually install system plugins. + +* Install via the plugin marketplace — by default it fetches from the public FastGPT Marketplace. +* If your FastGPT can't access the marketplace, visit [FastGPT Plugin Marketplace](https://marketplace.fastgpt.cn/), download .pkg files, and import them via file upload. +* You can also sort tools, set default installations, and manage tags. + +![alt text](/imgs/image-121.png) + +## FAQ + +### FastGPT and FastGPT-plugin Version Compatibility + +| FastGPT-plugin Version | FastGPT Main Service | +| ---------------------- | -------------------- | +| 0.5.x | >= 4.14.6 | +| < 0.5.0 | < 4.14.6 | + +### S3 Connection Issues + +Check the `STORAGE_EXTERNAL_ENDPOINT` variable — it must be accessible by both the client and FastGPT service. + +**Important:** + +> Don't use `127.0.0.1` or `localhost` or other loopback addresses. Use the host machine's local IP when deploying with Docker, but set it to a static IP; or use a fixed domain name. This prevents 403 errors caused by URL mismatches when signing object storage URLs. +> +> See [Object Storage Configuration & Common Issues](/docs/introduction/development/object-storage) + +### Browser Unresponsive After Login + +Can't click anything, refresh doesn't help. Close the tab and reopen it. + +### Mongo Replica Set Auto-Initialization Failed + +The latest docker-compose examples have fully automated Mongo replica set initialization. Tested on Ubuntu 20/22, CentOS 7, WSL2, macOS, and Windows. If it still won't start, the CPU likely doesn't support AVX instructions — switch to Mongo 4.x. + +To manually initialize the replica set: + +1. Create a mongo key in the terminal: + +```bash +openssl rand -base64 756 > ./mongodb.key +chmod 600 ./mongodb.key +# Change key permissions — some systems use admin, others use root +chown 999:root ./mongodb.key +``` + +2. Modify docker-compose.yml to mount the key: + +```yml +mongo: + # image: mongo:5.0.18 + # image: registry.cn-hangzhou.aliyuncs.com/fastgpt/mongo:5.0.18 # Alibaba Cloud + container_name: mongo + ports: + - 27017:27017 + networks: + - fastgpt + command: mongod --keyFile /data/mongodb.key --replSet rs0 + environment: + # Default username and password, only effective on first run + - MONGO_INITDB_ROOT_USERNAME=myusername + - MONGO_INITDB_ROOT_PASSWORD=mypassword + volumes: + - ./mongo/data:/data/db + - ./mongodb.key:/data/mongodb.key +``` + +3. Restart services: + +```bash +docker-compose down +docker-compose up -d +``` + +4. Enter the container and initialize the replica set: + +```bash +# Check if mongo container is running +docker ps +# Enter container +docker exec -it mongo bash + +# Connect to database (use your Mongo username and password) +mongo -u myusername -p mypassword --authenticationDatabase admin + +# Initialize replica set. For external access, add directConnection=true to the Mongo connection parameters +rs.initiate({ + _id: "rs0", + members: [ + { _id: 0, host: "mongo:27017" } + ] +}) +# Check status — if it shows rs0 status, it's running successfully +rs.status() +``` + +### How to Change API Address and Key + +By default, OneAPI connection address and key are configured. Modify the environment variables in the fastgpt container in `docker-compose.yml`: + +`OPENAI_BASE_URL` (API endpoint, must include /v1) +`CHAT_API_KEY` (API credentials) + +After modifying, restart: + +```bash +docker-compose down +docker-compose up -d +``` + +### How to Update Versions? + +1. Check the [update documentation](/docs/upgrading) to confirm the target version — avoid skipping versions. +2. Change the image tag to the target version +3. Run these commands to pull and restart: + + ```bash + docker-compose pull + docker-compose up -d + ``` + +4. Run initialization scripts (if any) + +### How to Customize Configuration Files? + +Modify `config.json`, then run `docker-compose down` followed by `docker-compose up -d` to restart. For details, see [Configuration Guide](/docs/introduction/development/configuration). + +### How to Check if Custom Config File is Mounted + +1. `docker logs fastgpt` shows logs. After starting the container, the first web request reads the config file — check for success or error messages. +2. `docker exec -it fastgpt sh` enters the container. Use `ls data` to check if `config.json` is mounted. Use `cat data/config.json` to view it. + +**Possible reasons it's not working:** + +1. Incorrect mount directory +2. Invalid config file — logs will show `invalid json`. The file must be valid JSON. +3. Didn't run `docker-compose down` then `docker-compose up -d` after changes. A simple restart doesn't remount files. + +### How to Check if Environment Variables Loaded + +1. `docker exec -it fastgpt sh` to enter the container. +2. Run `env` to view all environment variables. + +### Why Can't I Connect to Local Model Images + +`docker-compose.yml` uses bridge mode to create the `fastgpt` network. To access other images via 0.0.0.0 or image name, add those images to the same network. + +### How to Resolve Port Conflicts? + +Docker-compose port format: `mapped_port:running_port`. + +In bridge mode, container running ports don't conflict, but mapped ports can. Change the mapped port to a different value. + +If `container1` needs to connect to `container2`, use `container2:running_port`. + +(Brush up on Docker basics as needed) + +### relation "modeldata" does not exist + +PG database not connected or initialization failed — check logs. FastGPT initializes tables on each PG connection. Errors will appear in the logs. + +1. Check if the database container started normally +2. For non-Docker deployments, manually install the pg vector extension +3. Check fastgpt logs for related errors + +### Illegal instruction + +Possible causes: + +1. ARM architecture — use the official Mongo image: mongo:5.0.18 +2. CPU doesn't support AVX — switch to mongo4.x. Change the mongo image to: mongo:4.4.29 + +### Operation `auth_codes.findOne()` buffering timed out after 10000ms + +Mongo connection failed — check mongo's running status and **logs**. + +Possible causes: + +1. Mongo service didn't start (some CPUs don't support AVX — switch to mongo4.x, find the latest 4.x on Docker Hub, update the image version, and rerun) +2. Database connection environment variables are wrong (username/password, check host and port — for non-container network connections, use public IP and add directConnection=true) +3. Replica set startup failed, causing the container to keep restarting +4. `Illegal instruction.... Waiting for MongoDB to start`: CPU doesn't support AVX — switch to mongo4.x + +### First Deployment: Root User Shows Unregistered + +Logs will show error messages. Most likely Mongo replica set mode wasn't started. + +### Can't Export Knowledge Base / Can't Use Voice Input or Playback + +SSL certificate not configured — some features require it. + +### Login Shows Network Error + +Caused by service initialization errors triggering a restart. + +- 90% of cases: incorrect config file causing JSON parsing errors +- The rest: usually because the vector database can't connect + +### How to Change Password + +Modify `DEFAULT_ROOT_PSW` in `docker-compose.yml` and restart — the password auto-updates. + +### Deploy Zilliz Version: Get Account and Credentials + +Open [Zilliz Cloud](https://zilliz.com.cn/), create an instance, and get the credentials. + +![zilliz_key](/imgs/zilliz_key.png) + + + +1. Set `MILVUS_ADDRESS` and `MILVUS_TOKEN` to match Zilliz's `Public Endpoint` and `Api key`. Remember to add your IP to the whitelist. + + diff --git a/document/content/docs/introduction/development/faq.en.mdx b/document/content/docs/introduction/development/faq.en.mdx new file mode 100644 index 0000000000..6e12bd34ab --- /dev/null +++ b/document/content/docs/introduction/development/faq.en.mdx @@ -0,0 +1,393 @@ +--- +title: Private Deployment FAQ +description: FastGPT private deployment common issues +--- + +## 1. Error Troubleshooting + +Check [Issues](https://github.com/labring/FastGPT/issues) first, or create a new one. For private deployment errors, provide detailed steps, logs, and screenshots — otherwise it's very difficult to diagnose. + +### Backend Errors + +1. Run `docker ps -a` to check all container statuses. Verify everything is running. If not, use `docker logs ` to view logs. +2. If containers are running normally, use `docker logs ` to check for error logs. + +### Frontend Errors + +When the frontend crashes, the page will display an error prompting you to check console logs. Open the browser console and check the `console` tab. Click the log hyperlinks to see the specific error file — provide these details for troubleshooting. + +### OneAPI Errors + +Errors with `requestId` are from OneAPI, usually caused by model API issues. See [Common OneAPI Errors](/docs/introduction/development/faq/#3-common-oneapi-errors) + +## 2. General Issues + +### Frontend Page Crash + +1. 90% of cases: incorrect model configuration. Ensure each model type has at least one enabled. Check if `object` parameters are abnormal (arrays and objects) — if empty, try providing an empty array or object. +2. Browser compatibility: the project uses advanced syntax that may not work in older browsers. Provide specific steps and console errors in an issue. +3. Disable browser translation — it can cause page crashes. + +### Does Sealos deployment have fewer limitations than local deployment? + +![](/imgs/faq1.png) +This is the index model's length limit — it's the same regardless of deployment method. Different index models have different configurations, which you can modify in the admin panel. + +### How to Mount Mini Program Config Files + +Mount the verification file to: /app/projects/app/public/xxxx.txt + +Then restart. For example: + +![](/imgs/faq2.png) + +### Database Port 3306 Already in Use + +![](/imgs/faq3.png) + +Change the port mapping to something like 3307, e.g., 3307:3306. + +### Local Deployment Limitations + +See details at https://fael3z0zfze.feishu.cn/wiki/OFpAw8XzAi36Guk8dfucrCKUnjg. + +### Can It Run Fully Offline? + +Yes. You'll need vector models and LLM models ready. + +### Other Models Can't Do Question Classification / Content Extraction + +1. Check logs. If you see "JSON invalid" or "not support tool", the model doesn't support tool/function calling. Set `toolChoice=false` and `functionCall=false` to fall back to prompt mode. Built-in prompts are only tested with commercial model APIs. Question classification mostly works; content extraction is less reliable. +2. If configured correctly with no error logs, the prompts may not suit the model. Customize via `customCQPrompt`. + +### Page Crash + +1. Disable browser translation. +2. Check if the config file loaded properly — missing system info causes null pointer errors. + +- 95% of cases: incorrect config file, showing "xxx undefined" +- "URI malformed" error: report the specific operation and page in an issue — caused by special character encoding errors. + +3. Some API compatibility issues (rare) + +### Slow Response After Enabling Content Completion + +1. Content completion requires an additional AI generation round. +2. Performs 3–5 query rounds — insufficient database performance will cause noticeable slowdowns. + +### Page Works Fine, API Returns Errors + +The page uses `stream=true` mode, so the API also needs `stream=true` for testing. Some model APIs (especially domestic ones) have poor non-stream compatibility. +Same as above — test with curl. + +### Knowledge Base Indexing Has No Progress / Very Slow + +Check error logs first. Possible scenarios: + +1. Can chat but no indexing progress: vector model (vectorModels) not configured +2. Can't chat or index: API call failed — may not be connected to OneAPI or OpenAI +3. Has progress but very slow: API key issue. OpenAI free accounts have very limited rate limits (3 or 60 requests/minute, 200/day). + +### Connection Error + +Network issue. Servers in China can't reach OpenAI directly — verify your AI model connection. + +Or FastGPT can't reach OneAPI (not on the same network). + +### Modified vectorModels But No Effect + +1. Restart the container and confirm the model config loaded (check logs or the new knowledge base creation page). +2. Refresh the browser. +3. For existing knowledge bases, delete and recreate them. The vector model is bound at creation time and won't update dynamically. + +## 3. Common OneAPI Errors + +Errors with `requestId` are from OneAPI. + +### insufficient_user_quota user quota is not enough + +OneAPI account balance insufficient. The default root user only has $200 — increase it manually. + +Path: Open OneAPI -> Users -> Edit root user -> Increase remaining balance + +### xxx Channel Not Found + +The model in FastGPT's config must match a model in OneAPI channels. Check: + +1. The model channel isn't configured in OneAPI, or is disabled. +2. FastGPT config has models not configured in OneAPI. Don't add models to config that OneAPI doesn't have. +3. Created a knowledge base with an old vector model, then updated the vector model. Delete old knowledge bases and recreate. + +If OneAPI doesn't have the model configured, don't add it to `config.json` either. + +### Model Test Click Fails + +OneAPI only tests the first model in a channel, and only chat models. Vector models can't be auto-tested — send manual requests. [View test command examples](/docs/introduction/development/faq/#how-to-check-model-issues) + +### get request url failed: Post `"https://xxx"` dial tcp: xxxx + +OneAPI can't reach the model — check network configuration. + +### Incorrect API key provided: sk-xxxx.You can find your api Key at xxx + +OneAPI API Key configured incorrectly. Modify the `OPENAI_API_KEY` environment variable and restart (`docker-compose down` then `docker-compose up -d`). + +Use `exec` to enter the container, then `env` to verify environment variables. + +### bad_response_status_code bad response status code 503 + +1. Model service unavailable +2. Incompatible model API parameters (temperature, max token, etc.) +3. ... + +### Tiktoken Download Failed + +OneAPI downloads a tiktoken dependency at startup. Network failure causes startup failure. See [OneAPI Offline Deployment](https://blog.csdn.net/wanh/article/details/139039216). + +## 4. Common Model Issues + +### How to Check Model Availability + +1. For self-hosted models, confirm the deployment is working. +2. Use CURL to directly test the upstream model (both cloud and private models). +3. Use CURL to test through OneAPI. +4. Test the model in FastGPT. + +Here are some test CURL examples: + + + +```bash +curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4o", + "messages": [ + { + "role": "system", + "content": "You are a helpful assistant." + }, + { + "role": "user", + "content": "Hello!" + } + ] + }' +``` + + +```bash +curl https://api.openai.com/v1/embeddings \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "input": "The food was delicious and the waiter...", + "model": "text-embedding-ada-002", + "encoding_format": "float" + }' +``` + + +```bash +curl --location --request POST 'https://xxxx.com/api/v1/rerank' \ +--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "model": "bge-rerank-m3", + "query": "导演是谁", + "documents": [ + "你是谁？\n我是电影《铃芽之旅》助手" + ] +}' +``` + + +```bash +curl https://api.openai.com/v1/audio/speech \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "tts-1", + "input": "The quick brown fox jumped over the lazy dog.", + "voice": "alloy" + }' \ + --output speech.mp3 +``` + + +```bash +curl https://api.openai.com/v1/audio/transcriptions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: multipart/form-data" \ + -F file="@/path/to/file/audio.mp3" \ + -F model="whisper-1" +``` + + + +### Error — Model Response Empty / Model Error + +This occurs when OneAPI ends the stream request without returning any content. + +Version 4.8.10 added error logging — the actual request body is printed in logs on error. Copy it and use curl to test against OneAPI. + +Since OneAPI can't properly catch errors in stream mode, you can set `stream=false` to get precise error messages. + +Possible causes: + +1. Content moderation triggered +2. Unsupported model parameters: keep only messages and essential parameters, remove the rest +3. Parameters don't meet model requirements: e.g., some models don't support temperature=0, some don't support two decimal places, max_tokens exceeded, context too long, etc. +4. Model deployment issues with stream mode incompatibility + +Test example — copy the request body from error logs: + +```bash +curl --location --request POST 'https://api.openai.com/v1/chat/completions' \ +--header 'Authorization: Bearer sk-xxxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "model": "xxx", + "temperature": 0.01, + "max_tokens": 1000, + "stream": true, + "messages": [ + { + "role": "user", + "content": " 你是饿" + } + ] +}' +``` + +### How to Test if a Model Supports Tool Calling + +Both the model provider and OneAPI must support tool calling. Test as follows: + +##### 1. Send a first-round stream mode tool call request to OneAPI via `curl`. + +```bash +curl --location --request POST 'https://oneapi.xxx/v1/chat/completions' \ +--header 'Authorization: Bearer sk-xxxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "model": "gpt-5", + "temperature": 0.01, + "max_tokens": 8000, + "stream": true, + "messages": [ + { + "role": "user", + "content": "几点了" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "hCVbIY", + "description": "获取用户当前时区的时间。", + "parameters": { + "type": "object", + "properties": {}, + "required": [] + } + } + } + ], + "tool_choice": "auto" +}' +``` + +##### 2. Check the Response + +If tool calling works, the response includes `tool_calls` parameters. + +```json +{ + "id": "chatcmpl-A7kwo1rZ3OHYSeIFgfWYxu8X2koN3", + "object": "chat.completion.chunk", + "created": 1726412126, + "model": "gpt-5", + "system_fingerprint": "fp_483d39d857", + "choices": [ + { + "index": 0, + "id": "call_0n24eiFk8OUyIyrdEbLdirU7", + "type": "function", + "function": { + "name": "mEYIcFl84rYC", + "arguments": "" + } + } + ], + "refusal": null + }, + "logprobs": null, + "finish_reason": null + } + ], + "usage": null +} +``` + +##### 3. Send a second-round stream mode tool call request to OneAPI via `curl`. + +The second round sends tool results back to the model and returns the model's response. + +```bash +curl --location --request POST 'https://oneapi.xxxx/v1/chat/completions' \ +--header 'Authorization: Bearer sk-xxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "model": "gpt-5", + "temperature": 0.01, + "max_tokens": 8000, + "stream": true, + "messages": [ + { + "role": "user", + "content": "几点了" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "kDia9S19c4RO", + "type": "function", + "function": { + "name": "hCVbIY", + "arguments": "{}" + } + } + ] + }, + { + "tool_call_id": "kDia9S19c4RO", + "role": "tool", + "name": "hCVbIY", + "content": "{\n \"time\": \"2024-09-14 22:59:21 Sunday\"\n}" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "hCVbIY", + "description": "获取用户当前时区的时间。", + "parameters": { + "type": "object", + "properties": {}, + "required": [] + } + } + } + ], + "tool_choice": "auto" +}' +``` + +### Vector Retrieval Score Greater Than 1 + +Caused by the model not being normalized. Only normalized models are currently supported. diff --git a/document/content/docs/introduction/development/intro.en.mdx b/document/content/docs/introduction/development/intro.en.mdx new file mode 100644 index 0000000000..e5918c5b85 --- /dev/null +++ b/document/content/docs/introduction/development/intro.en.mdx @@ -0,0 +1,224 @@ +--- +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 FastGPT. + +## Prerequisites + +Install and configure these dependencies on your machine to build FastGPT: + +- [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:/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 +``` + + + 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. + + +### 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. + + + +## Code Structure + +### Next.js + +FastGPT uses Next.js page routing. To separate frontend and backend code, directories are split into global, service, and web subdirectories for shared, backend-only, and frontend-only code respectively. + +### Monorepo + +FastGPT uses pnpm workspace for its monorepo structure, with two main parts: + +- projects/app - FastGPT main project +- packages/ - Submodules + - global - Shared code: functions, type declarations, and constants usable on both frontend and backend + - service - Server-side code + - web - Frontend code + - plugin - Custom workflow plugin code + +### Domain-Driven Design (DDD) + +FastGPT's code modules follow DDD principles, divided into these domains: + +- core - Core features (knowledge base, workflow, app, conversation) +- support - Supporting features (user system, billing, authentication, etc.) +- common - Base features (log management, file I/O, etc.) + +
+Code Structure Details + +``` +. +├── .github // GitHub config +├── .husky // Formatting config +├── document // Documentation +├── files // External files, e.g., docker-compose, helm +├── packages // Subpackages +│ ├── global // Frontend/backend shared subpackage +│ ├── plugins // Workflow plugins (for custom packages) +│ ├── service // Backend subpackage +│ └── web // Frontend subpackage +├── projects +│ └── app // FastGPT main project +├── python // Model code, unrelated to FastGPT itself +└── scripts // Automation scripts + ├── icon // Icon scripts: pnpm initIcon (write SVG to code), pnpm previewIcon (preview icons) + └── postinstall.sh // ChakraUI custom theme TS type initialization +├── package.json // Top-level monorepo +├── pnpm-lock.yaml +├── pnpm-workspace.yaml // Monorepo declaration +├── Dockerfile +├── LICENSE +├── README.md +├── README_en.md +├── README_ja.md +├── dev.md +``` + +
diff --git a/document/content/docs/introduction/development/meta.en.json b/document/content/docs/introduction/development/meta.en.json new file mode 100644 index 0000000000..3cb5286ffa --- /dev/null +++ b/document/content/docs/introduction/development/meta.en.json @@ -0,0 +1,19 @@ +{ + "title": "Community Edition", + "description": "FastGPT Community Edition", + "icon": "🔧", + "pages": [ + "sealos", + "docker", + "faq", + "intro", + "configuration", + "object-storage", + "signoz", + "modelConfig", + "custom-models", + "proxy", + "migration", + "design" + ] +} diff --git a/document/content/docs/introduction/development/migration/docker_db.en.mdx b/document/content/docs/introduction/development/migration/docker_db.en.mdx new file mode 100644 index 0000000000..0be923c61b --- /dev/null +++ b/document/content/docs/introduction/development/migration/docker_db.en.mdx @@ -0,0 +1,20 @@ +--- +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. diff --git a/document/content/docs/introduction/development/migration/docker_mongo.en.mdx b/document/content/docs/introduction/development/migration/docker_mongo.en.mdx new file mode 100644 index 0000000000..83c55ead5f --- /dev/null +++ b/document/content/docs/introduction/development/migration/docker_mongo.en.mdx @@ -0,0 +1,176 @@ +--- +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. + +image + + +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 +``` +image +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): +iShot_2024-05-09_19 21 26 + +Error state: +iShot_2024-05-09_19 23 13 + + +6. After starting the FastGPT container, log in to the web UI. If all your original data is displayed, the migration was successful. +iShot_2024-05-09_19 23 51 diff --git a/document/content/docs/introduction/development/migration/meta.en.json b/document/content/docs/introduction/development/migration/meta.en.json new file mode 100644 index 0000000000..0acb9cbc83 --- /dev/null +++ b/document/content/docs/introduction/development/migration/meta.en.json @@ -0,0 +1,7 @@ +{ + "title": "Migration & Backup", + "pages": [ + "docker_db", + "docker_mongo" + ] +} diff --git a/document/content/docs/introduction/development/modelConfig/ai-proxy.en.mdx b/document/content/docs/introduction/development/modelConfig/ai-proxy.en.mdx new file mode 100644 index 0000000000..30dda8a994 --- /dev/null +++ b/document/content/docs/introduction/development/modelConfig/ai-proxy.en.mdx @@ -0,0 +1,125 @@ +--- +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. diff --git a/document/content/docs/introduction/development/modelConfig/intro.en.mdx b/document/content/docs/introduction/development/modelConfig/intro.en.mdx new file mode 100644 index 0000000000..2c7174a60f --- /dev/null +++ b/document/content/docs/introduction/development/modelConfig/intro.en.mdx @@ -0,0 +1,462 @@ +--- +title: FastGPT Model Configuration Guide +description: FastGPT Model Configuration Guide +--- + +import { Alert } from '@/components/docs/Alert'; + +Before version 4.8.20, FastGPT model configuration was declared in the `config.json` file. You can find the legacy configuration file example at https://github.com/labring/FastGPT/blob/main/projects/app/data/model.json. + +Starting from version 4.8.20, you can configure models directly in the FastGPT UI. The system includes a large number of built-in models, so you don't need to start from scratch. Here's the basic configuration flow: + +## Configuring Models + +### 1. Connect to Model Providers + +#### AI Proxy + +Starting from version 4.8.23, FastGPT supports configuring model providers directly in the UI using [AI Proxy](/docs/introduction/development/modelconfig/ai-proxy) for model aggregation, enabling connections to more providers. + +#### One API + +You can also use the [OneAPI Integration Guide](/docs/introduction/development/modelconfig/one-api). You'll need to apply for API access from each provider and add them to OneAPI before using them in FastGPT. Example flow: + +![alt text](/imgs/image-95.png) + +Besides official provider services, there are third-party services that offer model access. You can also use Ollama to deploy local models — all of these ultimately connect through OneAPI. Here are some third-party providers: + + + - [SiliconCloud](https://cloud.siliconflow.cn/i/TR9Ym0c4): A platform for open source model APIs. - + [Sealos AIProxy](https://hzh.sealos.run/?uid=fnWRt09fZP&openapp=system-aiproxy): + Proxies for various Chinese model providers — no need to apply for each API separately. + + +Once you've configured models in OneAPI, open the FastGPT page and enable the corresponding models. + +### 2. Configuration Overview + + + Note: 1. Only one speech recognition model can be active at a time, so you only need to configure one. 2. + The system requires at least one language model and one embedding model to function properly. + + +#### Core Configuration + +- Model ID: The value of the `model` field in the API request body. Must be globally unique. +- Custom Request URL/Key: If you need to bypass OneAPI, you can set a custom request URL and token. Generally not needed, but useful if OneAPI doesn't support certain models. + +#### Model Types + +1. Language Model - Text conversations; multimodal models support image recognition. +2. Embedding Model - Indexes text chunks for relevant text retrieval. +3. Rerank Model - Reorders retrieval results to optimize ranking. +4. Text-to-Speech - Converts text to audio. +5. Speech-to-Text - Converts audio to text. + +#### Enabling Models + +The system includes built-in models from mainstream providers. If you're unfamiliar with configuration, just click `Enable`. Make sure the `Model ID` matches the `Model` name in your OneAPI channel. + +| | | +| ------------------------------- | ------------------------------- | +| ![alt text](/imgs/image-91.png) | ![alt text](/imgs/image-92.png) | + +#### Modifying Model Configuration + +Click the gear icon on the right side of a model to configure it. Different model types have different configuration options. + +| | | +| ------------------------------- | ------------------------------- | +| ![alt text](/imgs/image-93.png) | ![alt text](/imgs/image-94.png) | + +## Adding Custom Models + +If the built-in models don't meet your needs, you can add custom models. If a custom model's `Model ID` matches a built-in model ID, it will be treated as a modification of the built-in model. + +| | | +| ------------------------------- | ------------------------------- | +| ![alt text](/imgs/image-96.png) | ![alt text](/imgs/image-97.png) | + +#### Configuration via Config File + +If you find UI-based model configuration tedious, or want to quickly copy configuration from one system to another, you can use config files instead. + +| | | +| ------------------------------- | ------------------------------- | +| ![alt text](/imgs/image-98.png) | ![alt text](/imgs/image-99.png) | + +**Language Model Field Descriptions:** + +```json +{ + "model": "Model ID", + "metadata": { + "isCustom": true, // Whether this is a custom model + "isActive": true, // Whether this model is enabled + "provider": "OpenAI", // Model provider, mainly for categorization display. Built-in providers: https://github.com/labring/FastGPT/blob/main/packages/global/core/ai/provider.ts. You can submit a PR for new providers, or use "Other" + "model": "gpt-5", // Model ID (matches the model name in OneAPI channel) + "name": "gpt-5", // Model display name + "maxContext": 125000, // Max context length + "maxResponse": 16000, // Max response length + "quoteMaxToken": 120000, // Max quote content tokens + "maxTemperature": 1.2, // Max temperature + "charsPointsPrice": 0, // n points/1k tokens (commercial version) + "censor": false, // Enable content moderation (commercial version) + "vision": true, // Supports image input + "datasetProcess": true, // Use as text understanding model (QA). At least one model must have this set to true, otherwise the 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, and tool calling) + "functionCall": false, // Supports function calling (used in classification, extraction, and tool calling). toolChoice takes priority; if false, falls back to functionCall; if still false, falls back to prompt mode + "customCQPrompt": "", // Custom classification prompt (for models without tool/function call 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) + "fieldMap": {} // Field mapping (e.g., o1 models need max_tokens mapped to max_completion_tokens) + } +} +``` + +**Embedding Model Field Descriptions:** + +```json +{ + "model": "Model ID", + "metadata": { + "isCustom": true, // Whether this is a custom model + "isActive": true, // Whether this model is enabled + "provider": "OpenAI", // Model provider + "model": "text-embedding-3-small", // Model ID + "name": "text-embedding-3-small", // Model display name + "charsPointsPrice": 0, // n points/1k tokens + "defaultToken": 512, // Default token count for text splitting + "maxToken": 3000 // Max tokens + } +} +``` + +**Rerank Model Field Descriptions:** + +```json +{ + "model": "Model ID", + "metadata": { + "isCustom": true, // Whether this is a custom model + "isActive": true, // Whether this model is enabled + "provider": "BAAI", // Model provider + "model": "bge-reranker-v2-m3", // Model ID + "name": "ReRanker-Base", // Model display name + "requestUrl": "", // Custom request URL + "requestAuth": "", // Custom request auth + "type": "rerank" // Model type + } +} +``` + +**Text-to-Speech Model Field Descriptions:** + +```json +{ + "model": "Model ID", + "metadata": { + "isActive": true, // Whether this model is enabled + "isCustom": true, // Whether this is a custom model + "type": "tts", // Model type + "provider": "FishAudio", // Model provider + "model": "fishaudio/fish-speech-1.5", // Model ID + "name": "fish-speech-1.5", // Model display name + "voices": [ + // Voice options + { + "label": "fish-alex", // Voice name + "value": "fishaudio/fish-speech-1.5:alex" // Voice ID + }, + { + "label": "fish-anna", // Voice name + "value": "fishaudio/fish-speech-1.5:anna" // Voice ID + } + ], + "charsPointsPrice": 0 // n points/1k tokens + } +} +``` + +**Speech-to-Text Model Field Descriptions:** + +```json +{ + "model": "whisper-1", + "metadata": { + "isActive": true, // Whether this model is enabled + "isCustom": true, // Whether this is a custom model + "provider": "OpenAI", // Model provider + "model": "whisper-1", // Model ID + "name": "whisper-1", // Model display name + "charsPointsPrice": 0, // n points/1k tokens + "type": "stt" // Model type + } +} +``` + +## Model Testing + +FastGPT provides simple tests for each model type on the UI. You can run a quick check to verify models are working correctly — it sends an actual request using a template. + +![alt text](/imgs/image-105.png) + +## Special Integration Examples + +### Integrating Rerank Models + +Since OneAPI doesn't support Rerank models, they need to be configured separately. FastGPT's model configuration supports custom request URLs, allowing you to bypass OneAPI and send requests directly to providers. You can use this feature to integrate Rerank models. + +#### Using SiliconCloud's Online Models + +A free `bge-reranker-v2-m3` model is available. + +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. Open FastGPT model configuration and add a `BAAI/bge-reranker-v2-m3` rerank model (or modify the built-in one if it already exists). + +![alt text](/imgs/image-101.png) + +#### Self-Hosted Rerank Models + +[View the ReRank model deployment tutorial](/docs/introduction/development/custom-models/bge-rerank/) + +### Integrating Speech Recognition Models + +OneAPI's speech recognition interface cannot correctly identify non-Whisper models (it always defaults to whisper-1). To integrate other models, use a custom request URL. For example, to integrate SiliconCloud's `FunAudioLLM/SenseVoiceSmall` model: + +Click model edit: + +![alt text](/imgs/image-106.png) + +Enter SiliconCloud's URL: `https://api.siliconflow.cn/v1/audio/transcriptions`, and enter your SiliconCloud API Key. + +![alt text](/imgs/image-107.png) + +## Other Configuration Options + +### Custom Request URL + +Setting this value allows you to bypass OneAPI and send requests directly to the custom URL. You need to provide the complete request URL, for example: + +- LLM: [host]/v1/chat/completions +- Embedding: [host]/v1/embeddings +- STT: [host]/v1/audio/transcriptions +- TTS: [host]/v1/audio/speech +- Rerank: [host]/v1/rerank + +The custom request key is sent as a request header: `Authorization: Bearer xxx`. + +All interfaces follow OpenAI's model format. See the [OpenAI API documentation](https://platform.openai.com/docs/api-reference/introduction) for details. + +Since OpenAI doesn't provide a ReRank model, the Cohere format is used instead. [View request examples](/docs/introduction/development/faq/#how-to-check-model-issues) + +### Model Pricing Configuration + +Commercial version users can configure model pricing for account billing. The system supports two billing modes: total token billing and separate input/output token billing. + +For **separate input/output token billing**, fill in both `Model Input Price` and `Model Output Price`. +For **total token billing**, fill in only `Model Combined Price`. + +## How to Submit Built-in Models + +Since models update frequently, the official team may not always keep up. If you can't find the built-in model you need, you can [submit an Issue](https://github.com/labring/FastGPT/issues) with the model name and official website, or directly [submit a PR](https://github.com/labring/FastGPT/pulls) with the model configuration. + +### Adding Model Providers + +To add a model provider, modify the following: + +1. FastGPT/packages/web/components/common/Icon/icons/model - Add the provider's SVG logo in this directory. +2. In the FastGPT root directory, run `pnpm initIcon` to load the icon into the config file. +3. FastGPT/packages/global/core/ai/provider.ts - Add the provider configuration in this file. + +### Adding Models + +In the `FastGPT-plugin` project, find the corresponding provider's config file under the `modules/model/provider` directory and add the model configuration. Make sure the `model` field is unique across all models. For field descriptions, see [Model Configuration Field Descriptions](/docs/introduction/development/modelconfig/intro/#configuration-via-config-file). + +## Legacy Model Configuration + +After configuring OneAPI, you need to manually add model configuration to the `config.json` file and restart. + +Since environment variables aren't ideal for complex configuration, FastGPT uses ConfigMap to mount config files. You can find the default config file at `projects/app/data/config.json`. See [docker-compose Quick Deployment](/docs/introduction/development/docker/) for how to mount config files. + +**In development**, copy the example config file `config.json` to `config.local.json` for it to take effect. +**In Docker deployment**, modifying `config.json` requires restarting the container. + +The example config file below includes system parameters and model configurations: + +```json +{ + "feConfigs": { + "lafEnv": "https://laf.dev" // Laf environment. https://laf.run (Hangzhou Alibaba Cloud), or a private Laf environment. Latest Laf version required for Laf OpenAPI features. + }, + "systemEnv": { + "vectorMaxProcess": 15, // Vector processing thread count + "qaMaxProcess": 15, // QA splitting thread count + "tokenWorkers": 50, // Token calculation worker count (persistent memory usage — don't set too high) + "hnswEfSearch": 100 // Vector search parameter (PG and OB only). Higher = more accurate but slower. 100 gives 99%+ accuracy. + }, + "llmModels": [ + { + "provider": "OpenAI", // Model provider, mainly for categorization display. Built-in providers: https://github.com/labring/FastGPT/blob/main/packages/global/core/ai/provider.ts. You can submit a PR for new providers, or use "Other" + "model": "gpt-5", // Model name (matches OneAPI channel model name) + "name": "gpt-5", // Model display name + "maxContext": 125000, // Max context + "maxResponse": 16000, // Max response + "quoteMaxToken": 120000, // Max quote content + "maxTemperature": 1.2, // Max temperature + "charsPointsPrice": 0, // n points/1k tokens (commercial version) + "censor": false, // Enable content moderation (commercial version) + "vision": true, // Supports image input + "datasetProcess": true, // Use as text understanding model (QA) — at least one 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, falls back to prompt mode + "customCQPrompt": "", // Custom classification prompt (for models without tool/function call 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) + "fieldMap": {} // Field mapping (e.g., o1 models need max_tokens mapped to max_completion_tokens) + }, + { + "provider": "OpenAI", + "model": "gpt-4o", + "name": "gpt-4o", + "maxContext": 125000, + "maxResponse": 4000, + "quoteMaxToken": 120000, + "maxTemperature": 1.2, + "charsPointsPrice": 0, + "censor": false, + "vision": true, + "datasetProcess": true, + "usedInClassify": true, + "usedInExtractFields": true, + "usedInToolCall": true, + "toolChoice": true, + "functionCall": false, + "customCQPrompt": "", + "customExtractPrompt": "", + "defaultSystemChatPrompt": "", + "defaultConfig": {}, + "fieldMap": {} + }, + { + "provider": "OpenAI", + "model": "o1-mini", + "name": "o1-mini", + "maxContext": 125000, + "maxResponse": 65000, + "quoteMaxToken": 120000, + "maxTemperature": 1.2, + "charsPointsPrice": 0, + "censor": false, + "vision": false, + "datasetProcess": true, + "usedInClassify": true, + "usedInExtractFields": true, + "usedInToolCall": true, + "toolChoice": false, + "functionCall": false, + "customCQPrompt": "", + "customExtractPrompt": "", + "defaultSystemChatPrompt": "", + "defaultConfig": { + "temperature": 1, + "max_tokens": null, + "stream": false + } + }, + { + "provider": "OpenAI", + "model": "o1-preview", + "name": "o1-preview", + "maxContext": 125000, + "maxResponse": 32000, + "quoteMaxToken": 120000, + "maxTemperature": 1.2, + "charsPointsPrice": 0, + "censor": false, + "vision": false, + "datasetProcess": true, + "usedInClassify": true, + "usedInExtractFields": true, + "usedInToolCall": true, + "toolChoice": false, + "functionCall": false, + "customCQPrompt": "", + "customExtractPrompt": "", + "defaultSystemChatPrompt": "", + "defaultConfig": { + "temperature": 1, + "max_tokens": null, + "stream": false + } + } + ], + "vectorModels": [ + { + "provider": "OpenAI", + "model": "text-embedding-3-small", + "name": "text-embedding-3-small", + "charsPointsPrice": 0, + "defaultToken": 512, + "maxToken": 3000, + "weight": 100 + }, + { + "provider": "OpenAI", + "model": "text-embedding-3-large", + "name": "text-embedding-3-large", + "charsPointsPrice": 0, + "defaultToken": 512, + "maxToken": 3000, + "weight": 100, + "defaultConfig": { + "dimensions": 1024 + } + }, + { + "provider": "OpenAI", + "model": "text-embedding-ada-002", // Model name (matches OneAPI) + "name": "Embedding-2", // Model display name + "charsPointsPrice": 0, // n points/1k tokens + "defaultToken": 700, // Default token count for text splitting + "maxToken": 3000, // Max tokens + "weight": 100, // Training priority weight + "defaultConfig": {}, // Custom extra parameters. For example, to use embedding3-large, pass dimensions:1024 to return 1024-dimensional vectors (currently must be less than 1536 dimensions) + "dbConfig": {}, // Extra parameters for storage (needed for asymmetric vector models) + "queryConfig": {} // Extra parameters for querying + } + ], + "reRankModels": [], + "audioSpeechModels": [ + { + "provider": "OpenAI", + "model": "tts-1", + "name": "OpenAI TTS1", + "charsPointsPrice": 0, + "voices": [ + { "label": "Alloy", "value": "alloy", "bufferId": "openai-Alloy" }, + { "label": "Echo", "value": "echo", "bufferId": "openai-Echo" }, + { "label": "Fable", "value": "fable", "bufferId": "openai-Fable" }, + { "label": "Onyx", "value": "onyx", "bufferId": "openai-Onyx" }, + { "label": "Nova", "value": "nova", "bufferId": "openai-Nova" }, + { "label": "Shimmer", "value": "shimmer", "bufferId": "openai-Shimmer" } + ] + } + ], + "whisperModel": { + "provider": "OpenAI", + "model": "whisper-1", + "name": "Whisper1", + "charsPointsPrice": 0 + } +} +``` diff --git a/document/content/docs/introduction/development/modelConfig/meta.en.json b/document/content/docs/introduction/development/modelConfig/meta.en.json new file mode 100644 index 0000000000..61a466af72 --- /dev/null +++ b/document/content/docs/introduction/development/modelConfig/meta.en.json @@ -0,0 +1,10 @@ +{ + "title": "Model Configuration Solutions", + "pages": [ + "ai-proxy", + "intro", + "one-api", + "siliconCloud", + "ppio" + ] +} diff --git a/document/content/docs/introduction/development/modelConfig/one-api.en.mdx b/document/content/docs/introduction/development/modelConfig/one-api.en.mdx new file mode 100644 index 0000000000..e1dac24cf3 --- /dev/null +++ b/document/content/docs/introduction/development/modelConfig/one-api.en.mdx @@ -0,0 +1,124 @@ +--- +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) | diff --git a/document/content/docs/introduction/development/modelConfig/ppio.en.mdx b/document/content/docs/introduction/development/modelConfig/ppio.en.mdx new file mode 100644 index 0000000000..228b59127a --- /dev/null +++ b/document/content/docs/introduction/development/modelConfig/ppio.en.mdx @@ -0,0 +1,139 @@ +--- +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. + + + 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. + + +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. + +Create API Key + +(3) Generate and save the API Key + + + 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. + + +Generate API Key +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 + + + Please use version v4.8.22 or above. Deployment reference: [Deploy FastGPT](/docs/introduction/development/intro/) + + +## 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: + +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. + Test Connectivity + +(2) Connect PPIO models without OneAPI + +Select PPIO Cloud in the model providers as shown below: + +Select PPIO Cloud + +- Configure the model: Enter `https://api.ppinfra.com/v3/openai/chat/completions` in the custom request URL field. + + Configure Model + Configure Model + +- Test connectivity + 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 + +Create Workspace +(2) Start chatting +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! diff --git a/document/content/docs/introduction/development/modelConfig/siliconCloud.en.mdx b/document/content/docs/introduction/development/modelConfig/siliconCloud.en.mdx new file mode 100644 index 0000000000..37f4709579 --- /dev/null +++ b/document/content/docs/introduction/development/modelConfig/siliconCloud.en.mdx @@ -0,0 +1,89 @@ +--- +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. diff --git a/document/content/docs/introduction/development/object-storage.en.mdx b/document/content/docs/introduction/development/object-storage.en.mdx new file mode 100644 index 0000000000..1290791205 --- /dev/null +++ b/document/content/docs/introduction/development/object-storage.en.mdx @@ -0,0 +1,98 @@ +--- +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= +``` diff --git a/document/content/docs/introduction/development/proxy/cloudflare.en.mdx b/document/content/docs/introduction/development/proxy/cloudflare.en.mdx new file mode 100644 index 0000000000..ee0ca6c045 --- /dev/null +++ b/document/content/docs/introduction/development/proxy/cloudflare.en.mdx @@ -0,0 +1,50 @@ +--- +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 +``` diff --git a/document/content/docs/introduction/development/proxy/http_proxy.en.mdx b/document/content/docs/introduction/development/proxy/http_proxy.en.mdx new file mode 100644 index 0000000000..29fa2b5ec4 --- /dev/null +++ b/document/content/docs/introduction/development/proxy/http_proxy.en.mdx @@ -0,0 +1,42 @@ +--- +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 +``` diff --git a/document/content/docs/introduction/development/proxy/meta.en.json b/document/content/docs/introduction/development/proxy/meta.en.json new file mode 100644 index 0000000000..200bdc9d85 --- /dev/null +++ b/document/content/docs/introduction/development/proxy/meta.en.json @@ -0,0 +1,9 @@ +{ + "title": "Proxy Solutions", + "description": "FastGPT private deployment proxy solutions", + "pages": [ + "nginx", + "http_proxy", + "cloudflare" + ] +} diff --git a/document/content/docs/introduction/development/proxy/nginx.en.mdx b/document/content/docs/introduction/development/proxy/nginx.en.mdx new file mode 100644 index 0000000000..58ac028b0e --- /dev/null +++ b/document/content/docs/introduction/development/proxy/nginx.en.mdx @@ -0,0 +1,101 @@ +--- +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!** diff --git a/document/content/docs/introduction/development/sealos.en.mdx b/document/content/docs/introduction/development/sealos.en.mdx new file mode 100644 index 0000000000..1e77a5ea4a --- /dev/null +++ b/document/content/docs/introduction/development/sealos.en.mdx @@ -0,0 +1,187 @@ +--- +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 👇 + + + Deploy on Sealos + + +### 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 👇 + + + Deploy on Sealos + + +### 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) + + + 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.) + + +### 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/) diff --git a/document/content/docs/introduction/development/signoz.en.mdx b/document/content/docs/introduction/development/signoz.en.mdx new file mode 100644 index 0000000000..a2f057d39d --- /dev/null +++ b/document/content/docs/introduction/development/signoz.en.mdx @@ -0,0 +1,81 @@ +--- +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) diff --git a/document/content/docs/introduction/guide/DialogBoxes/htmlRendering.en.mdx b/document/content/docs/introduction/guide/DialogBoxes/htmlRendering.en.mdx new file mode 100644 index 0000000000..b4c9c6d9d8 --- /dev/null +++ b/document/content/docs/introduction/guide/DialogBoxes/htmlRendering.en.mdx @@ -0,0 +1,52 @@ +--- +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 + + + + + + + Welcome to FastGPT + + + + + +``` +``` diff --git a/document/content/docs/introduction/guide/DialogBoxes/meta.en.json b/document/content/docs/introduction/guide/DialogBoxes/meta.en.json new file mode 100644 index 0000000000..2059318b19 --- /dev/null +++ b/document/content/docs/introduction/guide/DialogBoxes/meta.en.json @@ -0,0 +1,8 @@ +{ + "title": "Dialog Boxes", + "description": "Dialog box components that support multiple interaction methods to enhance user experience in applications.", + "pages": [ + "htmlRendering", + "quoteList" + ] +} diff --git a/document/content/docs/introduction/guide/DialogBoxes/quoteList.en.mdx b/document/content/docs/introduction/guide/DialogBoxes/quoteList.en.mdx new file mode 100644 index 0000000000..d4c7a3155a --- /dev/null +++ b/document/content/docs/introduction/guide/DialogBoxes/quoteList.en.mdx @@ -0,0 +1,82 @@ +--- +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. diff --git a/document/content/docs/introduction/guide/admin/meta.en.json b/document/content/docs/introduction/guide/admin/meta.en.json new file mode 100644 index 0000000000..4a43c9a140 --- /dev/null +++ b/document/content/docs/introduction/guide/admin/meta.en.json @@ -0,0 +1,8 @@ +{ + "title": "Commercial Admin", + "description": "Commercial admin usage tutorial", + "pages": [ + "sso", + "teamMode" + ] +} diff --git a/document/content/docs/introduction/guide/admin/sso.en.mdx b/document/content/docs/introduction/guide/admin/sso.en.mdx new file mode 100644 index 0000000000..93f380519b --- /dev/null +++ b/document/content/docs/introduction/guide/admin/sso.en.mdx @@ -0,0 +1,643 @@ +--- +title: SSO & External Member Sync +description: FastGPT External Member System Integration and Configuration +--- + +import { Alert } from '@/components/docs/Alert'; + +If you don't need SSO or member sync, or only need quick login via GitHub, Google, Microsoft, or WeChat Official Account, you can skip this section. This guide is for users who need to integrate their own member systems or mainstream office IMs. + +## Overview + +To simplify integration with **external member systems**, FastGPT provides a set of **standard interfaces** for connecting to external systems, along with a FastGPT-SSO-Service image that serves as an **adapter**. + +Through these standard interfaces, you can: + +1. SSO login. After a callback from an external system, create a user in FastGPT. +2. Member and organizational structure sync (referred to as "member sync" below). + +**How It Works** + +FastGPT-pro includes a standard set of SSO and member sync interfaces. The system performs SSO and member sync operations based on these interfaces. + +FastGPT-SSO-Service aggregates SSO and member sync interfaces from different sources and converts them into the format recognized by fastgpt-pro. + + ![](/imgs/sso2.png) + +## System Configuration Tutorial + +### 1. Deploy the SSO-Service Image + +Deploy using docker-compose: + +```yaml + fastgpt-sso: + image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:v4.9.0 # This version must match the FastGPT image version + container_name: fastgpt-sso + restart: always + networks: + - fastgpt + environment: + - SSO_PROVIDER=example + - AUTH_TOKEN=xxxxx # Auth token, used by fastgpt-pro + # Provider-specific environment variables below +``` + +Depending on the provider, you'll need different environment variables. Below are the built-in protocols/IMs: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Protocol/FeatureSSOMember Sync Support
LarkYesYes
WeComYesYes
DingTalkYesNo
SAML 2.0YesNo
OAuth 2.0YesNo
+ +### 2. Configure fastgpt-pro + +#### 1. Configure Environment Variables + +The `EXTERNAL_USER_SYSTEM_BASE_URL` environment variable should be set to the internal network address. For example, with the configuration above: + +```yaml +env: + - EXTERNAL_USER_SYSTEM_BASE_URL=http://fastgpt-sso:3000 + - EXTERNAL_USER_SYSTEM_AUTH_TOKEN=xxxxx +``` + +#### 2. Configure button text, icons, etc. in the commercial version admin panel. + + + + + + + + + + + + + + + + +
WeComDingTalkLark
![WeCom](/imgs/sso15.png)![DingTalk](/imgs/sso16.png)![Lark](/imgs/sso17.png)
+ +#### 3. Enable Member Sync (Optional) + +If you need to sync members from an external system, you can enable member sync. For team mode details, see: [Team Mode Documentation](/docs/introduction/guide/admin/teamMode) + +![](/imgs/sso1.png) + +#### 4. Optional Configuration + +1. Automatic scheduled member sync + +Set the fastgpt-pro environment variable to enable automatic member sync: + +```yaml +env: + - "SYNC_MEMBER_CRON=0 0 * * *" # Cron expression, runs daily at 00:00. Note: uses UTC (timezone 0). For example, to sync at 12:00 Beijing time, set this to "0 4 * * *" (UTC 04:00) +``` + +## Built-in Protocol/IM Configuration Examples + +### Lark + +#### 1. Get Parameters + + App ID and App Secret + + Go to the developer console, click on your enterprise self-built app, and view the app credentials on the Credentials & Basic Info page. + + ![](/imgs/sso3.png) + +#### 2. Permission Configuration + + Go to the developer console, click on your enterprise self-built app, and enable permissions on the Permission Management page under Development Configuration. + + ![](/imgs/sso4.png) + + You can use the **Batch Import/Export Permissions** feature to import the following permission configuration: + +```json +{ + "scopes": { + "tenant": [ + "contact:user.phone:readonly", + "contact:contact.base:readonly", + "contact:department.base:readonly", + "contact:department.organize:readonly", + "contact:user.base:readonly", + "contact:user.department:readonly", + "contact:user.email:readonly", + "contact:user.employee_id:readonly" + ], + "user": [] + } +} +``` + +Note: The accessible data scope must be set to visible to all members. + +#### 3. Redirect URL + + Go to the developer console, click on your enterprise self-built app, and set the redirect URL in Security Settings under Development Configuration. + The redirect URL should follow the format `https://www.fastgpt.cn/login/provider` — replace the domain with your publicly accessible FastGPT domain. + ![](/imgs/sso5.png) + +#### 4. yml Configuration Example + +```yaml +fastgpt-sso: + image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:v4.9.0 + container_name: fastgpt-sso + restart: always + networks: + - fastgpt + environment: + - SSO_PROVIDER=feishu + - AUTH_TOKEN=xxxxx + # OAuth endpoint (for private Lark deployments, replace with your private address; same below) + - SSO_TARGET_URL=https://accounts.feishu.cn/open-apis/authen/v1/authorize + # Token endpoint + - FEISHU_TOKEN_URL=https://open.feishu.cn/open-apis/authen/v2/oauth/token + # User info endpoint + - FEISHU_GET_USER_INFO_URL=https://open.feishu.cn/open-apis/authen/v1/user_info + # Redirect address — must match the URL from step 3 exactly + - FEISHU_REDIRECT_URI=https://fastgpt.cn/login/provider + # Lark App ID, usually starts with cli + - FEISHU_APP_ID=xxx + # Lark App Secret + - FEISHU_APP_SECRET=xxx +``` + +### DingTalk + +#### 1. Get Parameters + + CLIENT_ID and CLIENT_SECRET + + Go to the DingTalk Open Platform, click App Development, select your app, and record the Client ID and Client Secret on the Credentials & Basic Info page. + ![](/imgs/sso6.png) + +#### 2. Permission Configuration + + Go to the DingTalk Open Platform, click App Development, select your app, and manage permissions on the Permission Management page under Development Configuration. Required permissions: + + 1. ***Personal phone number information*** + 2. ***Contact personal information read permission*** + 3. ***Basic permission to obtain DingTalk open interface user access credentials*** + +#### 3. Redirect URL + + Go to the DingTalk Open Platform, click App Development, select your app, and configure on the Security Settings page under Development Configuration. + Two items need to be filled in: + + 1. Server egress IP (list of server IPs calling DingTalk server-side APIs) + 2. Redirect URL (callback domain) + +#### 4. yml Configuration Example + +```yaml +fastgpt-sso: + image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:v4.9.0 + container_name: fastgpt-sso + restart: always + networks: + - fastgpt + environment: + - SSO_PROVIDER=dingtalk + - AUTH_TOKEN=xxxxx + # OAuth endpoint + - SSO_TARGET_URL=https://login.dingtalk.com/oauth2/auth + # Token endpoint + - DINGTALK_TOKEN_URL=https://api.dingtalk.com/v1.0/oauth2/userAccessToken + # User info endpoint + - DINGTALK_GET_USER_INFO_URL=https://oapi.dingtalk.com/v1.0/contact/users/me + # DingTalk App ID + - DINGTALK_CLIENT_ID=xxx + # DingTalk App Secret + - DINGTALK_CLIENT_SECRET=xxx +``` + +### WeCom + +#### 1. Get Parameters + + 1. Enterprise CorpID + + a. Log in to the WeCom admin console with an admin account: `https://work.weixin.qq.com/wework_admin/loginpage_wx` + + b. Go to the "My Enterprise" page and find the Enterprise ID + + ![](/imgs/sso7.png) + + 2. Create an internal app for FastGPT: + + a. Get the app's AgentID and Secret + + b. Ensure the app's visibility scope is set to all (i.e., root department) + + ![](/imgs/sso8.png) + + + ![](/imgs/sso9.png) + + 3. A domain name with the following requirements: + + a. Resolves to a publicly accessible server + + b. Can serve static files at the root path (for domain ownership verification — follow the prompts, you only need to host one static file, which can be removed after verification) + + c. Configure web authorization, JS-SDK, and WeCom authorization login + + d. You can set "Hide app in workbench" at the bottom of the WeCom Authorization Login page + + ![](/imgs/sso10.png) + + ![](/imgs/sso11.png) + + ![](/imgs/sso12.png) + + 4. Get the "Contact Sync Assistant" secret + + Retrieving contacts and organization member IDs requires the "Contact Sync Assistant" secret + + Security & Management -- Management Tools -- Contact Sync + + ![](/imgs/sso13.png) + + 5. Enable interface sync + + 6. Get the Secret + + 7. Configure enterprise trusted IPs + + ![](/imgs/sso14.png) + +#### 2. yml Configuration Example + +```yaml +fastgpt-sso: + image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:v4.9.0 + container_name: fastgpt-sso + restart: always + networks: + - fastgpt + environment: + - AUTH_TOKEN=xxxxx + - SSO_PROVIDER=wecom + # OAuth endpoint, used in WeCom client + - WECOM_TARGET_URL_OAUTH=https://open.weixin.qq.com/connect/oauth2/authorize + # SSO endpoint, QR code scan + - WECOM_TARGET_URL_SSO=https://login.work.weixin.qq.com/wwlogin/sso/login + # Get user ID (returns ID only) + - WECOM_GET_USER_ID_URL=https://qyapi.weixin.qq.com/cgi-bin/auth/getuserinfo + # Get detailed user info (everything except name) + - WECOM_GET_USER_INFO_URL=https://qyapi.weixin.qq.com/cgi-bin/auth/getuserdetail + # Get user info (has name, no other info) + - WECOM_GET_USER_NAME_URL=https://qyapi.weixin.qq.com/cgi-bin/user/get + # Get department ID list + - WECOM_GET_DEPARTMENT_LIST_URL=https://qyapi.weixin.qq.com/cgi-bin/department/list + # Get user ID list + - WECOM_GET_USER_LIST_URL=https://qyapi.weixin.qq.com/cgi-bin/user/list_id + # WeCom CorpId + - WECOM_CORPID= + # WeCom App AgentId, usually 1000xxx + - WECOM_AGENTID= + # WeCom App Secret + - WECOM_APP_SECRET= + # Contact Sync Assistant Secret + - WECOM_SYNC_SECRET= +``` + +### Standard OAuth 2.0 + +We provide OAuth 2.0 integration support using the authorization code grant from RFC 6749. +References: +- [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) documentation +- [Ruan Yifeng's blog post on OAuth 2.0](https://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html) + +#### Parameter Requirements + +##### Three Endpoints +We provide a standard OAuth 2.0 integration flow requiring three endpoints: + +1. Login authorization endpoint (users are redirected here with parameters after clicking the SSO button), e.g., `http://example.com/oauth/authorize` + ```bash + curl -X GET\ + "http://example.com/oauth/authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Ffastgpt.cn%2Flogin%2Fprovider" + ``` + After entering credentials, users are redirected to redirect_uri with a code parameter: + `https://fastgpt.cn/login/provider?code=4/P7qD2qAz4&state=xyz` +2. Access token endpoint. After obtaining the code, make a *server-side request* to this endpoint to get the access_token, e.g., `http://example.com/oauth/access_token` + ```bash + curl -X POST\ + -H "Content-Type: application/x-www-form-urlencoded"\ + "http://example.com/oauth/access_token?grant_type=authorization_code&client_id=s6BhdRkqt3&client_secret=xxx&code=4/P7qD2qAz4&redirect_uri=https%3A%2F%2Ffastgpt.cn%2Flogin%2Fprovider" + ``` + Note: Content-Type must be application/x-www-form-urlencoded, not application/json +3. User info endpoint, requires passing the access_token, e.g., `http://example.com/oauth/user_info` + ```bash + curl -X GET\ + -H "Authorization: Bearer 4/P7qD2qAz4"\ + "http://example.com/oauth/user_info" + ``` + Note: access_token is passed as the Authorization header in the format: Bearer xxxx + +##### Parameter Configuration +- CLIENT_ID: Required +- CLIENT_SECRET: Optional, skip if not needed +- SCOPE: Optional, skip if not needed + +> The redirect_uri parameter is auto-populated based on the runtime environment +> +> Other fixed parameters like grant_type and response_type are auto-populated + +#### Configuration Example + +```yaml +fastgpt-sso: + image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:v4.9.0 + container_name: fastgpt-sso + restart: always + networks: + - fastgpt + environment: + - SSO_PROVIDER=oauth2 + - AUTH_TOKEN=xxxxx + # OAuth2.0 + # === Request URLs === + # 1. OAuth2 login authorization URL (required) + - OAUTH2_AUTHORIZE_URL= + # 2. OAuth2 access token URL (required) + - OAUTH2_TOKEN_URL= + # 3. OAuth2 user info URL (required) + - OAUTH2_USER_INFO_URL= + # === Parameters === + # 1. client_id (required) + - OAUTH2_CLIENT_ID= + # 2. client_secret (optional) + - OAUTH2_CLIENT_SECRET= + # 3. scope (optional) + - OAUTH2_SCOPE= + # === Field Mapping === + # OAuth2 username field mapping (required) + - OAUTH2_USERNAME_MAP= + # OAuth2 avatar field mapping (optional) + - OAUTH2_AVATAR_MAP= + # OAuth2 member name field mapping (optional) + - OAUTH2_MEMBER_NAME_MAP= + # OAuth2 contact field mapping (optional) + - OAUTH2_CONTACT_MAP= +``` + +## Standard Interface Documentation + +Below is the standard interface documentation for SSO and member sync in FastGPT-pro. If you need to integrate with a non-standard system, refer to this section for development. + +![](/imgs/sso18.png) + +FastGPT provides the following standard interfaces: + +1. https://example.com/login/oauth/getAuthURL - Get the authorization redirect URL +2. https://example.com/login/oauth/getUserInfo?code=xxxxx - Consume the code and exchange it for user info +3. https://example.com/org/list - Get the organization list +4. https://example.com/user/list - Get the member list + +### Get SSO Login Redirect URL + +Returns a redirect login URL. FastGPT will automatically redirect to this URL. The redirect_uri is automatically appended to the URL query string. + + + + +```bash +curl -X GET "https://redict.example/login/oauth/getAuthURL?redirect_uri=xxx&state=xxxx" \ +-H "Authorization: Bearer your_token_here" \ +-H "Content-Type: application/json" +``` + + + + +Success: + +```json +{ + "success": true, + "message": "", + "authURL": "https://example.com/somepath/login/oauth?redirect_uri=https%3A%2F%2Ffastgpt.cn%2Flogin%2Fprovider%0A" +} +``` + +Failure: + +```json +{ + "success": false, + "message": "Error message", + "authURL": "" +} +``` + + + + + +### SSO Get User Info + +This interface accepts a code parameter for authentication, consumes the code, and returns user info. + + + + +```bash +curl -X GET "https://oauth.example/login/oauth/getUserInfo?code=xxxxxx" \ +-H "Authorization: Bearer your_token_here" \ +-H "Content-Type: application/json" +``` + + + + + +Success: +```json +{ + "success": true, + "message": "", + "username": "fastgpt-123456789", + "avatar": "https://example.webp", + "contact": "+861234567890", + "memberName": "Member name (optional)", +} +``` + +Failure: +```json +{ + "success": false, + "message": "Error message", + "username": "", + "avatar": "", + "contact": "" +} +``` + + + + +### Get Organizations + + + + +```bash +curl -X GET "https://example.com/org/list" \ +-H "Authorization: Bearer your_token_here" \ +-H "Content-Type: application/json" +``` + + + + + +Warning: Only one root department can exist. If your system has multiple root departments, you need to add a virtual root department first. Return type: + +```ts +type OrgListResponseType = { + message?: string; // Error message + success: boolean; + orgList: { + id: string; // Unique department ID + name: string; // Name + parentId: string; // parentId — empty string for root department + }[]; +} +``` + +```json +{ + "success": true, + "message": "", + "orgList": [ + { + "id": "od-125151515", + "name": "Root Department", + "parentId": "" + }, + { + "id": "od-51516152", + "name": "Sub Department", + "parentId": "od-125151515" + } + ] +} +``` + + + + + +### Get Members + + + + + +```bash +curl -X GET "https://example.com/user/list" \ +-H "Authorization: Bearer your_token_here" \ +-H "Content-Type: application/json" +``` + + + + + +Return type: + +```typescript +type UserListResponseListType = { + message?: string; // Error message + success: boolean; + userList: { + username: string; // Unique ID. username must match the username returned by the SSO interface. Must include a prefix, e.g., sync-aaaaa, consistent with the SSO interface prefix + memberName?: string; // Name, used as tmbname + avatar?: string; + contact?: string; // email or phone number + orgs?: string[]; // IDs of organizations the member belongs to. Pass [] if no organization + }[]; +} +``` +curl example + +```json +{ + "success": true, + "message": "", + "userList": [ + { + "username": "fastgpt-123456789", + "memberName": "John Doe", + "avatar": "https://example.webp", + "contact": "+861234567890", + "orgs": ["od-125151515", "od-51516152"] + }, + { + "username": "fastgpt-12345678999", + "memberName": "Jane Smith", + "avatar": "", + "contact": "", + "orgs": ["od-125151515"] + } + ] + +} +``` + + + + + + + +## How to Integrate Non-Standard Systems + +1. Self-development: Build according to the standard interfaces provided by FastGPT, then enter the deployed service address into fastgpt-pro. + You can use this template repository as a starting point: [fastgpt-sso-template](https://github.com/labring/fastgpt-sso-template) +2. Custom development by the FastGPT team: + a. Provide the system's SSO documentation, member and organization retrieval documentation, and an external test address. + b. In fastgpt-sso-service, add the corresponding provider and environment variables, and write the integration code. diff --git a/document/content/docs/introduction/guide/admin/teamMode.en.mdx b/document/content/docs/introduction/guide/admin/teamMode.en.mdx new file mode 100644 index 0000000000..6ef086d503 --- /dev/null +++ b/document/content/docs/introduction/guide/admin/teamMode.en.mdx @@ -0,0 +1,81 @@ +--- +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) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Team ModeSMS/Email RegistrationAdmin Direct AddSSO Registration
Creates Default TeamJoins Root TeamCreates Default TeamJoins Root TeamCreates Default TeamJoins Root Team
Single-team Mode❌✅❌✅❌✅
Multi-team Mode✅❌✅❌✅❌
Sync Mode❌❌❌❌❌✅
+ +### 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) diff --git a/document/content/docs/introduction/guide/course/ai_settings.en.mdx b/document/content/docs/introduction/guide/course/ai_settings.en.mdx new file mode 100644 index 0000000000..c007358e1f --- /dev/null +++ b/document/content/docs/introduction/guide/course/ai_settings.en.mdx @@ -0,0 +1,164 @@ +--- +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) +] +``` + + +Tip: Click the context button to view the full context composition for easier debugging. + + +### 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. + + +Tip: For best results, use only one data type per Knowledge Base for each scenario to maximize prompt effectiveness. + + +| 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. diff --git a/document/content/docs/introduction/guide/course/chat_input_guide.en.mdx b/document/content/docs/introduction/guide/course/chat_input_guide.en.mdx new file mode 100644 index 0000000000..6ec362cd73 --- /dev/null +++ b/document/content/docs/introduction/guide/course/chat_input_guide.en.mdx @@ -0,0 +1,50 @@ +--- +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 diff --git a/document/content/docs/introduction/guide/course/fileInput.en.mdx b/document/content/docs/introduction/guide/course/fileInput.en.mdx new file mode 100644 index 0000000000..9e1b7b2120 --- /dev/null +++ b/document/content/docs/introduction/guide/course/fileInput.en.mdx @@ -0,0 +1,109 @@ +--- +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` 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} + +``` + +### 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` input. The URLs are parsed and injected into a system message using this prompt template: + +``` +Use the content in as reference for this conversation: + +{{quote}} + +``` + +# 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.** diff --git a/document/content/docs/introduction/guide/course/meta.en.json b/document/content/docs/introduction/guide/course/meta.en.json new file mode 100644 index 0000000000..6e799b0743 --- /dev/null +++ b/document/content/docs/introduction/guide/course/meta.en.json @@ -0,0 +1,10 @@ +{ + "title": "Basic Tutorial", + "description": "FastGPT basic tutorial", + "pages": [ + "quick-start", + "ai_settings", + "chat_input_guide", + "fileInput" + ] +} diff --git a/document/content/docs/introduction/guide/course/quick-start.en.mdx b/document/content/docs/introduction/guide/course/quick-start.en.mdx new file mode 100644 index 0000000000..4414258900 --- /dev/null +++ b/document/content/docs/introduction/guide/course/quick-start.en.mdx @@ -0,0 +1,50 @@ +--- +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) diff --git a/document/content/docs/introduction/guide/dashboard/basic-mode.en.mdx b/document/content/docs/introduction/guide/dashboard/basic-mode.en.mdx new file mode 100644 index 0000000000..59489ca7bc --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/basic-mode.en.mdx @@ -0,0 +1,5 @@ +--- +title: Basic Mode +description: A quick overview of FastGPT Dashboard's Basic Mode +--- + diff --git a/document/content/docs/introduction/guide/dashboard/evaluation.en.mdx b/document/content/docs/introduction/guide/dashboard/evaluation.en.mdx new file mode 100644 index 0000000000..a548c9f446 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/evaluation.en.mdx @@ -0,0 +1,74 @@ +--- +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 diff --git a/document/content/docs/introduction/guide/dashboard/gapier.en.mdx b/document/content/docs/introduction/guide/dashboard/gapier.en.mdx new file mode 100644 index 0000000000..dcd550639e --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/gapier.en.mdx @@ -0,0 +1,56 @@ +--- +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
![](/imgs/gapierTool3.png) | +| Step4 | Step5 | Step6 | +| Custom request header: Authorization
Value: Bearer your_copied_key
![](/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) diff --git a/document/content/docs/introduction/guide/dashboard/intro.en.mdx b/document/content/docs/introduction/guide/dashboard/intro.en.mdx new file mode 100644 index 0000000000..5e2590db0f --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/intro.en.mdx @@ -0,0 +1,89 @@ +--- +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. + + diff --git a/document/content/docs/introduction/guide/dashboard/mcp_server.en.mdx b/document/content/docs/introduction/guide/dashboard/mcp_server.en.mdx new file mode 100644 index 0000000000..1cd17d7f86 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/mcp_server.en.mdx @@ -0,0 +1,101 @@ +--- +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": ""` (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. diff --git a/document/content/docs/introduction/guide/dashboard/mcp_tools.en.mdx b/document/content/docs/introduction/guide/dashboard/mcp_tools.en.mdx new file mode 100644 index 0000000000..2cc70fc400 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/mcp_tools.en.mdx @@ -0,0 +1,51 @@ +--- +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. diff --git a/document/content/docs/introduction/guide/dashboard/meta.en.json b/document/content/docs/introduction/guide/dashboard/meta.en.json new file mode 100644 index 0000000000..8901076219 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/meta.en.json @@ -0,0 +1,13 @@ +{ + "title": "Dashboard", + "description": "FastGPT dashboard and workflow node usage guide", + "pages": [ + "basic-mode", + "intro", + "workflow", + "mcp_server", + "mcp_tools", + "gapier", + "evaluation" + ] +} diff --git a/document/content/docs/introduction/guide/dashboard/workflow/ai_chat.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/ai_chat.en.mdx new file mode 100644 index 0000000000..26ac4492b2 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/ai_chat.en.mdx @@ -0,0 +1,30 @@ +--- +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) + + + For detailed parameter descriptions, see: [AI Parameter Configuration](/docs/introduction/guide/course/ai_settings/) + diff --git a/document/content/docs/introduction/guide/dashboard/workflow/content_extract.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/content_extract.en.mdx new file mode 100644 index 0000000000..d186579fc2 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/content_extract.en.mdx @@ -0,0 +1,53 @@ +--- +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. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/coreferenceResolution.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/coreferenceResolution.en.mdx new file mode 100644 index 0000000000..67956827d7 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/coreferenceResolution.en.mdx @@ -0,0 +1,34 @@ +--- +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/) diff --git a/document/content/docs/introduction/guide/dashboard/workflow/custom_feedback.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/custom_feedback.en.mdx new file mode 100644 index 0000000000..41f5d014fb --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/custom_feedback.en.mdx @@ -0,0 +1,31 @@ +--- +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. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/dataset_search.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/dataset_search.en.mdx new file mode 100644 index 0000000000..ea5f887d83 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/dataset_search.en.mdx @@ -0,0 +1,30 @@ +--- +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. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/document_parsing.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/document_parsing.en.mdx new file mode 100644 index 0000000000..b033746af6 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/document_parsing.en.mdx @@ -0,0 +1,14 @@ +--- +title: Document Parsing +description: FastGPT Document Parsing node overview +--- + +| | | +| --- | --- | +| ![](/imgs/document_analysis1.png) | ![](/imgs/document_analysis2.png) | + +The Document Parsing component becomes available after enabling file upload. + +## Features + +## Use Cases diff --git a/document/content/docs/introduction/guide/dashboard/workflow/form_input.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/form_input.en.mdx new file mode 100644 index 0000000000..8ed662c5fc --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/form_input.en.mdx @@ -0,0 +1,28 @@ +--- +title: Form Input +description: FastGPT Form Input node overview +--- + +## Characteristics + +- User interaction +- Can be added multiple times +- Trigger-based execution + +![](/imgs/form_input1.png) + +## What It Does + +The Form Input node is a user interaction node. When triggered, the conversation enters an "interactive" state -- the workflow state is saved and execution pauses until the user completes the interaction. + +![](/imgs/form_input2.png) + +In the example above, when the Form Input node is triggered, the chat box is hidden and the conversation enters interactive mode. + +![](/imgs/form_input3.png) + +After the user fills in the required fields and clicks submit, the node collects the form data and passes it to subsequent nodes. + +## Use Cases + +Precisely collect specific user information, then perform follow-up operations based on that data. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/http.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/http.en.mdx new file mode 100644 index 0000000000..d4b5f4b4ee --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/http.en.mdx @@ -0,0 +1,253 @@ +--- +title: HTTP Request +description: FastGPT HTTP Request node overview +--- + +import { Alert } from '@/components/docs/Alert'; + +## Characteristics + +- Can be added multiple times +- Manual configuration +- Trigger-based execution +- Core of core modules + +![](/imgs/http1.jpg) + +## Overview + +The HTTP node sends an `HTTP` request to a specified URL. It works similarly to tools like Postman and ApiFox. + +- Params are query parameters, commonly used in GET requests. +- Body is the request body, commonly used in POST/PUT requests. +- Headers are request headers for passing additional information. +- Custom variables can receive outputs from upstream nodes. +- All 3 data types support variable references via `{{}}`. +- The URL also supports `{{}}` variable references. +- Variables come from `global variables`, `system variables`, and `upstream node outputs`. + +## Parameter Structure + +### System Variables + +Hover over the question mark next to `Request Parameters` to see available variables. + +- appId: Application ID +- chatId: Current conversation ID (not available in test mode) +- responseChatItemId: Response message ID in the current conversation (not available in test mode) +- variables: Global variables for the current conversation +- cTime: Current time +- histories: Chat history (defaults to max 10 entries, length is not configurable) + +### Params, Headers + +Usage is the same as Postman and ApiFox. + +Use `{{key}}` to reference variables. For example: + +| key | value | +| --- | --- | +| appId | `{{appId}}` | +| Authorization | Bearer `{{token}}` | + +### Body + +Only takes effect with certain request types. + +Write a custom JSON body and use `{{key}}` to reference variables. For example: + + + + + +```json +{ + "string": "字符串", + "number": 123, + "boolean": true, + "array": [1, 2, 3], + "obj": { + "name": "FastGPT", + "url": "https://fastgpt.io" + } +} +``` + + + + + + +When referencing a `string` in the Body, wrap it in quotes: `"{{string}}"`. + +```json +{ + "string": "{{string}}", + "token": "Bearer {{string}}", + "number": {{number}}, + "boolean": {{boolean}}, + "array": [{{number}}, "{{string}}"], + "array2": {{array}}, + "object": {{obj}} +} +``` + + + + + + +```json +{ + "string": "字符串", + "token": "Bearer 字符串", + "number": 123, + "boolean": true, + "array": [123, "字符串"], + "array2": [1, 2, 3], + "object": { + "name": "FastGPT", + "url": "https://fastgpt.io" + } +} +``` + + + + + +### Extracting Return Values + +As shown in the image, FastGPT lets you add multiple return values. These don't represent the raw API response -- they define `how to parse the API response`. You can use `JSON path` syntax to `extract` values from the response. + +Syntax reference: https://github.com/JSONPath-Plus/JSONPath?tab=readme-ov-file + + + + + +```json +{ + "message": "测试", + "data":{ + "user": { + "name": "xxx", + "age": 12 + }, + "list": [ + { + "name": "xxx", + "age": 50 + }, + [{ "test": 22 }] + ], + "psw": "xxx" + } +} +``` + + + + + + +```json +{ + "$.message": "测试", + "$.data.user": { "name": "xxx", "age": 12 }, + "$.data.user.name": "xxx", + "$.data.user.age": 12, + "$.data.list": [ { "name": "xxx", "age": 50 }, [{ "test": 22 }] ], + "$.data.list[0]": { "name": "xxx", "age": 50 }, + "$.data.list[0].name": "xxx", + "$.data.list[0].age": 50, + "$.data.list[1]": [ { "test": 22 } ], + "$.data.list[1][0]": { "test": 22 }, + "$.data.list[1][0].test": 22, + "$.data.psw": "xxx" +} +``` + + + + + + +Configure the `key` to extract values from FastGPT's parsed format, following standard JavaScript object access rules. For example: + +1. To get the `message` content, set the `key` to `message`. +2. To get the user's name, set the `key` to `data.user.name`. +3. To get the second element in the list, set the `key` to `data.list[1]`. If you select string as the output type, it will automatically return the JSON string `[ { "test": 22 } ]`. + +### Auto-format Output + +Starting from FastGPT v4.6.8, output formatting was added, primarily converting `JSON` to `string`. If you select `string` as the output type, the HTTP node will convert the corresponding key's value to a JSON string. This lets you pipe HTTP output directly into a `Text Processing` node, append appropriate prompts, and feed the result into `AI Chat`. + + + +The HTTP node is extremely versatile. You can integrate public APIs to extend your workflow capabilities. + +If you don't want to deploy additional services, use [Laf](https://laf.dev/) to quickly develop and publish APIs -- write and ship instantly with no deployment needed. + + +## Laf HTTP Integration Example + + +Here is a POST request example written in Laf: + +```ts +import cloud from '@lafjs/cloud' +const db = cloud.database() + +type RequestType = { + appId: string; + appointment: string; + action: 'post' | 'delete' | 'put' | 'get' +} + +export default async function (ctx: FunctionContext) { + try { + // Get parameters from body + const { appId, appointment, action } = ctx.body as RequestType + + const parseBody = JSON.parse(appointment) + if (action === 'get') { + return await getRecord(parseBody) + } + if (action === 'post') { + return await createRecord(parseBody) + } + if (action === 'put') { + return await putRecord(parseBody) + } + if (action === 'delete') { + return await removeRecord(parseBody) + } + + + return { + response: "Error" + } + } catch (err) { + return { + response: "Error" + } + } +} +``` + +## Use Cases + +The HTTP node enables unlimited extensibility, such as: +- Database operations +- External data source calls +- Web searches +- Sending emails +- .... + + +## Related Examples + +- [Google Search](/docs/use-cases/app-cases/google_search/) +- [Send Lark Webhook](/docs/use-cases/app-cases/feishu_webhook/) +- [Lab Appointment (Database Operations)](/docs/use-cases/app-cases/lab_appointment/) diff --git a/document/content/docs/introduction/guide/dashboard/workflow/knowledge_base_search_merge.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/knowledge_base_search_merge.en.mdx new file mode 100644 index 0000000000..ecd20c9dfe --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/knowledge_base_search_merge.en.mdx @@ -0,0 +1,25 @@ +--- +title: Knowledge Base Search Merge +description: FastGPT Knowledge Base Search Merge node overview +--- + + +![](/imgs/knowledge_merge1.png) + +## What It Does + +Merges search results from multiple Knowledge Bases into a single output, re-ranks them using RRF (Reciprocal Rank Fusion), and supports max token filtering. + +## Usage + +The AI Chat node can only accept one Knowledge Base reference input. If you call multiple Knowledge Bases, you cannot directly reference all of them (as shown below). + +![](/imgs/knowledge_merge2.png) + +Use **Knowledge Base Search Merge** to combine results from multiple Knowledge Bases into one. + +![](/imgs/knowledge_merge3.png) + +## Example Use Cases + +1. After question classification, search different Knowledge Bases per category, then feed the merged results to a single AI Chat node. This avoids adding a separate AI Chat node to each branch. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/laf.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/laf.en.mdx new file mode 100644 index 0000000000..6b8be9bff5 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/laf.en.mdx @@ -0,0 +1,94 @@ +--- +title: Laf Function Call +description: FastGPT Laf Function Call node overview +--- + + +![](/imgs/laf1.webp) + +## Overview + +The `Laf Function Call` node invokes cloud functions under your Laf account. It works the same way as the HTTP node, with these differences: + +- Only POST requests are supported +- Requests automatically include `systemParams` -- no need to pass them via variables + +## Bind Your Laf Account + +To call Laf cloud functions, you first need to bind your Laf account and application, and create cloud functions within the application. + +Laf provides a PAT (Personal Access Token) for authentication outside the Laf platform. See the [Laf documentation](https://doc.Laf.run/zh/cli/#%E7%99%BB%E5%BD%95) for details on obtaining a PAT. + +After obtaining a PAT, go to FastGPT's `Account page` or the `Laf module` in the workflow editor to bind your Laf account. The Laf account is shared across the team and can only be configured by team admins. + +Enter the PAT for verification, then select the application to bind (the application must be in Running status). You can then call cloud functions under that application. + +![](/imgs/laf2.webp) + +## Writing Cloud Functions + +Laf cloud functions can auto-generate OpenAPI specs from TypeScript interfaces. Follow the code below to enable automatic OpenAPI documentation generation. + +The `Laf module` can automatically detect input/output parameters from the OpenAPI spec, so you don't need to add data types manually. If you're not familiar with TypeScript, you can skip this and add parameters manually in FastGPT. + +```ts +import cloud from '@lafjs/cloud' + +interface IRequestBody { // Custom input params. FastGPT always sends POST requests. + data1: string // Required parameter + data2?: string // Optional parameter +} + +interface RequestProps extends IRequestBody { // Full input params. No changes needed here. + systemParams: { // Default parameters passed by FastGPT + appId: string, + variables: string, + histories: string, + cTime: string, + chatId: string, + responseChatItemId: string + } +} + +interface IResponse { // Response content + message: string // Required return parameter + msg?: string; // Optional return parameter +} + +export default async function (ctx: FunctionContext): Promise { + const { + data1, + data2, + systemParams + }: RequestProps = ctx.body; + + console.log({ + data1, + data2, + systemParams + }); + + return { + message: 'ok', + msg: 'msg' + }; +} +``` + +You can also select the `fastgpt_template` on the Laf platform to quickly generate this function template. + +To do this, go to the Laf functions page and create a new function (note: FastGPT only calls POST functions). Then either paste the code above or click "More Templates" and search for "fastgpt" to use the template shown below. + +![](/imgs/laf3.webp) + +## Using in FastGPT + +After selecting a function, click "Sync Parameters" to automatically sync the cloud function's parameters into FastGPT. You can also add parameters manually -- manually modified parameters will not be overwritten by "Sync Parameters". + +![](/imgs/laf4.png) + +## Notes + +### Debugging Errors + +First debug the function in Laf to verify it works correctly. Use `console.log` to print the input parameters, then paste them into the Body field on Laf's test page to test. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/loop.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/loop.en.mdx new file mode 100644 index 0000000000..c94020ff7f --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/loop.en.mdx @@ -0,0 +1,290 @@ +--- +title: Batch Processing +description: FastGPT Batch Processing node overview and usage +--- + +## Node Overview + +The **Batch Processing** node was introduced in FastGPT V4.8.11. It allows workflows to iterate over array-type input data, processing one element at a time and automatically executing subsequent nodes until the entire array is processed. + +This node is inspired by loop structures in programming languages, presented in a visual format. + +![Batch Processing node](/imgs/fastgpt-loop-node.png) + +> In programming terms, nodes are like functions or API endpoints -- each one is a **step**. By connecting multiple nodes together, you build a step-by-step process that produces the final AI output. + +The **Batch Processing** node is essentially a function whose job is to automate repeated execution of a specific workflow. + +## Core Features + +1. **Array Batch Processing** + - Accepts array-type data input + - Automatically iterates through array elements + - Maintains processing order + - Supports parallel processing for performance optimization + +2. **Automatic Iteration** + - Automatically triggers downstream nodes + - Supports conditional termination + - Supports loop counting + - Maintains execution context + +3. **Works with Other Nodes** + - AI Chat nodes + - HTTP Request nodes + - Content Extraction nodes + - Conditional nodes + +## Use Cases + +The **Batch Processing** node extends workflow capabilities through automation, enabling FastGPT to handle batch tasks and complex data processing pipelines. It significantly improves efficiency when processing large-scale data or scenarios requiring multiple iterations. + +The **Batch Processing** node is ideal for: + +1. **Batch Data Processing** + - Batch text translation + - Batch document summarization + - Batch content generation + +2. **Data Pipeline Processing** + - Analyzing search results one by one + - Processing Knowledge Base retrieval results individually + - Processing array data from HTTP responses item by item + +3. **Recursive or Iterative Tasks** + - Long text segmented processing + - Multi-round content refinement + - Chained data processing + +## Usage + +### Input Parameters + +The **Batch Processing** node requires two core inputs: + +1. **Array (Required)**: An array-type input, which can be: + - String array (`Array`) + - Number array (`Array`) + - Boolean array (`Array`) + - Object array (`Array`) + +2. **Loop Body (Required)**: Defines the node flow executed in each iteration: + - Loop Body Start: Marks where the loop begins + - Loop Body End: Marks where the loop ends, with an optional output variable + +### Loop Body Configuration + +![Loop body configuration](/imgs/fastgpt-loop-node-config.webp) + +1. Inside the loop body, you can add any type of node: + - AI Chat node + - HTTP Request node + - Content Extraction node + - Text Processing node, etc. + +2. Loop Body End node configuration: + - Select the output variable from the dropdown + - This variable is collected as the current iteration's result + - Results from all iterations form a new array as the final output + +## Examples + +### Batch Processing an Array + +Suppose you have an array of texts that each need AI processing. This is the most basic and common use case. + +#### Steps + +1. Prepare the input array + + ![Prepare input array](/imgs/fastgpt-loop-node-example-1.png) + + Use a Code Execution node to create a test array: + + ```javascript + const texts = [ + "这是第一段文本", + "这是第二段文本", + "这是第三段文本" + ]; + return { textArray: texts }; + ``` + +2. Configure the Batch Processing node + + ![Configure Batch Processing node](/imgs/fastgpt-loop-node-example-2.png) + + - Array input: Select the `textArray` output from the previous Code Execution node. + - Add an AI Chat node inside the loop body to process each text. Set the prompt to: `Please translate this text to English`. + - Add a Specified Reply node to output the translated text. + - Set the Loop Body End node's output variable to the AI reply content. + +#### Execution Flow + +![Execution flow](/imgs/fastgpt-loop-node-example-3.png) + +1. The Code Execution node runs and generates the test array +2. The Batch Processing node receives the array and begins iteration +3. For each element: + - The AI Chat node processes the current element + - The Specified Reply node outputs the translated text + - The Loop Body End node collects the result +4. After all elements are processed, the result array is output + +### Long Text Translation + +When translating long texts, you often face these challenges: + +- Text length exceeds LLM token limits +- Translation style must remain consistent +- Context coherence must be maintained +- Translation quality may need multiple refinement passes + +The **Batch Processing** node handles these well. + +#### Steps + +1. Text preprocessing and segmentation + + ![Text preprocessing and segmentation](/imgs/fastgpt-loop-node-example-4.png) + + Use a Code Execution node for text segmentation: + + ```javascript + const MAX_HEADING_LENGTH = 7; // Max heading length + const MAX_HEADING_CONTENT_LENGTH = 200; // Max heading content length + const MAX_HEADING_UNDERLINE_LENGTH = 200; // Max heading underline length + const MAX_HTML_HEADING_ATTRIBUTES_LENGTH = 100; // Max HTML heading attributes length + const MAX_LIST_ITEM_LENGTH = 200; // Max list item length + const MAX_NESTED_LIST_ITEMS = 6; // Max nested list items + const MAX_LIST_INDENT_SPACES = 7; // Max list indent spaces + const MAX_BLOCKQUOTE_LINE_LENGTH = 200; // Max blockquote line length + const MAX_BLOCKQUOTE_LINES = 15; // Max blockquote lines + const MAX_CODE_BLOCK_LENGTH = 1500; // Max code block length + const MAX_CODE_LANGUAGE_LENGTH = 20; // Max code language length + const MAX_INDENTED_CODE_LINES = 20; // Max indented code lines + const MAX_TABLE_CELL_LENGTH = 200; // Max table cell length + const MAX_TABLE_ROWS = 20; // Max table rows + const MAX_HTML_TABLE_LENGTH = 2000; // Max HTML table length + const MIN_HORIZONTAL_RULE_LENGTH = 3; // Min horizontal rule length + const MAX_SENTENCE_LENGTH = 400; // Max sentence length + const MAX_QUOTED_TEXT_LENGTH = 300; // Max quoted text length + const MAX_PARENTHETICAL_CONTENT_LENGTH = 200; // Max parenthetical content length + const MAX_NESTED_PARENTHESES = 5; // Max nested parentheses + const MAX_MATH_INLINE_LENGTH = 100; // Max inline math length + const MAX_MATH_BLOCK_LENGTH = 500; // Max math block length + const MAX_PARAGRAPH_LENGTH = 1000; // Max paragraph length + const MAX_STANDALONE_LINE_LENGTH = 800; // Max standalone line length + const MAX_HTML_TAG_ATTRIBUTES_LENGTH = 100; // Max HTML tag attributes length + const MAX_HTML_TAG_CONTENT_LENGTH = 1000; // Max HTML tag content length + const LOOKAHEAD_RANGE = 100; // Lookahead range for sentence boundaries + + const AVOID_AT_START = `[\\s\\]})>,']`; // Characters to avoid at start + const PUNCTUATION = `[.!?…]|\\.{3}|[\\u2026\\u2047-\\u2049]|[\\p{Emoji_Presentation}\\p{Extended_Pictographic}]`; // Punctuation + const QUOTE_END = `(?:'(?=\`)|''(?=\`\`))`; // Quote end + const SENTENCE_END = `(?:${PUNCTUATION}(?] {0,${MAX_HTML_HEADING_ATTRIBUTES_LENGTH}}>)[^\\r\\n]{1,${MAX_HEADING_CONTENT_LENGTH}}(?:)?(?:\\r?\\n|$))` + + "|" + + // New pattern for citations + `(?:\\[[0-9]+\\][^\\r\\n]{1,${MAX_STANDALONE_LINE_LENGTH}})` + + "|" + + // 2. List items (bulleted, numbered, lettered, or task lists, including nested, up to three levels, with length constraints) + `(?:(?:^|\\r?\\n)[ \\t]{0,3}(?:[-*+•]|\\d{1,3}\\.\\w\\.|\\[[ xX]\\])[ \\t]+${SENTENCE_PATTERN.replace(/{MAX_LENGTH}/g, String (MAX_LIST_ITEM_LENGTH))}` + + `(?:(?:\\r?\\n[ \\t]{2,5}(?:[-*+•]|\\d{1,3}\\.\\w\\.|\\[[ xX]\\])[ \\t]+${SENTENCE_PATTERN.replace(/{MAX_LENGTH}/g, String (MAX_LIST_ITEM_LENGTH))}){0,${MAX_NESTED_LIST_ITEMS}}` + + `(?:\\r?\\n[ \\t]{4,${MAX_LIST_INDENT_SPACES}}(?:[-*+•]|\\d{1,3}\\.\\w\\.|\\[[ xX]\\])[ \\t]+${SENTENCE_PATTERN.replace(/{MAX_LENGTH}/g, String (MAX_LIST_ITEM_LENGTH))}){0,${MAX_NESTED_LIST_ITEMS}})?)` + + "|" + + // 3. Block quotes (including nested quotes and citations, up to three levels, with length constraints) + `(?:(?:^>(?:>|\\s{2,}){0,2}${SENTENCE_PATTERN.replace(/{MAX_LENGTH}/g, String(MAX_BLOCKQUOTE_LINE_LENGTH))}\\r?\\n?){1,$ {MAX_BLOCKQUOTE_LINES}})` + + "|" + + // 4. Code blocks (fenced, indented, or HTML pre/code tags, with length constraints) + `(?:(?:^|\\r?\\n)(?:\`\`\`|~~~)(?:\\w{0,${MAX_CODE_LANGUAGE_LENGTH}})?\\r?\\n[\\s\\S]{0,${MAX_CODE_BLOCK_LENGTH}}?(?:\`\`\`|~~~)\\r?\\n?` + + `|(?:(?:^|\\r?\\n)(?: {4}|\\t)[^\\r\\n]{0,${MAX_LIST_ITEM_LENGTH}}(?:\\r?\\n(?: {4}|\\t)[^\\r\\n]{0,${MAX_LIST_ITEM_LENGTH}}){0,$ {MAX_INDENTED_CODE_LINES}}\\r?\\n?)` + + `|(?:
(?:)?[\\s\\S]{0,${MAX_CODE_BLOCK_LENGTH}}?(?:)?
))` + + "|" + + // 5. Tables (Markdown, grid tables, and HTML tables, with length constraints) + `(?:(?:^|\\r?\\n)(?:\\|[^\\r\\n]{0,${MAX_TABLE_CELL_LENGTH}}\\|(?:\\r?\\n\\|[-:]{1,${MAX_TABLE_CELL_LENGTH}}\\|){0,1}(?:\\r?\\n\\|[^\\r\\n]{0,$ {MAX_TABLE_CELL_LENGTH}}\\|){0,${MAX_TABLE_ROWS}}` + + `|[\\s\\S]{0,${MAX_HTML_TABLE_LENGTH}}?
))` + + "|" + + // 6. Horizontal rules (Markdown and HTML hr tag) + `(?:^(?:[-*_]){${MIN_HORIZONTAL_RULE_LENGTH},}\\s*$|)` + + "|" + + // 10. Standalone lines or phrases (including single-line blocks and HTML elements, with length constraints) + `(?!${AVOID_AT_START})(?:^(?:<[a-zA-Z][^>]{0,${MAX_HTML_TAG_ATTRIBUTES_LENGTH}}>)?${SENTENCE_PATTERN.replace(/{MAX_LENGTH}/g, String (MAX_STANDALONE_LINE_LENGTH))}(?:)?(?:\\r?\\n|$))` + + "|" + + // 7. Sentences or phrases ending with punctuation (including ellipsis and Unicode punctuation) + `(?!${AVOID_AT_START})${SENTENCE_PATTERN.replace(/{MAX_LENGTH}/g, String(MAX_SENTENCE_LENGTH))}` + + "|" + + // 8. Quoted text, parenthetical phrases, or bracketed content (with length constraints) + "(?:" + + `(?)?${SENTENCE_PATTERN.replace(/{MAX_LENGTH}/g, String(MAX_PARAGRAPH_LENGTH))}(?:

)?(?=\\r? \\n\\r?\\n|$))` + + "|" + + // 11. HTML-like tags and their content (including self-closing tags and attributes, with length constraints) + `(?:<[a-zA-Z][^>]{0,${MAX_HTML_TAG_ATTRIBUTES_LENGTH}}(?:>[\\s\\S]{0,${MAX_HTML_TAG_CONTENT_LENGTH}}?|\\s*/>))` + + "|" + + // 12. LaTeX-style math expressions (inline and block, with length constraints) + `(?:(?:\\$\\$[\\s\\S]{0,${MAX_MATH_BLOCK_LENGTH}}?\\$\\$)|(?:\\$[^\\$\\r\\n]{0,${MAX_MATH_INLINE_LENGTH}}\\$))` + + "|" + + // 14. Fallback for any remaining content (with length constraints) + `(?!${AVOID_AT_START})${SENTENCE_PATTERN.replace(/{MAX_LENGTH}/g, String(MAX_STANDALONE_LINE_LENGTH))}` + + ")", + "gmu" + ); + + function main({text}){ + const chunks = []; + let currentChunk = ''; + const tokens = countToken(text) + + const matches = text.match(regex); + if (matches) { + matches.forEach((match) => { + if (currentChunk.length + match.length <= 1000) { + currentChunk += match; + } else { + if (currentChunk) { + chunks.push(currentChunk); + } + currentChunk = match; + } + }); + if (currentChunk) { + chunks.push(currentChunk); + } + } + + return {chunks, tokens}; + } + ``` + + This uses [a powerful regex open-sourced by Jina AI](https://x.com/JinaAI_/status/1823756993108304135) that leverages all possible boundary clues and heuristics for precise text splitting. + +2. Configure the Batch Processing node + + ![Configure Batch Processing node](/imgs/fastgpt-loop-node-example-5.png) + + - Array input: Select the `chunks` output from the previous Code Execution node. + - Add a Code Execution node inside the loop body to format the source text. + - Add a Search Glossary node to look up proper nouns from a terminology Knowledge Base before translation. + - Add an AI Chat node using CoT (Chain of Thought) to have the LLM explicitly generate a reasoning chain showing the complete translation thought process. + - Add a Code Execution node to extract the final translation result from the AI Chat node's last round. + - Add a Specified Reply node to output the translated text. + - Set the Loop Body End node's output variable to the `result` output from the Extract Translation Text node. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/meta.en.json b/document/content/docs/introduction/guide/dashboard/workflow/meta.en.json new file mode 100644 index 0000000000..14a59b13cf --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/meta.en.json @@ -0,0 +1,25 @@ +{ + "title": "Workflow Nodes", + "description": "FastGPT workflow node configuration and usage guide", + "pages": [ + "ai_chat", + "dataset_search", + "tool", + "question_classify", + "content_extract", + "user-selection", + "form_input", + "text_editor", + "reply", + "document_parsing", + "http", + "tfswitch", + "variable_update", + "sandbox", + "loop", + "knowledge_base_search_merge", + "coreferenceResolution", + "laf", + "custom_feedback" + ] +} diff --git a/document/content/docs/introduction/guide/dashboard/workflow/question_classify.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/question_classify.en.mdx new file mode 100644 index 0000000000..ed61d0efd3 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/question_classify.en.mdx @@ -0,0 +1,74 @@ +--- +title: Question Classification +description: FastGPT Question Classification node overview +--- + +## Characteristics + +- Can be added multiple times +- Has external input +- Requires manual configuration +- Trigger-based execution +- function_call module + +![](/imgs/cq1.png) + +## What It Does + +Classifies user questions into categories and executes different operations based on the result. Classification may be less effective in ambiguous scenarios. + +## Parameters + +### System Prompt + +Placed at the beginning of the conversation to provide supplementary definitions for classification categories. For example, questions might be classified as: + +1. Greetings +2. Laf FAQs +3. Other questions + +Since "Laf" isn't self-explanatory, you need to define it. The system prompt could include: + +``` +Laf is a cloud development platform for rapid application development +Laf is an open-source BaaS development platform (Backend as a Service) +Laf is a ready-to-use serverless development platform +Laf is an all-in-one development platform combining function computing, database, and object storage +Laf can be thought of as an open-source alternative to Google Firebase or similar cloud development platforms +``` + +### Chat History + +Adding some chat history enables context-aware classification. + +### User Question + +The user's input content. + +### Classification Categories + +Using the same 3 categories as an example, here is the resulting Function composition. The return values are randomly generated by the system and can be ignored. + +1. Greetings +2. Laf FAQs +3. Other questions + +```js +const agentFunction = { + name: agentFunName, + description: 'Determine which category the user question belongs to and return the corresponding enum value', + parameters: { + type: 'object', + properties: { + type: { + type: 'string', + description: `Greetings, return: abc; Laf FAQs, return: vvv; Other questions, return: aaa` + enum: ["abc","vvv","aaa"] + } + }, + required: ['type'] + } +}; +``` + +The Function above always returns one of `type = abc, vvv, aaa`, achieving the classification. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/reply.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/reply.en.mdx new file mode 100644 index 0000000000..f44e81b8a0 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/reply.en.mdx @@ -0,0 +1,18 @@ +--- +title: Specified Reply +description: FastGPT Specified Reply module overview +--- + +## Features + +- Can be added multiple times (helps keep complex workflows visually clean by avoiding tangled connections) +- Supports manual input +- Supports external input +- Outputs results to the client + +The Specified Reply module is typically used for special-case responses. There are two ways to define reply content: + +1. Manually enter fixed content. +2. Use variable references. + +![](/imgs/specialreply.png) diff --git a/document/content/docs/introduction/guide/dashboard/workflow/sandbox.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/sandbox.en.mdx new file mode 100644 index 0000000000..6b42d95d92 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/sandbox.en.mdx @@ -0,0 +1,96 @@ +--- +title: Code Execution +description: FastGPT Code Execution node overview +--- + +![alt text](/imgs/image.png) + +## Function + +Runs simple JavaScript code for complex data processing. Code executes in a sandbox with no access to network requests, DOM, or async operations. For advanced use cases, use an HTTP node instead. + +**Important Notes** + +- Self-hosted users must deploy the `fastgpt-sandbox` image and set the `SANDBOX_URL` environment variable. +- The sandbox enforces a 10-second max runtime and 32 MB memory limit. + +## Variable Input + +Add the variables your code needs via custom inputs. In the code's `main` function, destructure them by matching name. + +As shown above, the custom inputs include `data1` and `data2`, which can be destructured with the same names in the `main` function. + +## Result Output + +You must return an object. + +In custom outputs, add variable names to retrieve values from the corresponding object keys. For example, the image above returns: + +```json +{ + result: data1, + data2 +} +``` + +This object has 2 keys: `result` and `data2` (JS shorthand where key = data2, value = data2). You can then add 2 custom output variables to access the values under each key. + +## Built-in JS Global Variables + +### delay + +Returns after a 1-second delay: + +```js +async function main({data1, data2}){ + await delay(1000) + return { + result: "111" + } +} +``` + +### countToken + +```js +function main({input}){ + return { + result: countToken(input) + } +} +``` + +![alt text](/imgs/image-1.png) + +### strToBase64 (added in v4.8.11) + +Useful for converting SVG images to base64 format for display. + +```js +function main({input}){ + + return { + /* + param1: input - the string to convert + param2: base64 prefix + */ + result: strToBase64(input,'data:image/svg+xml;base64,') + } +} +``` + +![alt text](/imgs/image-2.png) + +### createHmac + +Works the same as Node.js crypto's `createHmac` method. + +```js +function main({secret}){ + const {sign,timestamp} = createHmac('sha256',secret) + + return { + sign,timestamp + } +} +``` diff --git a/document/content/docs/introduction/guide/dashboard/workflow/text_editor.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/text_editor.en.mdx new file mode 100644 index 0000000000..210d5eac8c --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/text_editor.en.mdx @@ -0,0 +1,27 @@ +--- +title: Text Concatenation +description: FastGPT Text Concatenation module overview +--- + +## Features + +- Can be added multiple times +- Has external inputs +- Trigger-based execution +- Manual configuration + +![](/imgs/string.png) + +## Function + +Applies fixed text processing to inputs. Input parameters only support string and number formats, and are used as variables in the text editing area. + +In the example above, any input will have "The user's question is:" prepended to it. + +## Use Cases + +Provide custom-formatted text to any module, or preprocess system prompts for AI modules. + +## Examples + +- [Google Search Integration](/docs/use-cases/app-cases/google_search/) diff --git a/document/content/docs/introduction/guide/dashboard/workflow/tfswitch.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/tfswitch.en.mdx new file mode 100644 index 0000000000..947b5a9e90 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/tfswitch.en.mdx @@ -0,0 +1,24 @@ +--- +title: Conditional (IF/ELSE) +description: FastGPT Conditional module overview +--- + +## Features + +- Can be added multiple times +- Has external inputs +- Trigger-based execution + +![](/imgs/judgement1.png) + +## Function + +Performs an `IF` evaluation on any variable. If the condition is met, the `IF` branch executes; otherwise the `ELSE` branch runs. + +In the example above, if the "Knowledge Base Citation" variable has a length of 0, the `IF` branch executes; otherwise the `ELSE` branch runs. + +You can add more conditions and branches, following the same logic as `IF` statements in programming languages. + +## Use Cases + +Common scenarios include: having the LLM make a judgment and then output fixed content, or checking the LLM's response to decide whether to trigger downstream modules. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/tool.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/tool.en.mdx new file mode 100644 index 0000000000..12c2793d54 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/tool.en.mdx @@ -0,0 +1,78 @@ +--- +title: Tool Calling & Termination +description: FastGPT Tool Calling module overview +--- + +![](/imgs/flow-tool1.png) + +### What is a Tool + +A tool can be a built-in module (e.g., AI Chat, Knowledge Base Search, HTTP) or a plugin. + +Tool calling lets the LLM dynamically decide the workflow path instead of following a fixed sequence. (The trade-off is higher token consumption.) + +### Tool Components + +1. **Tool description.** Typically the module or plugin description that tells the LLM what the tool does. +2. **Tool parameters.** For built-in modules, parameters are fixed and require no extra configuration. For plugins, parameters are configurable. + +### How Tools Work + +To understand how tools run, you need to know the execution prerequisites: + +1. A tool description is required. It tells the LLM what the tool does, and the LLM uses contextual semantics to decide whether to invoke it. +2. Tool parameters. Some tools require special parameters when called. Each parameter has two key properties: `parameter description` and `required`. + +Based on the tool description, parameter descriptions, and whether parameters are required, the LLM decides whether to call the tool. The scenarios are: + +1. **Tools without parameters:** The LLM decides based solely on the tool description. Example: get current time. +2. **Tools with parameters:** + 1. No required parameters: The tool can still be called even without suitable context parameters, though the LLM may sometimes fabricate a value. + 2. Has required parameters: If no suitable parameters are available, the LLM may skip the tool. Use prompts to guide users into providing the needed parameters. + +#### Tool Calling Logic + +Models that support `function calling` can invoke multiple tools in a single turn. The calling logic: + +![](/imgs/flow-tool2.png) + +### How to Use + +| | | +| --- | --- | +| ![](/imgs/flow-tool3.png) | ![](/imgs/flow-tool4.png) | + +In the advanced workflow editor, drag from the tool calling connection point. Eligible tools display a diamond icon at the top, which you can connect to the diamond at the bottom of the tool calling module. + +Connected tools automatically separate tool inputs from regular inputs. You can also edit the `description` to fine-tune when the tool gets called. + +Debugging tool calling is still more art than science, so start with a small number of tools, optimize them, then gradually add more. + +#### Use Cases + +By default, after the tool calling node invokes a tool, it returns the tool's output to the AI for summarization. If you don't need the AI to summarize, place this node at the end of the tool's workflow branch. + +In the example below, after the Knowledge Base Search runs, results are sent to an HTTP request. The search results are not returned to the tool calling node for AI summarization. + +![](/imgs/flow-tool5.png) + +### Additional Nodes + +When you use the tool calling node, a Tool Calling Termination node and a Custom Variable node also become available, further enhancing the tool calling experience. + +#### Tool Calling Termination + +Tool Calling Termination ends the current call cycle. Place it after a tool node. When the workflow reaches this node, it forcibly ends the current tool call -- no further tools are invoked, and the AI won't generate a summary based on tool results. + +![](/imgs/flow-tool6.png) + +### Custom Tool Variables + +Custom variables extend tool input capabilities. For nodes that aren't recognized as tool parameters or can't be directly tool-called, you can define custom tool variables with appropriate parameter descriptions. The tool calling node will then invoke this node and its downstream workflow accordingly. + +![](/imgs/flow-tool7.png) + +### Related Examples + +- [Google Search](https://doc.fastgpt.in/docs/use-cases/app-cases/google_search/) +- [Send Lark Webhook](https://doc.fastgpt.in/docs/use-cases/app-cases/feishu_webhook/) diff --git a/document/content/docs/introduction/guide/dashboard/workflow/user-selection.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/user-selection.en.mdx new file mode 100644 index 0000000000..d74b072b08 --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/user-selection.en.mdx @@ -0,0 +1,28 @@ +--- +title: User Selection +description: FastGPT User Selection module usage guide +--- + +## Features + +- User interaction +- Can be added multiple times +- Trigger-based execution + +![](/imgs/user-selection1.png) + +## Function + +The "User Selection" node is an interactive node. When triggered, the conversation enters an "interactive" state -- the workflow state is saved and execution pauses until the user completes the interaction. + +![](/imgs/user-selection2.png) + +In the example above, when the User Selection node triggers, the chat input is hidden and the conversation enters interactive mode. + +![](/imgs/user-selection3.png) + +When the user makes a choice, the node evaluates the selection and executes the corresponding branch (e.g., the "Yes" branch). + +## Use Cases + +The basic pattern is to present a question that requires a user decision, then route to different workflow paths based on the user's response. diff --git a/document/content/docs/introduction/guide/dashboard/workflow/variable_update.en.mdx b/document/content/docs/introduction/guide/dashboard/workflow/variable_update.en.mdx new file mode 100644 index 0000000000..add07122ef --- /dev/null +++ b/document/content/docs/introduction/guide/dashboard/workflow/variable_update.en.mdx @@ -0,0 +1,34 @@ +--- +title: Variable Update +description: FastGPT Variable Update module overview +--- + +## Features + +- Can be added multiple times +- Has external inputs +- Trigger-based execution +- Manual configuration + +![](/imgs/variable_update1.png) + +## Function + +- Update the output value of a specified node + +![](/imgs/variable_update2.png) + +![](/imgs/variable_update3.png) + +- Update global variables + +![](/imgs/variable_update4.png) + +![](/imgs/variable_update5.png) + +## Use Cases + +Common scenarios include: + +- Assign a value to a "Custom Variable" type global variable, so the global variable doesn't require user input +- Update a workflow node's output upstream of the Variable Update node, so downstream nodes use the new value diff --git a/document/content/docs/introduction/guide/knowledge_base/RAG.en.mdx b/document/content/docs/introduction/guide/knowledge_base/RAG.en.mdx new file mode 100644 index 0000000000..64a5ed66d7 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/RAG.en.mdx @@ -0,0 +1,262 @@ +--- +title: Knowledge Base Fundamentals +description: This section covers the core mechanisms, application scenarios, advantages, and limitations of the RAG model in generation tasks. +--- + +[RAG Documentation](https://huggingface.co/docs/transformers/model_doc/rag) + +# 1. Introduction + +As natural language processing (NLP) technology has advanced rapidly, generative language models (such as GPT and BART) have excelled at text generation tasks, particularly in language generation and context understanding. However, purely generative models have inherent limitations when handling factual tasks. Since these models rely on fixed pre-training data, they may "hallucinate" — fabricating information when answering questions that require up-to-date or real-time knowledge, leading to inaccurate or unfounded results. Additionally, generative models often struggle with long-tail questions and complex reasoning tasks due to a lack of domain-specific external knowledge. + +Meanwhile, retrieval models (Retrievers) can quickly locate relevant information across massive document collections, addressing factual query needs. However, traditional retrieval models (such as BM25) often return isolated results when facing ambiguous queries or cross-domain questions, and cannot generate coherent natural language answers. Without contextual reasoning capabilities, the answers they produce tend to lack coherence and completeness. + +To address the shortcomings of both approaches, Retrieval-Augmented Generation (RAG) was developed. RAG combines the strengths of generative and retrieval models by fetching relevant information from external knowledge bases in real time and incorporating it into the generation process. This ensures that generated text is both contextually coherent and factually grounded. This hybrid architecture performs particularly well in intelligent Q&A, information retrieval and reasoning, and domain-specific content generation. + +## 1.1 Definition of RAG + +RAG is a hybrid architecture that combines information retrieval with generative models. First, the retriever fetches content fragments relevant to the user's query from an external knowledge base or document collection. Then, the generator produces natural language output based on these retrieved fragments, ensuring the output is information-rich, highly relevant, and accurate. + +# 2. Core Mechanisms of RAG + +RAG models consist of two main modules: the Retriever and the Generator. These modules work together to ensure generated text contains relevant external knowledge while maintaining natural, fluent language. + +## 2.1 Retriever + +The retriever's primary task is to fetch the most relevant content from an external knowledge base or document collection for a given input query. Common techniques in RAG include: + +- Vector retrieval: Using models like BERT to convert documents and queries into vector space representations, then matching them via similarity calculations. Vector retrieval excels at capturing semantic similarity rather than relying solely on lexical matching. +- Traditional retrieval algorithms: Such as BM25, which uses term frequency and inverse document frequency (TF-IDF) weighted scoring to rank and retrieve documents. BM25 works well for straightforward keyword matching tasks. + +The retriever in RAG provides contextual background for the generator, enabling it to produce more relevant answers based on the retrieved document fragments. + +## 2.2 Generator + +The generator is responsible for producing the final natural language output. Common generators in RAG systems include: + +- BART: A sequence-to-sequence model focused on text generation, capable of improving output quality through various noise-handling techniques. +- GPT series: Pre-trained language models that excel at generating fluent, natural text, particularly strong in generation tasks thanks to large-scale training data. + +After receiving document fragments from the retriever, the generator uses them as context alongside the input query to produce relevant, natural text answers. This ensures the output draws on both existing knowledge and the latest external information. + +## 2.3 RAG Workflow + +The RAG model workflow can be summarized as follows: + +1. Input query: The user submits a question, which the system converts to a vector representation. +2. Document retrieval: The retriever extracts the most relevant document fragments from the knowledge base, typically using vector retrieval or traditional techniques like BM25. +3. Answer generation: The generator receives the retrieved fragments and produces a natural language answer based on both the original query and the retrieved context, providing richer, more contextually relevant responses. +4. Output: The generated answer is returned to the user, ensuring they receive an accurate response grounded in relevant, up-to-date information. + +# 3. How RAG Works + +## 3.1 Retrieval Phase + +In RAG, the user's query is first converted to a vector representation, then vector search is performed against the knowledge base. The retriever typically uses pre-trained models like BERT to generate vector representations of both queries and document fragments, matching the most relevant fragments through similarity calculations (such as cosine similarity). RAG's retriever goes beyond simple keyword matching by using semantic-level vector representations, enabling more accurate results even for complex or ambiguous queries. This step is critical because retrieval quality directly determines the context available to the generator. + +## 3.2 Generation Phase + +The generation phase is the core of RAG. The generator produces coherent, natural text answers based on retrieved content. RAG generators like BART or GPT combine the user's query with retrieved document fragments to produce more precise and comprehensive answers. Unlike traditional generative models, RAG's generator can incorporate factual information from external knowledge bases, improving accuracy. + +## 3.3 Multi-Turn Interaction and Feedback + +RAG models effectively support multi-turn interactions in dialogue systems. Each round's query and generated results serve as input for the next round. Through this feedback loop, RAG progressively refines its retrieval and generation strategies, producing increasingly relevant answers across multiple conversation turns. This also enhances RAG's adaptability in complex dialogue scenarios involving cross-turn knowledge integration and reasoning. + +# 4. Advantages and Limitations of RAG + +## 4.1 Advantages + +- Information completeness: RAG combines retrieval and generation, producing text that is both naturally fluent and grounded in real-time information from external knowledge bases. This significantly improves accuracy in knowledge-intensive scenarios like medical Q&A or legal opinion generation, avoiding the risk of hallucinated information. +- Knowledge reasoning: RAG can efficiently retrieve from large-scale external knowledge bases and reason with real data to generate fact-based answers. Compared to traditional generative models, RAG handles more complex tasks, particularly cross-domain or cross-document reasoning — such as legal case analysis or financial report generation. +- Strong domain adaptability: RAG adapts well across domains, performing efficient retrieval and generation within specific fields. In domains like healthcare, law, and finance that require real-time updates and high accuracy, RAG outperforms models that rely solely on pre-training. + +## 4.2 Limitations + +Despite its strong potential and cross-domain adaptability, RAG faces several key limitations in practice that constrain large-scale deployment and optimization: + +#### 4.2.1 Retriever Dependency and Quality Issues + +RAG performance depends heavily on the quality of documents returned by the retriever. If retrieved fragments are irrelevant or inaccurate, the generated text may be biased or misleading — especially with ambiguous queries or cross-domain retrieval. + +- Challenge: Improving retriever precision for complex queries across large, diverse knowledge bases remains difficult. Methods like BM25 have limitations, particularly with semantically ambiguous queries where keyword matching falls short. +- Solution: Adopt hybrid retrieval combining sparse retrieval (BM25) with dense retrieval (vector search). For example, Faiss enables BERT-based dense vector representations that significantly improve semantic matching, reducing the impact of irrelevant documents on generation. + +#### 4.2.2 Generator Computational Complexity and Performance Bottlenecks + +Combining retrieval and generation modules significantly increases computational complexity. When processing large datasets or long texts, the generator must integrate information from multiple document fragments, increasing generation time and reducing inference speed. This is a major bottleneck for real-time Q&A systems. + +- Challenge: As knowledge base scale grows, both retrieval computation and the generator's multi-fragment integration capabilities significantly impact system efficiency. GPU and memory consumption can multiply in multi-turn dialogues or complex generation tasks. +- Solution: Use model compression and knowledge distillation to reduce generator complexity and inference time. Distributed computing and model parallelization techniques like [DeepSpeed](https://www.deepspeed.ai/) can effectively handle high computational demands in large-scale scenarios. + +#### 4.2.3 Knowledge Base Updates and Maintenance + +RAG models typically rely on a pre-built external knowledge base containing documents, papers, legal provisions, and other information. The timeliness and accuracy of this content directly affects the credibility of generated results. Over time, knowledge base content may become outdated, producing answers that don't reflect current information — particularly problematic in fast-moving fields like healthcare and finance. + +- Challenge: Knowledge bases need frequent updates, but manual updates are time-consuming and error-prone. Implementing continuous automated updates without impacting system performance is a significant challenge. +- Solution: Use automated crawlers and information extraction systems (such as Scrapy) to automatically fetch and update knowledge base content. Combined with [dynamic indexing techniques](https://arxiv.org/pdf/2102.03315), retrievers can update indexes in real time. Incremental learning allows the generator to gradually absorb new information, avoiding outdated answers. + +#### 4.2.4 Generated Content Controllability and Transparency + +RAG models have controllability and transparency challenges. In complex tasks or with ambiguous user input, the generator may produce incorrect reasoning based on inaccurate document fragments. Due to RAG's "black box" nature, users find it difficult to understand how the generator uses retrieved information — a significant concern in sensitive domains like law and healthcare, potentially eroding user trust. + +- Challenge: Insufficient model transparency makes it hard for users to verify the source and credibility of generated answers. For tasks requiring high explainability (medical consultations, legal advice), inability to trace answer sources undermines trust. +- Solution: Introduce explainable AI (XAI) techniques like LIME or SHAP ([link](https://github.com/marcotcr/lime)) to provide detailed provenance for each generated answer, showing which knowledge fragments were referenced. Additionally, rule constraints and user feedback mechanisms can progressively optimize generator output for greater trustworthiness. + +# 5. RAG Improvement Directions + +RAG model performance depends on knowledge base accuracy and retrieval efficiency. Optimizing data collection, content chunking, retrieval precision, and answer generation are key to improving overall effectiveness. + +## 5.1 Data Collection and Knowledge Base Construction + +RAG's core dependency is knowledge base data quality and breadth — the knowledge base serves as "external memory." A high-quality knowledge base should include content from diverse, authoritative sources such as scientific literature databases (PubMed, IEEE Xplore), established news media, and industry standards and reports. It also needs automated update capabilities to stay current. + +- Challenges: + - Single or limited data sources leading to insufficient coverage across domains + - Inconsistent data quality from non-authoritative or low-quality sources introducing bias + - Lack of regular update mechanisms, especially in fast-changing fields like law, finance, and technology + - Time-consuming and error-prone data processing workflows + - Data sensitivity and privacy concerns in domains like healthcare, law, and finance + +- Improvements: + - Expand data source coverage across multiple domains, including specialized databases like PubMed, LexisNexis, and financial databases + - Build data quality review and filtering mechanisms using automated detection algorithms combined with manual review + - Implement automated knowledge base updates using web crawlers with change detection algorithms + - Adopt efficient data cleaning and classification using NLP techniques like BERT for entity recognition and text denoising + - Strengthen data security with de-identification, anonymization, and differential privacy protection + - Standardize data formats using JSON, XML, or knowledge graphs for structured storage + - Incorporate user feedback mechanisms to continuously optimize knowledge base content + +## 5.2 Data Chunking and Content Management + +Proper chunking strategies help models efficiently locate target information and provide clear context during answer generation. Chunking by paragraph, section, or topic improves retrieval efficiency and prevents redundant data from interfering with generation — especially important in complex, long-form text. + +- Challenges: + - Unreasonable chunking breaking information chains and context + - Redundant data causing repetitive or overloaded generated content + - Inappropriate chunk granularity affecting retrieval precision + - Difficulty implementing topic-based or logic-based chunking for complex texts + +- Improvements: + - Use NLP techniques (syntactic analysis, semantic segmentation) for automated, logic-based chunking + - Apply deduplication and information consolidation using similarity algorithms (TF-IDF, cosine similarity) + - Dynamically adjust chunk granularity based on task requirements + - Introduce topic-based chunking using topic models (LDA) or embedding-based text clustering + - Implement feedback mechanisms to continuously evaluate and optimize chunking strategies + +## 5.3 Retrieval Optimization + +The retrieval module determines the relevance and accuracy of generated answers. Hybrid retrieval strategies (combining BM25 and DPR) complement each other — BM25 handles keyword matching efficiently while DPR excels at deep semantic understanding. + +- Challenges: + - Single retrieval strategies causing answer bias + - Tension between retrieval efficiency and resource consumption + - Redundant retrieval results leading to repetitive content + - Poor adaptability of fixed retrieval strategies across different task types + +- Improvements: + - Combine BM25 and DPR in a hybrid retrieval strategy — BM25 for initial keyword filtering, then DPR for deep semantic matching + - Optimize retrieval efficiency using caching for frequent queries and distributed computing for parallel processing + - Apply deduplication and ranking optimization algorithms to retrieval results + - Dynamically adjust retrieval strategies based on task type — favoring semantic retrieval for medical Q&A, keyword matching for news scenarios + - Integrate retrieval optimization frameworks like Haystack for enhanced extensibility + +## 5.4 Answer Generation and Optimization + +The generator produces natural language answers based on retrieved context. Accuracy and logical coherence directly impact user experience. Knowledge graphs and structured information help the generator better understand and connect context for more coherent, accurate answers. + +- Challenges: + - Insufficient context leading to logically incoherent answers + - Inadequate accuracy in specialized domain answers + - Difficulty effectively integrating multi-turn user feedback + - Insufficient controllability and consistency in generated content + +- Improvements: + - Integrate knowledge graphs and structured data to enhance context understanding + - Design domain-specific generation rules and terminology constraints + - Optimize user feedback mechanisms for dynamic generation logic adjustment + - Implement collaborative optimization between generator and retriever — allowing the generator to request additional context as needed + - Apply consistency detection and semantic correction to ensure uniform terminology and logical structure + +## 5.5 RAG Pipeline + +![](/imgs/RAG1.png) + +1. Data loading and query input: + 1. The user submits a natural language query through the UI or API. + 2. The input is passed to a vectorizer (such as BERT or Sentence Transformer) to convert the query into a vector representation. +2. Document retrieval: + 1. The vectorized query is passed to the retriever, which finds the most relevant document fragments in the knowledge base. + 2. Retrieval can use sparse techniques (BM25) or dense techniques (DPR) for improved matching efficiency and precision. +3. Generator processing and natural language generation: + 1. Retrieved document fragments are fed to the generator (such as GPT, BART, or T5), which produces a natural language answer based on the query and document content. + 2. The generator combines external retrieval results with pre-trained language knowledge for more precise, natural answers. +4. Result output: + 1. The generated answer is returned to the user via API or UI, ensuring coherence and factual accuracy. +5. Feedback and optimization: + 1. Users can provide feedback on generated answers, which the system uses to optimize retrieval and generation. + 2. Through model fine-tuning or retrieval weight adjustments, the system progressively improves accuracy and efficiency. + +# 6. RAG Case Studies + +[RAG Across Various Domains](https://github.com/hymie122/RAG-Survey) + +# 7. RAG Applications + +RAG models have been widely adopted across multiple domains: + +## 7.1 Intelligent Q&A Systems + +- RAG generates accurate, detailed answers by retrieving from external knowledge bases in real time, avoiding the hallucination issues of traditional generative models. For example, in medical Q&A systems, RAG can incorporate the latest medical literature to generate answers with current treatment protocols, helping medical professionals quickly access the latest research and clinical recommendations. + - [Medical Q&A System Case Study](https://www.apexon.com/blog/empowering-discovery-the-role-of-rag-architecture-generative-ai-in-healthcare-life-sciences/) + - ![](/imgs/RAG2.png) + - User submits a query through the web application: + 1. The user enters a query in the web app, which enters the backend system and initiates the data processing pipeline. + - Authentication via Azure AD: + 1. The system authenticates the user through Azure Active Directory (Azure AD), ensuring only authorized users can access the system and data. + - User permission check: + 1. The system filters accessible content based on user group permissions managed by Azure AD. + - Azure AI Search Service: + 1. The filtered query is passed to Azure AI Search, which finds relevant content in indexed databases or documents using semantic search. + - Document intelligence processing: + 1. The system uses OCR and document extraction to convert unstructured data into structured, searchable data for Azure AI retrieval. + - Document sources: + 1. Documents come from pre-stored collections that have been processed and indexed before user queries. + - Azure OpenAI generates response: + 1. After retrieving relevant information, data is passed to Azure OpenAI, which uses natural language generation (NLG) to produce a coherent answer based on the query and retrieval results. + - Response returned to user: + 1. The final answer is returned through the web application, completing the query-to-response flow. + - The entire pipeline demonstrates Azure AI technology integration, handling complex queries through document retrieval, intelligent processing, and natural language generation while ensuring data security and compliance. + +## 7.2 Information Retrieval and Text Generation + +- Text generation: RAG can not only retrieve relevant documents but also generate summaries, reports, or document abstracts, enhancing coherence and accuracy. For example, in the legal domain, RAG can integrate relevant statutes and case law to generate detailed legal opinions, ensuring comprehensiveness and rigor — particularly valuable for lawyers and legal practitioners to improve efficiency. + - [Legal Domain RAG Case Study](https://www.apexon.com/blog/empowering-discovery-the-role-of-rag-architecture-generative-ai-in-healthcare-life-sciences/) + - Summary: + - Background: Traditional LLMs perform well in generation tasks but have limitations with complex legal tasks. Legal documents have unique structures and terminology that standard retrieval benchmarks often fail to capture. LegalBench-RAG aims to provide a dedicated benchmark for evaluating legal document retrieval. + - LegalBench-RAG structure: + 1. ![](/imgs/RAG3.png) + 2. Workflow: + 3. User inputs a question (Q: ?, A: ?): The user submits a query through the interface. + 4. Embed + Retrieve module: Receives the query, embeds it as a vector, and performs similarity search in external knowledge bases or documents. + 5. Answer generation (A): Based on the most relevant retrieved information, the generation model produces a coherent natural language answer. + 6. Compare and return results: The generated answer is compared with previous related answers and returned to the user. + 7. The benchmark is built on the LegalBench dataset with 6,858 query-answer pairs traced to exact locations in original legal documents. + 8. LegalBench-RAG focuses on precisely retrieving small passages from legal texts rather than broad, contextually irrelevant fragments. + 9. The dataset covers various legal document types including contracts and privacy policies, ensuring coverage across multiple legal scenarios. + - Significance: LegalBench-RAG is the first publicly available benchmark specifically for legal retrieval systems, providing a standardized framework for comparing retrieval algorithms in high-precision legal tasks such as citation lookup and clause interpretation. + - Key challenges: + 1. RAG's generation component depends on retrieved information — incorrect retrieval can lead to incorrect generation. + 2. The length and terminological complexity of legal documents increase retrieval and generation difficulty. + - Quality control: The dataset construction process ensures high-quality human annotations and textual precision, with multiple rounds of manual verification when mapping annotation categories and document IDs to specific text fragments. + +## 7.3 Other Applications + +RAG can also be applied to multimodal generation scenarios, including image, audio, and 3D content generation. Cross-modal applications like ReMoDiffuse and Make-An-Audio leverage RAG technology for generation across different data modalities. In enterprise decision support, RAG can rapidly retrieve external resources (industry reports, market data) to generate high-quality forward-looking reports, enhancing strategic decision-making capabilities. + +## 8. Summary + +This document systematically covers the core mechanisms, advantages, and applications of Retrieval-Augmented Generation (RAG). By combining generative and retrieval models, RAG addresses the hallucination problem of traditional generative models in factual tasks and the inability of retrieval models to produce coherent natural language output. RAG models retrieve information from external knowledge bases in real time, generating content that is both factually accurate and linguistically fluent — applicable to knowledge-intensive domains like healthcare, law, and intelligent Q&A systems. + +In practice, while RAG offers significant advantages in information completeness, reasoning capability, and cross-domain adaptability, it also faces challenges around data quality, computational resource consumption, and knowledge base maintenance. To further improve RAG performance, this document proposes comprehensive improvements across data collection, content chunking, retrieval strategy optimization, and answer generation — including knowledge graph integration, user feedback optimization, and efficient deduplication algorithms — to enhance model applicability and efficiency. + +RAG has demonstrated strong potential in intelligent Q&A, information retrieval, and text generation, and continues to expand into multimodal generation and enterprise decision support. Through hybrid retrieval techniques, knowledge graphs, and dynamic feedback mechanisms, RAG can flexibly address complex user needs, generating factually grounded and logically coherent answers. Going forward, RAG will further improve trustworthiness and practicality in specialized domains through enhanced model transparency and controllability, providing broader applications for intelligent information retrieval and content generation. diff --git a/document/content/docs/introduction/guide/knowledge_base/api_dataset.en.mdx b/document/content/docs/introduction/guide/knowledge_base/api_dataset.en.mdx new file mode 100644 index 0000000000..515080fcb8 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/api_dataset.en.mdx @@ -0,0 +1,183 @@ +--- +title: API File Library +description: Introduction and usage of the FastGPT API File Library +--- + +import { Alert } from '@/components/docs/Alert'; + +| | | +| --- | --- | +| ![](/imgs/image-18.png) | ![](/imgs/image-19.png) | + +## Background + +FastGPT supports local file imports, but in many cases users already have an existing document library. Re-importing files would create duplicate storage and complicate management. To address this, FastGPT offers an API File Library that connects to your existing document library through simple API endpoints, with flexible import options. + +The API File Library lets you integrate your existing document library seamlessly. Implement a few endpoints that conform to FastGPT's API File Library specification, provide the service's baseURL and token when creating a knowledge base, and you can browse and selectively import files directly from the UI. + +## How to Use the API File Library + +When creating a knowledge base, select the API File Library type and configure two key parameters: the baseURL of your file service and the request header for authentication. As long as your endpoints conform to FastGPT's specification, the system will automatically fetch and display the complete file list for selective import. + +You need to provide two parameters: +- baseURL: The base URL of your file service +- authorization: The authentication request header, sent as `Authorization: Bearer ` + +## API Specification + +Response format: + +```ts +type ResponseType = { + success: boolean; + message: string; + data: any; +} +``` + +Data types: + +```ts +// Single file item in the file list +type FileListItem = { + id: string; + parentId: string | null; + name: string; + type: 'file' | 'folder'; + updateTime: Date; + createTime: Date; +} +``` + + +### 1. Get File Tree + + + + + + +- parentId - Parent ID, optional or null. +- searchKey - Search keyword, optional + + +```bash +curl --location --request POST '{{baseURL}}/v1/file/list' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "parentId": null, + "searchKey": "" +}' +``` + + + + + + + +```json +{ + "code": 200, + "success": true, + "message": "", + "data": [ + { + "id": "xxxx", + "parentId": "xxxx", + "type": "file", // file | folder + "name":"test.json", + "updateTime":"2024-11-26T03:05:24.759Z", + "createTime":"2024-11-26T03:05:24.759Z" + } + ] +} +``` + + + + + +### 2. Get Single File Content (Text Content or Access Link) + + + + + +```bash +curl --location --request GET '{{baseURL}}/v1/file/content?id=xx' \ +--header 'Authorization: Bearer {{authorization}}' +``` + + + + + + + +```json +{ + "code": 200, + "success": true, + "message": "", + "data": { + "title": "Document Title", + "content": "FastGPT is an LLM-based knowledge base Q&A system with out-of-the-box data processing and model invocation capabilities. It also supports visual workflow orchestration via Flow for complex Q&A scenarios!\n", + "previewUrl": "xxxx" + } +} +``` + + + +- title - File title. +- content - File content, used directly. +- previewUrl - File link; the system will request this URL to fetch the file content. + +Return either `content` or `previewUrl`. If both are returned, `content` takes priority. When `previewUrl` is returned, the system will access that link to read the document content. + + + + + + + + +### 3. Get File Read Link (for Viewing the Original) + + + + + +id is the file's ID. + +```bash +curl --location --request GET '{{baseURL}}/v1/file/read?id=xx' \ +--header 'Authorization: Bearer {{authorization}}' +``` + + + + + + + +```json +{ + "code": 200, + "success": true, + "message": "", + "data": { + "url": "xxxx" + } +} +``` + + +- url - File access link; opens automatically once retrieved. + + + + + diff --git a/document/content/docs/introduction/guide/knowledge_base/collection_tags.en.mdx b/document/content/docs/introduction/guide/knowledge_base/collection_tags.en.mdx new file mode 100644 index 0000000000..821b6be373 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/collection_tags.en.mdx @@ -0,0 +1,46 @@ +--- +title: Knowledge Base Collection Tags +description: How to use collection tags in FastGPT Knowledge Base +--- + +Collection tags are a commercial-edition feature in FastGPT. They let you tag and categorize data collections within a knowledge base for more efficient data management. + +You can also use tags as collection filters during knowledge base searches for more precise results. + +| | | | +| --------------------- | --------------------- | --------------------- | +| ![](/imgs/collection-tags-1.png) | ![](/imgs/collection-tags-2.png) | ![](/imgs/collection-tags-3.png) | + +## Basic Tag Operations + +On the knowledge base detail page, you can manage tags with the following operations: + +- Create a tag +- Rename a tag +- Delete a tag +- Assign a tag to multiple collections +- Add multiple tags to a single collection + +You can also filter collections by tags. + +## Collection Filtering in Knowledge Base Search + +Tags can be used to filter collections during knowledge base searches by filling in the "Collection Filter" field. Here's an example: + +```json +{ + "tags": { + "$and": ["Tag 1","Tag 2"], + "$or": ["When $and tags are present, $and takes effect and $or is ignored"] + }, + "createTime": { + "$gte": "YYYY-MM-DD HH:mm format, matches collections created after this time", + "$lte": "YYYY-MM-DD HH:mm format, matches collections created before this time. Can be used together with $gte" + } +} +``` + +Two important notes: + +- Tag values can be a `string` tag name or `null`, where `null` represents collections with no tags assigned +- There are two filter condition types: `$and` and `$or`. When both are set, only `$and` takes effect diff --git a/document/content/docs/introduction/guide/knowledge_base/dataset_engine.en.mdx b/document/content/docs/introduction/guide/knowledge_base/dataset_engine.en.mdx new file mode 100644 index 0000000000..6e0440df6e --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/dataset_engine.en.mdx @@ -0,0 +1,134 @@ +--- +title: Knowledge Base Search Methods and Parameters +description: + This section covers FastGPT's knowledge base architecture, including its QA + storage format and multi-vector mapping, to help you build better knowledge bases. It also explains each search parameter. This guide focuses on practical usage rather than in-depth theory. +--- + +## Understanding Vectors + +FastGPT uses an Embedding-based RAG approach for its knowledge base. To use FastGPT effectively, you need a basic understanding of how `Embedding` vectors work and their characteristics. + +Human text, images, videos, and other media cannot be directly understood by computers. To determine whether two pieces of text are similar or related, they typically need to be converted into a computer-readable format — vectors are one such method. + +A vector is essentially an array of numbers. The "distance" between two vectors can be calculated using mathematical formulas — the smaller the distance, the more similar the vectors. This maps back to text, images, videos, and other media to measure similarity between them. Vector search leverages this principle. + +Since text comes in many types with countless combinations, exact matching is hard to guarantee when converting to vectors for similarity comparison. In vector-based knowledge bases, a `top-k` recall approach is typically used — finding the top `k` most similar results and passing them to an LLM for further `semantic evaluation`, `logical reasoning`, and `summarization`, enabling knowledge base Q&A. This makes vector search the most critical step in the process. + +Many factors affect vector search accuracy, including: vector model quality, data quality (length, completeness, diversity), and retriever precision (the speed vs. accuracy tradeoff). Search query quality is equally important. + +Retriever precision is relatively straightforward to address, and training vector models is more complex, so optimizing data and query quality becomes a key focus. + + +### Improving Vector Search Accuracy + +1. Better tokenization and chunking: When a text segment has complete and singular structure and semantics, accuracy improves. Many systems optimize their tokenizers to preserve data completeness. +2. Streamline `index` content by reducing vector content length: Shorter, more precise `index` content improves search accuracy, though it may narrow the search scope. Best suited for scenarios requiring strict answers. +3. Increase `index` quantity: Add multiple `index` entries for the same `chunk` to improve recall. +4. Optimize search queries: In practice, user questions are often vague or incomplete. Refining the query (search term) can significantly improve accuracy. +5. Fine-tune vector models: Off-the-shelf vector models are general-purpose and may underperform in specific domains. Fine-tuning can greatly improve domain-specific search results. + +## FastGPT Knowledge Base Architecture + +### Data Storage Structure + +In FastGPT, a knowledge base consists of three parts: libraries, collections, and data entries. A collection can be thought of as a "file." A library can contain multiple collections, and a collection can contain multiple data entries. The smallest searchable unit is the library — searches span the entire library. Collections are only for organizing and managing data and do not affect search results (at least for now). + +![](/imgs/dataset_tree.png) + +### Vector Storage Structure + +FastGPT uses `PostgreSQL`'s `PG Vector` extension as the vector retriever, with `HNSW` indexing. `PostgreSQL` is used solely for vector search (this engine can be swapped for other databases), while `MongoDB` handles all other data storage. + +In `MongoDB`'s `dataset.datas` collection, vector source data is stored along with an `indexes` field that records corresponding vector IDs. This is an array, meaning a single data entry can map to multiple vectors. + +In `PostgreSQL`, a `vector` field stores the vectors. During search, vectors are recalled first, then their IDs are used to look up the original data in `MongoDB`. If multiple vectors map to the same source data, they are merged and the highest vector score is used. + +![](/imgs/datasetSetting1.png) + +### Purpose and Usage of Multi-Vector Mapping + +In a single vector, content length and semantic richness are often at odds. FastGPT uses multi-vector mapping to map a single data entry to multiple vectors, preserving both data completeness and semantic richness. + +You can add multiple vectors to a longer text so that if any one vector is matched during search, the entire data entry is recalled. + +This means you can continuously improve data chunk accuracy through annotation. + +### Search Pipeline + +1. Use `Query Optimization` for coreference resolution and query expansion, improving multi-turn conversation search capability and semantic richness. +2. Use `Concat Query` to improve `Rerank` accuracy during multi-turn conversations. +3. Use `RRF` (Reciprocal Rank Fusion) to merge results from multiple search channels. +4. Use `Rerank` for secondary sorting to improve precision. + +![](/imgs/dataset_search_process.png) + + +## Search Parameters +| | | | +| --- |---| --- | +|![](/imgs/dataset_search_params1.png)| ![](/imgs/dataset_search_params2.png) | ![](/imgs/dataset_search_params3.png) | + +### Search Modes + +#### Semantic Search + +Semantic search calculates the vector distance between the user's query and knowledge base content to determine "similarity" — mathematical similarity, not linguistic. + +Pros: +- Understands similar semantics +- Cross-language understanding (e.g., Chinese query matching English content) +- Multimodal understanding (text, images, audio/video, etc.) + +Cons: +- Depends on model training quality +- Inconsistent accuracy +- Affected by keywords and sentence completeness + +#### Full-Text Search + +Uses traditional full-text search. Best for finding key subjects, predicates, and other specific terms. + +#### Hybrid Search + +Combines vector search and full-text search, merging results using the RRF formula. Generally produces richer and more accurate results. + +Since hybrid search covers a large range and cannot directly filter by similarity, a rerank model is typically used to re-sort results and filter by rerank scores. + +#### Result Reranking + +Uses a `ReRank` model to re-sort search results. In most cases, this significantly improves accuracy. Rerank models work better with complete questions (with proper subjects and predicates), so query optimization is usually applied before search and reranking. Reranking produces a score between `0-1` representing the relevance between the search content and the query — this score is typically more accurate than vector similarity scores and can be used for filtering. + +FastGPT uses `RRF` to merge rerank results, vector search results, and full-text search results into the final output. + +### Search Filters + +#### Reference Limit + +The maximum number of `tokens` to reference per search. + +Instead of using `top k`, we found that in mixed knowledge bases (Q&A + document), different `chunk` lengths vary significantly, making `top k` results unstable. Using a `token` limit provides more consistent control. + +#### Minimum Relevance + +A value between `0-1` that filters out low-relevance search results. + +This only takes effect when using `Semantic Search` or `Result Reranking`. + +### Query Optimization + +#### Background + +In RAG, we need to perform embedding searches against the database based on the input query to find similar content (i.e., knowledge base search). + +During search — especially in multi-turn conversations — follow-up questions often fail to find relevant content because knowledge base search only uses the "current" question. Consider this example: + +![](/imgs/coreferenceResolution2.webp) + +When the user asks "What's the second point?", the system searches for "What's the second point?" in the knowledge base, which returns nothing useful. The actual query should be "What is the QA structure?". This is why we need a Query Optimization module to complete the user's current question, enabling the knowledge base search to find relevant content. Here's the result after optimization: + +![](/imgs/coreferenceResolution3.webp) + +#### How It Works + +Before performing `data retrieval`, the model first performs `coreference resolution` and `query expansion`. This resolves ambiguous references and enriches the query's semantic content. You can view the optimized query in the conversation details after each interaction. diff --git a/document/content/docs/introduction/guide/knowledge_base/lark_dataset.en.mdx b/document/content/docs/introduction/guide/knowledge_base/lark_dataset.en.mdx new file mode 100644 index 0000000000..c16dccd052 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/lark_dataset.en.mdx @@ -0,0 +1,58 @@ +--- +title: Lark Knowledge Base +description: Introduction and usage of the FastGPT Lark Knowledge Base +--- + +| | | +| --- | --- | +| ![alt text](/imgs/image-39.png) | ![alt text](/imgs/image-40.png) | + +Starting from FastGPT v4.8.16, commercial edition users can import from Lark knowledge bases. Configure a Lark app's appId and appSecret, then select a **top-level folder in a document space** to import. This feature is currently in beta — some interactions may still need refinement. + +Due to Lark API limitations, you cannot directly access all document content. Currently, only files in shared space directories are accessible — personal spaces and wiki content are not supported. + +Only cloud document types are supported for import. + + +## 1. Create a Lark App + +Go to the [Lark Open Platform](https://open.feishu.cn/?lang=zh-CN), click **Create App**, select **Custom App**, and fill in the app name. + +## 2. Configure App Permissions + +After creating the app, configure the following **3 permissions**: + +1. View the list of cloud documents in a folder +2. View new-format documents +3. View, comment, edit, and manage all files in the cloud space + +![alt text](/imgs/image-41.png) + +## 3. Get the appId and appSecret + +![alt text](/imgs/image-42.png) + +## 4. Grant Folder Permissions + +Refer to the Lark tutorial: https://open.feishu.cn/document/server-docs/docs/drive-v1/faq#b02e5bfb + +In summary: + +1. Add the app you just created to a group chat +2. Grant directory permissions to that group + +If your directory already has permissions granted to the "All Members" group, you can skip the steps above and go directly to getting the Folder Token. + +![alt text](/imgs/image-43.png) + +## 5. Get the Folder Token + +You can find the Folder Token in the page URL. Make sure not to include the question mark. + +![alt text](/imgs/image-44.png) + +## 6. Create the Knowledge Base + +Using the 3 parameters obtained from steps 3 and 5, create a knowledge base. Select the Lark file library type, fill in the parameters, and click Create. + +![alt text](/imgs/image-39.png) diff --git a/document/content/docs/introduction/guide/knowledge_base/meta.en.json b/document/content/docs/introduction/guide/knowledge_base/meta.en.json new file mode 100644 index 0000000000..9e13f77f01 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/meta.en.json @@ -0,0 +1,15 @@ +{ + "title": "Knowledge Base", + "description": "Basic principles of knowledge base, search solutions, web site synchronization, and usage methods for external file knowledge bases.", + "pages": [ + "RAG", + "dataset_engine", + "collection_tags", + "api_dataset", + "lark_dataset", + "yuque_dataset", + "websync", + "third_dataset", + "template" + ] +} diff --git a/document/content/docs/introduction/guide/knowledge_base/template.en.mdx b/document/content/docs/introduction/guide/knowledge_base/template.en.mdx new file mode 100644 index 0000000000..8a427795a1 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/template.en.mdx @@ -0,0 +1,113 @@ +--- +title: Template Import +description: Introduction and usage of the FastGPT template import feature +--- + +## Background + +FastGPT provides a template import feature that lets you batch-import Q&A pair data using a predefined CSV template format. This is especially useful if you already have structured Q&A data and want to quickly load it into a knowledge base. + +## Template Structure + +The template uses CSV format with the following columns: + +- q: Question column — stores questions users might ask +- a: Answer column — stores the corresponding answers +- indexes: Index column — stores related indexes for the question + +### Example Data + +```csv +q,a,indexes +"Who are you?","I'm an AI assistant, always here to chat with you, answer your questions, discuss topics, address everyday queries, or brainstorm creative ideas. I do my best to help using my 'knowledge brain' — I hope to be your go-to partner for exploring and learning!","1. What are you?\n2. What can you do?\n3. What kinds of questions can you answer?\n4. What kind of partner do you want to be?\n5. How do you provide help?" +"What are you?","I'm an AI assistant, always ready to chat with users and answer their questions. I can participate in knowledge discussions, address everyday queries, and brainstorm creative ideas, providing help and companionship through my 'knowledge brain'. I hope to be a great partner for interaction and exploration.","What are you?" +"What can you do?","I can chat with users, answer questions, participate in knowledge discussions, address everyday queries, and brainstorm creative ideas, providing help and companionship through my 'knowledge brain'.","What can you do?" +``` + +## Usage Instructions + +### 1. Open the Knowledge Base, Click Import, and Select Template Import + +![](/imgs/template/import.png) + +![](/imgs/template/box.png) + +### 2. Download the Template + +Click to download the CSV template. It contains two content modes: + +#### Standard Mode Template + +![](/imgs/template/nomal.png) + +Corresponding CSV format: + +![](/imgs/template/nomal_data.png) + +In standard mode, q is the content, a is empty, and indexes can have multiple entries. + +#### Q&A Pair Mode Template + +![](/imgs/template/Question-answer.png) + +Corresponding CSV format: + +![](/imgs/template/Question-answer_data.png) + +In Q&A pair mode, q is the question, a is the answer, and indexes are the index entries. + +### 3. Fill in Your Data + +Fill in your Q&A data following the template format: +- Each row represents one content entry or one Q&A pair +- The question (q) must never be empty +- Within a row, you can add more index entries by extending columns to the right + +### 4. Import Limits + +- Only CSV format files are supported +- Maximum file size is 100MB +- Data must strictly follow the template format, otherwise import may fail +- Only one file can be imported at a time + +After a successful import: + +![](/imgs/template/import_csv.png) + +### 4. Important Notes + +- Ensure the CSV file uses UTF-8 encoding +- If content contains commas, wrap the entire value in double quotes +- The indexes column is used as search indexes for related questions, helping improve retrieval accuracy +- We recommend testing with a small dataset before importing large amounts of data + +## Best Practices + +1. **Data Preparation** + - Ensure content or Q&A pair quality — answers should be clear and accurate + - Add appropriate index keywords for each import entry + - Avoid duplicate content or Q&A pairs + +2. **Format Check** + - Verify the CSV file format before importing + - Ensure there are no extra blank lines or spaces + - Verify that special characters are properly escaped + +3. **Batch Import** + - For large datasets, import in batches + - Verify data correctness after each batch + +## FAQ + +Q: Why did my file import fail? +A: Check the following: +- Is the file format CSV? +- Is the encoding UTF-8? +- Does the data strictly follow the template format? +- Does the file exceed the size limit? + +Q: How do I verify a successful import? +A: After a successful import, you can: +- Search for imported questions in the knowledge base +- Test answer accuracy through conversations +- Check the knowledge base data statistics diff --git a/document/content/docs/introduction/guide/knowledge_base/third_dataset.en.mdx b/document/content/docs/introduction/guide/knowledge_base/third_dataset.en.mdx new file mode 100644 index 0000000000..5fc2f59409 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/third_dataset.en.mdx @@ -0,0 +1,167 @@ +--- +title: Third-Party Knowledge Base Development +description: How to integrate a third-party knowledge base with FastGPT +--- + +import { Alert } from '@/components/docs/Alert'; + +There are many document libraries available online, such as Lark, Yuque, and others. Different FastGPT users may use different document libraries. FastGPT has built-in support for Lark and Yuque, but if you need to integrate other document libraries, follow this guide. + + +## Unified API Specification + +To provide a unified interface for different document libraries, FastGPT defines a standard API specification with 4 endpoints. See the [API File Library endpoints](/docs/introduction/guide/knowledge_base/api_dataset). + +All built-in document libraries are extensions of the standard API File Library. Refer to the code in `FastGPT/packages/service/core/dataset/apiDataset/yuqueDataset/api.ts` to build extensions for other document libraries. You need to implement 4 endpoints: + +1. Get file list +2. Get file content / file link +3. Get original file preview URL +4. Get file detail information + +## Building a Third-Party File Library + +For this walkthrough, we'll use adding a Lark Knowledge Dataset (FeishuKnowledgeDataset) as an example. + +### 1. Add Third-Party Document Library Parameters + +First, go to `FastGPT\packages\global\core\dataset\apiDataset.d.ts` in the FastGPT project and add the third-party document library server type. Design the fields based on your needs. For example, the Yuque knowledge base requires `userId` and `token` for authentication. + +```ts +export type YuqueServer = { + userId: string; + token?: string; + basePath?: string; +}; +``` + + + +If the document library supports a `root directory` selection feature, add a `basePath` field. [See the root directory feature](/docs/introduction/guide/knowledge_base/third_dataset/#adding-the-configuration-form) + + + +![](/imgs/thirddataset-1.png) + +### 2. Create the Hook File + +Each third-party document library uses a Hook pattern to maintain a set of API endpoints. The Hook contains 5 functions to implement. + +- Create a folder for your document library under `FastGPT\packages\service\core\dataset\apiDataset\`, then create an `api.ts` file inside it +- In `api.ts`, define the following 5 functions: + - `listFiles`: Get the file list + - `getFileContent`: Get file content / file link + - `getFileDetail`: Get file detail information + - `getFilePreviewUrl`: Get the original file preview URL + - `getFileId`: Get the original file's real ID + +### 3. Add the Knowledge Base Type + +In `FastGPT\packages\global\core\dataset\type.d.ts`, import your new knowledge base type. + +![](/imgs/thirddataset-2.png) + +### 4. Add Knowledge Base Data Retrieval + +In `FastGPT\packages\global\core\dataset\apiDataset\utils.ts`, add the following content. + +![](/imgs/thirddataset-3.png) + +### 5. Add Knowledge Base Invocation Method + +In `FastGPT\packages\service\core\dataset\apiDataset\index.ts`, add the following content. + +![](/imgs/thirddataset-4.png) + +## Adding the Frontend + +Add your i18n translations in `FastGPT\packages\web\i18n\zh-CN\dataset.json`, `FastGPT\packages\web\i18n\en\dataset.json`, and `FastGPT\packages\web\i18n\zh-Hant\dataset.json`. Using Chinese translations as an example, you'll generally need the following: + +![](/imgs/thirddataset-5.png) + +In `FastGPT\packages\service\support\user/audit\util.ts`, add the following to support i18n translation retrieval. + +![](/imgs/thirddataset-6.png) + + + +The i18n translation content is stored in `FastGPT\packages\web\i18n\zh-Hant\account_team.json`, `FastGPT\packages\web\i18n\zh-CN\account_team.json`, and `FastGPT\packages\web\i18n\en\account_team.json`. The field format is `dataset.XXX_dataset`. For example, for the Lark knowledge base, the field value is `dataset.feishu_knowledge_dataset`. + + + +Add your knowledge base icons under `FastGPT\packages\web\components\common\Icon\icons\core\dataset\`. You need two icons: `Outline` (monochrome) and `Color` (colored), as shown below. + +![](/imgs/thirddataset-7.png) + + +In `FastGPT\packages\web\components\common\Icon\constants.ts`, register your icons. The `import` path points to where the icons are stored. + +![](/imgs/thirddataset-8.png) + +In `FastGPT\packages\global\core\dataset\constants.ts`, add your knowledge base type to both `DatasetTypeEnum` and `ApiDatasetTypeMap`. + +| | | +| --- | --- | +| ![](/imgs/thirddataset-9.png) | ![](/imgs/thirddataset-10.png) | + + + +The `courseUrl` field links to the relevant documentation — add it if available. +Documentation goes in `FastGPT/document/content/docs/introduction/guide/dashboard/workflow/knowledge_base_search_merge.mdx`. +The `label` value is the knowledge base name you added via i18n translations. +`icon` and `avatar` are the two icons you added earlier. + + + +In `FastGPT\projects\app\src\pages\dataset\list\index.tsx`, add the following. This file handles the menu that appears when clicking the "New" button on the knowledge base list page. Your knowledge base must be added here to be creatable. + +![](/imgs/thirddataset-11.png) + +In `FastGPT\projects\app\src\pageComponents\dataset\detail\Info\index.tsx`, add the following. This configuration corresponds to the UI shown below. + +| | | +| --- | --- | +![](/imgs/thirddataset-12.png)|![](/imgs/thirddataset-13.png) + +## Adding the Configuration Form + +In `FastGPT\projects\app\src\pageComponents\dataset\ApiDatasetForm.tsx`, add the following. This file handles the field input form when creating a knowledge base. + +| | | | +| --- | --- | --- | +| ![](/imgs/thirddataset-14.png) | ![](/imgs/thirddataset-15.png) | ![](/imgs/thirddataset-16.png) | + +The two components added in the code render the root directory selector, corresponding to the `getFileDetail` API method. If your knowledge base doesn't support this, you can omit them. + +``` +{renderBaseUrlSelector()} // Renders the `Base URL` field +{renderDirectoryModal()} // The `Select Root Directory` modal that appears when clicking `Select` (see image) +``` + +| | | +| --- | --- | +| ![](/imgs/thirddataset-17.png) | ![](/imgs/thirddataset-18.png) | + +If the knowledge base needs root directory support, also add the following in the `ApiDatasetForm` file. + +### 1. Parse the Knowledge Base Type + +Parse your knowledge base type from `apiDatasetServer`, as shown: + +![](/imgs/thirddataset-19.png) + +### 2. Add Root Directory Selection Logic and `parentId` Assignment + +Add root directory selection logic to ensure the user has filled in all required fields for the API methods, such as the Token. + +![](/imgs/thirddataset-20.png) + +### 3. Add Field Validation and Assignment Logic + +Verify that all required fields are present before calling the API, and assign the root directory value to the corresponding field after selection. + +![](/imgs/thirddataset-21.png) + +## Tips + +After creating the knowledge base, we recommend running a full test of all knowledge base features to check for issues. If you encounter problems that aren't covered in this documentation, it's likely that some configuration was missed. Do a global search for `YuqueServer` and `yuqueServer` to verify that your type has been added everywhere it's needed. diff --git a/document/content/docs/introduction/guide/knowledge_base/websync.en.mdx b/document/content/docs/introduction/guide/knowledge_base/websync.en.mdx new file mode 100644 index 0000000000..4fff674e79 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/websync.en.mdx @@ -0,0 +1,77 @@ +--- +title: Web Site Sync +description: Introduction and usage of the FastGPT Web Site Sync feature +--- + +![](/imgs/webSync1.jpg) + +This feature is currently only available to commercial edition users. + +## What is Web Site Sync + +Web Site Sync uses crawler technology to automatically discover all pages under the `same domain` from an entry URL, supporting up to `200` sub-pages. For compliance and security reasons, FastGPT only supports crawling `static sites`, primarily intended for quickly building knowledge bases from documentation sites. + +Tip: Most China-based media sites are not supported, including WeChat Official Accounts, CSDN, Zhihu, etc. You can verify whether a site is static by sending a `curl` request from the terminal: + +```bash +curl https://doc.fastgpt.io/docs/intro/ +``` + +## How to Use + +### 1. Create a New Knowledge Base and Select Web Site Sync + +![](/imgs/webSync2.jpg) + +![](/imgs/webSync3.jpg) + +### 2. Click to Configure Site Information + +![](/imgs/webSync4.jpg) + +### 3. Enter the URL and Selector + +![](/imgs/webSync5.jpg) + +![](/imgs/webSync5-1.jpg) + +Click Start Sync and wait for the system to automatically crawl the site content. + +## Create an App and Bind the Knowledge Base + +![](/imgs/webSync6.jpg) + +## How to Use Selectors + +Selectors are based on HTML/CSS/JS. You can use selectors to target specific content to crawl rather than the entire site. Here's how: + +### Open the Browser DevTools (usually F12, or Right-click > Inspect) + +![](/imgs/webSync7.webp) + +![](/imgs/webSync8.webp) + +### Enter the Element Selector + +For a CSS selectors reference, see the [MDN CSS Selectors guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors). + +In the image above, we selected an area corresponding to a `div` tag with three attributes: `data-prismjs-copy`, `data-prismjs-copy-success`, and `data-prismjs-copy-error`. We only need one, so the selector is: +**`div[data-prismjs-copy]`** + +Besides attribute selectors, class and ID selectors are also common. For example: + +![](/imgs/webSync9.webp) + +The `class` in the image contains class names (there may be multiple separated by spaces — just pick one). The selector would be: **`.docs-content`** + +### Using Multiple Selectors + +In the earlier demo, we used multiple selectors for the FastGPT documentation site, separated by commas. + +![](/imgs/webSync10.webp) + +We want to select content from the two tags shown above, which requires two selectors. The first is: `.docs-content .mb-0.d-flex`, meaning child elements under the `docs-content` class that have both the `mb-0` and `d-flex` classes. + +The second is `.docs-content div[data-prismjs-copy]`, meaning `div` elements under the `docs-content` class that have the `data-prismjs-copy` attribute. + +Separate the two selectors with a comma: `.docs-content .mb-0.d-flex, .docs-content div[data-prismjs-copy]` diff --git a/document/content/docs/introduction/guide/knowledge_base/yuque_dataset.en.mdx b/document/content/docs/introduction/guide/knowledge_base/yuque_dataset.en.mdx new file mode 100644 index 0000000000..8731b241d6 --- /dev/null +++ b/document/content/docs/introduction/guide/knowledge_base/yuque_dataset.en.mdx @@ -0,0 +1,46 @@ +--- +title: Yuque File Library +description: Introduction and usage of the FastGPT Yuque File Library +--- + +| | | +| --- | --- | +| ![alt text](/imgs/image-31.png) | ![alt text](/imgs/image-32.png) | + +Starting from FastGPT v4.8.16, commercial edition users can import from Yuque file libraries by configuring a Yuque token and uid. This feature is currently in beta — some interactions may still need refinement. + +## 1. Get the Yuque Token and UID + +Go to the Yuque homepage > click your avatar > Settings to find the relevant parameters. + +![alt text](/imgs/image-36.png) + +Follow the images below to get the Token and User ID. Make sure to assign the appropriate permissions to the Token: + +**Personal Edition**: + +| Get Token | Add Permissions | Get User ID | +| --- | --- | --- | +| ![alt text](/imgs/image-33.png) | ![alt text](/imgs/image-34.png) | ![alt text](/imgs/image-35.png) | + +**Enterprise Edition**: + +| Get Token | Get User ID | +| --- | --- | +| ![alt text](/imgs/image-109.png) | ![alt text](/imgs/image-108.png) | + +## 2. Create the Knowledge Base + +Using the token and uid from the previous step, create a knowledge base. Select the Yuque file library type, fill in the parameters, and click Create. + +![alt text](/imgs/image-37.png) + +![alt text](/imgs/image-31.png) + +## 3. Import Documents + +After creating the knowledge base, click `Add File` to import from your Yuque document library and follow the on-screen guidance. + +The Yuque knowledge base supports scheduled sync — it scans once daily at varying times. If documents have been updated, they will be synced automatically. You can also trigger a manual sync. + +![alt text](/imgs/image-38.png) diff --git a/document/content/docs/introduction/guide/meta.en.json b/document/content/docs/introduction/guide/meta.en.json new file mode 100644 index 0000000000..f466c10e22 --- /dev/null +++ b/document/content/docs/introduction/guide/meta.en.json @@ -0,0 +1,13 @@ +{ + "title": "Features", + "description": "FastGPT features", + "pages": [ + "course", + "dashboard", + "plugins", + "knowledge_base", + "team_permissions", + "DialogBoxes", + "admin" + ] +} diff --git a/document/content/docs/introduction/guide/plugins/bing_search_plugin.en.mdx b/document/content/docs/introduction/guide/plugins/bing_search_plugin.en.mdx new file mode 100644 index 0000000000..e01de90093 --- /dev/null +++ b/document/content/docs/introduction/guide/plugins/bing_search_plugin.en.mdx @@ -0,0 +1,28 @@ +--- +title: Bing Search Plugin Configuration Guide +description: Step-by-step guide for configuring the FastGPT Bing Search plugin +--- + +1. # Open the Microsoft Azure Portal and Log In + +https://portal.azure.com/ + +![](/imgs/bing_search_plugin1.png) + +2. # Create a Bing Web Search Resource + +Search for Bing Search v7 and click Create. + +https://portal.azure.com/#create/Microsoft.BingSearch + +![](/imgs/bing_search_plugin2.png) + +3. # Go to the Resource Details and Click Manage Keys + +![](/imgs/bing_search_plugin3.png) + +# 4. Copy Either Key and Paste It into the Plugin Input + +![](/imgs/bing_search_plugin4.png) + +![](/imgs/bing_search_plugin5.png) diff --git a/document/content/docs/introduction/guide/plugins/dev_system_tool.en.mdx b/document/content/docs/introduction/guide/plugins/dev_system_tool.en.mdx new file mode 100644 index 0000000000..d374644efd --- /dev/null +++ b/document/content/docs/introduction/guide/plugins/dev_system_tool.en.mdx @@ -0,0 +1,353 @@ +--- +title: How to Develop System Plugins +description: FastGPT system plugin development guide (Tools) +--- + +## Introduction + +Starting from version 4.10.0, the FastGPT system plugin project moved to the standalone `fastgpt-plugin` repository, using a pure code approach for tool development. +After the plugin marketplace update in version 4.14.0, the system tool development process changed — please follow the latest documentation when contributing code. + +You can develop and debug plugins independently in the `fastgpt-plugin` project, then submit a PR directly to FastGPT without needing to run the main FastGPT service. + +Currently, system plugins only support the "Tool" type. + +## Concepts + +- Tool: The smallest execution unit. Each tool has a unique ID with specific inputs and outputs. +- Toolset: A collection of tools that can contain multiple tools. + +In `fastgpt-plugin`, you can create one tool or toolset at a time. Each submission accepts only one tool/toolset. To develop multiple, create separate PRs. + +## 1. Prepare the Development Environment + +### 1.1 Install Bun + +- Install [Bun](https://bun.sh/). FastGPT-plugin uses Bun as its package manager. + +### 1.2 Fork the FastGPT-plugin Repository + +Fork the repository at `https://github.com/labring/fastgpt-plugin` + +### 1.3 Set Up the Development Scaffold + + + +Note: Due to Bun-specific APIs, you must use bunx for installation. Using npx or pnpm will cause errors. + +Create a new directory and run: +```bash +bunx @fastgpt-sdk/plugin-cli +``` + +This creates a fastgpt-plugin directory and adds two remotes: +- upstream pointing to the official repository +- origin pointing to your fork + +Uses sparse-checkout by default to avoid pulling all official plugin code. + + + +- Initialize a `git` repository in a new local directory: + +```bash +git init +``` + +If you have a Git SSH key configured: +```bash +git remote add origin git@github.com:[your-name]/fastgpt-plugin.git +git remote add upstream git@github.com:labring/fastgpt-plugin.git +``` + +Otherwise use HTTPS: +```bash +git remote add origin https://github.com/[your-name]/fastgpt-plugin.git +git remote add upstream https://github.com/labring/fastgpt-plugin.git +``` + +- (Optional) Use sparse-checkout to avoid pulling all plugin code. Without this, all official plugins will be pulled: +```bash +git sparse-checkout init --no-cone +git sparse-checkout add "/*" "!/modules/tool/packages/*" +git pull +``` + +Create a new tool: +```bash +bun i +bun run new:tool +``` + + + + +## 2. Write Tool Code + +### 2.1 Tool Code Structure + +Follow the prompts to choose between creating a tool or toolset, and enter a directory name (use camelCase). + +System tool file structure: + +```plaintext +src // Source code and processing logic +└── index.ts +test // Test cases +└── index.test.ts +config.ts // Configuration: tool name, description, type, icon, etc. +index.ts // Entry point — do not modify this file +logo.svg // Logo — replace with your tool's logo +README.md // (Optional) README with usage instructions and examples +assets/ // (Optional) Resource files such as images, audio, etc. +package.json // npm package +``` + +Toolset file structure: + +```plaintext +children +└── tool // Same structure as a tool above, but without README and assets +config.ts +index.ts +logo.svg +README.md +assets/ +package.json +``` + +### 2.2 Modify config.ts + +- **name** and **description** fields support both Chinese and English +- **courseUrl** (optional) — Link for obtaining keys, official website, tutorial, etc. If you provide a README.md, you can include it there instead +- **author** — Developer name +- **tags** — Default tags for the tool. Available tags (enum): + - tools: Tools + - search: Search + - multimodal: Multimodal + - communication: Communication + - finance: Finance + - design: Design + - productivity: Productivity + - news: News + - entertainment: Entertainment + - social: Social + - scientific: Scientific + - other: Other +- **secretInputList** — Secret input list for configuring tool `activation information`, typically including `keys`, `Endpoint`, `Port`, etc. (see secretInputList format below) +- **versionList** (configured per tool) — For version management. Each element has: + - value: Version number (semver recommended) + - description: Description + - inputs: Input parameters (see inputs format below) + - outputs: Return values (see outputs format below) + +For tools within a Toolset, `type`, `courseUrl`, and `author` are inherited from the Toolset configuration and don't need to be specified. + +#### secretInputList Format + +General format: +```ts +{ + key: 'key', // Unique key + label: 'Frontend display label', + description: 'Frontend display description', // Optional + inputType: 'input' | 'secret' | 'switch' | 'select' | 'numberInput', // Frontend input type + // secret: Encrypted input — the value is symmetrically encrypted when saved + // switch: Toggle switch + // select: Dropdown select + // numberInput: Number input + // input: Plain text input +} +``` + +Here's an example from the dalle3 configuration. See [dalle3's config.ts](https://github.com/labring/fastgpt-plugin/blob/main/modules/tool/packages/dalle3/config.ts) for the full file. + +```ts +{ + // Other configuration + secretInputConfig: [ + { + key: 'url', + label: 'Dalle3 API Base URL', + description: 'e.g., https://api.openai.com', + inputType: 'input', + required: true + }, + { + key: 'authorization', + label: 'API Credential (without Bearer prefix)', + description: 'sk-xxxx', + required: true, + inputType: 'secret' + } + ] +} +``` + +#### inputs Format + +General format: + +```ts +{ + key: 'Unique key within this tool, matching the InputType definition in src/index.ts', + label: 'Frontend display label', + renderTypeList: [FlowNodeInputTypeEnum.input, FlowNodeInputTypeEnum.reference], // Frontend input type + valueType: WorkflowIOValueTypeEnum.string, // Data type + toolDescription: 'Description used during tool invocation' // Required if this is a tool call parameter +} +``` + +dalle3 inputs example: +```ts +{ +//... + versionList: [ + { + // Other configuration + inputs: [ + { + key: 'prompt', + label: 'Drawing Prompt', + valueType: WorkflowIOValueTypeEnum.string, + renderTypeList: [FlowNodeInputTypeEnum.reference, FlowNodeInputTypeEnum.input], + toolDescription: 'Drawing prompt' + } + ], + } + // ... + ] +} +``` + +#### outputs Format +```ts +{ + key: 'link', // Unique key + valueType: WorkflowIOValueTypeEnum.string, // See the Enum type definition for options + label: 'Image Access Link', // Display name + description: 'Image access link' // Description (optional) +} +``` + +dalle3 outputs example: + +```ts +{ + // ... + versionList: [ + { + // ... + outputs: [ + { + valueType: WorkflowIOValueTypeEnum.string, + key: 'link', + label: 'Image Access Link', + description: 'Image access link' + }, + { + type: FlowNodeOutputTypeEnum.error, + valueType: WorkflowIOValueTypeEnum.string, + key: 'system_error', + label: 'Error Message' + } + ] + } + ], +} +``` + +### 2.3 Write the Processing Logic + +Write your processing logic in `[your-tool-name]/src/index.ts` as the entry point. Key requirements: + +1. Use zod for type definitions, exported as `InputType` and `OutputType` schemas. +2. The entry function must be named `tool`. You can define additional helper functions. + +```ts +import { format } from 'date-fns'; +import { z } from 'zod'; + +export const InputType = z.object({ + formatStr: z.string().optional() +}); + +export const OutputType = z.object({ + time: z.string() +}); + +export async function tool(props: z.infer): Promise> { + const formatStr = props.formatStr || 'yyyy-MM-dd HH:mm:ss'; + + return { + time: format(new Date(), formatStr) + }; +} +``` + +The example above takes a `formatStr` (format string) and returns the current time. To install packages, run `bun install PACKAGE` from the `/modules/tools/packages/[your-tool-name]` directory. + +## 4. Build / Package + +Starting from FastGPT v4.14.0, system plugins are packaged as `.pkg` files. Run: +```bash +bun run build:pkg +``` +This builds and packages all local plugins as `.pkg` files in the `dist/pkgs` directory. + +## 5. Unit Testing + +FastGPT-plugin uses Vitest as its testing framework. + +### 5.1 Write Test Cases + +Write test cases in `test/index.test.ts`. Run them with `bun run test index.test.ts `. + +> Note: Never include secret keys in test cases. +> +> When using AI agent tools to write test cases, the agent may modify your processing logic or even the testing framework itself. + +### 5.2 View Test Coverage + +Open `coverage/index.html` in a browser to view coverage for each plugin module. + +To submit plugins to the official repository, you must write unit tests that achieve: +- 90%+ code coverage +- 100% function coverage +- 100% branch condition coverage + +## 6. E2E (End-to-End) Testing + +Simple tools may not need E2E testing. For complex tools, the review team may require it. + +### 6.1 Deploy the E2E Test Environment + +1. Follow [Quick Start Local Development](/docs/introduction/development/intro) to set up a local FastGPT development environment +2. Run `cd runtime && cp .env.template .env.local` to copy the environment variable template, then connect to the Minio, Mongo, and Redis instances from step 1 +3. Run `bun run dev` to start the development environment, then update FastGPT's environment variables to connect to your fastgpt-plugin instance + +### 6.2 Test via Scalar + +Start the fastgpt-plugin development environment. + +Open `http://localhost:PORT/openapi` in a browser to access the `fastgpt-plugin` OpenAPI page for API debugging. Replace PORT with your fastgpt-plugin port number. + +![](/imgs/plugin-openapi.png) + +First, use the `/tool/list` endpoint to get the tool list and find the `toolId` of the tool you want to debug. Then use `/tool/runStream` to run the tool and get results. + +![](/imgs/plugin-openapi2.png) + +### 6.3 E2E Testing in Dev Mode (with Hot Reload) + +By default, fastgpt-plugin automatically loads all tools under `modules/tool/packages/` and watches for file changes with hot reload. You can use these tools directly in FastGPT. + +### 6.4 Upload Tools for E2E Testing in Dev Mode (without Hot Reload) + +Set the FastGPT-plugin environment variable `DISABLE_DEV_TOOLS=true` to disable automatic loading of development tools, allowing you to test tool uploads instead. + +## 7. Submit Your Tool to the Official Repository + +After completing all the steps above, submit a PR to the official repository at `https://github.com/labring/fastgpt-plugin`. Once reviewed and approved, your tool will be included as an official FastGPT plugin. + +If you don't need official inclusion, refer to [Upload System Tool](upload_system_tool) to use it in your own FastGPT deployment. diff --git a/document/content/docs/introduction/guide/plugins/doc2x_plugin_guide.en.mdx b/document/content/docs/introduction/guide/plugins/doc2x_plugin_guide.en.mdx new file mode 100644 index 0000000000..e71f72c566 --- /dev/null +++ b/document/content/docs/introduction/guide/plugins/doc2x_plugin_guide.en.mdx @@ -0,0 +1,22 @@ +--- +title: Doc2x Plugin Configuration Guide +description: How to configure and use the Doc2x plugin +--- + +1. # Open the Doc2x Website, Create an Account, and Copy the API Key + +https://doc2x.noedgeai.com/ + +![](/imgs/doc2x_plugin1.png) + +![](/imgs/doc2x_plugin2.png) + +2. # Enter the API Key in FastGPT + +**In Workflow mode:** + +![](/imgs/doc2x_plugin3.png) + +**In Simple mode:** + +![](/imgs/doc2x_plugin4.png) diff --git a/document/content/docs/introduction/guide/plugins/google_search_plugin_guide.en.mdx b/document/content/docs/introduction/guide/plugins/google_search_plugin_guide.en.mdx new file mode 100644 index 0000000000..03ba744ef7 --- /dev/null +++ b/document/content/docs/introduction/guide/plugins/google_search_plugin_guide.en.mdx @@ -0,0 +1,28 @@ +--- +title: Google Search Plugin Configuration Guide +description: FastGPT Google Search Plugin Configuration Guide +--- + +## 1. Create a Google Custom Search Engine + +https://programmablesearchengine.google.com/ + +Go to the Custom Search Engine control panel and create a new Search Engine. + +![](/imgs/google_search_plugin1.png) + +Get the Search Engine ID (cx). + +![](/imgs/google_search_plugin2.png) + +## 2. Get an API Key + +https://developers.google.com/custom-search/v1/overview + +![](/imgs/google_search_plugin3.png) + +## 3. Fill in the Plugin Input Parameters + +Enter the Search Engine ID in the cx field and the API key in the key field. + +![](/imgs/google_search_plugin4.png) diff --git a/document/content/docs/introduction/guide/plugins/meta.en.json b/document/content/docs/introduction/guide/plugins/meta.en.json new file mode 100644 index 0000000000..72071b27dc --- /dev/null +++ b/document/content/docs/introduction/guide/plugins/meta.en.json @@ -0,0 +1,14 @@ +{ + "title": "System Plugins", + "description": "Introduction to using and submitting system plugins, and filling instructions for each plugin", + "pages": [ + "dev_system_tool", + "how_to_submit_system_plugin", + "upload_system_tool", + "searxng_plugin_guide", + "google_search_plugin_guide", + "bing_search_plugin", + "doc2x_plugin_guide", + "deepseek_plugin_guide" + ] +} diff --git a/document/content/docs/introduction/guide/plugins/searxng_plugin_guide.en.mdx b/document/content/docs/introduction/guide/plugins/searxng_plugin_guide.en.mdx new file mode 100644 index 0000000000..8dc191fc87 --- /dev/null +++ b/document/content/docs/introduction/guide/plugins/searxng_plugin_guide.en.mdx @@ -0,0 +1,186 @@ +--- +title: SearXNG Search Plugin Configuration Guide +description: FastGPT SearXNG Search Plugin Configuration Guide +--- + +[SearXNG](https://github.com/searxng/searxng) is a free internet metasearch engine that aggregates results from various search services and databases. It does not track or profile users. You can self-host it for your own use. This guide covers deploying SearXNG and integrating it with FastGPT. + +## 1. Deploy the Application + +This section covers deploying SearXNG on Sealos. For Docker deployment, refer to the [official SearXNG documentation](https://github.com/searxng/searxng). + +Open [Sealos Beijing Region](https://bja.sealos.run?uid=fnWRt09fZP), click App Launchpad, and create a new app: + +| Open App Launchpad | Create New App | +| --- | --- | +| ![](/imgs/searxng_plugin_guide1.png) | ![alt text](/imgs/image-45.png) | + +## 2. Deployment Configuration + +Fill in the following parameters: + +* Image: searxng/searxng:latest +* CPU: 0.2 +* Memory: 512M +* Container Port: 8080 +* Enable public access +* Click Advanced Configuration to add environment variables and config files + +![alt text](/imgs/image-50.png) + +**Environment Variables** + +Add these two variables to reduce concurrency and memory usage: + +``` +UWSGI_WORKERS=4 +UWSGI_THREADS=4 +``` + +**Configuration File** + +Add a new config file with filename: `/etc/searx/settings.yml` + +File content: + +```txt +general: + debug: false + instance_name: "searxng" + privacypolicy_url: false + donation_url: false + contact_url: false + enable_metrics: true + open_metrics: '' + +brand: + new_issue_url: https://github.com/searxng/searxng/issues/new + docs_url: https://docs.searxng.org/ + public_instances: https://searx.space + wiki_url: https://github.com/searxng/searxng/wiki + issue_url: https://github.com/searxng/searxng/issues + +search: + safe_search: 0 + autocomplete: "" + autocomplete_min: 4 + default_lang: "auto" + ban_time_on_fail: 5 + max_ban_time_on_fail: 120 + formats: + - html + +server: + port: 8080 + bind_address: "0.0.0.0" + base_url: false + limiter: false + public_instance: false + secret_key: "example" + image_proxy: false + http_protocol_version: "1.0" + method: "POST" + default_http_headers: + X-Content-Type-Options: nosniff + X-Download-Options: noopen + X-Robots-Tag: noindex, nofollow + Referrer-Policy: no-referrer + +redis: + url: false + +ui: + static_path: "" + static_use_hash: false + templates_path: "" + default_theme: simple + default_locale: "" + query_in_title: false + infinite_scroll: false + center_alignment: false + theme_args: + simple_style: auto + +outgoing: + request_timeout: 30.0 + max_request_timeout: 40.0 + pool_connections: 200 + pool_maxsize: 50 + enable_http2: false + retries: 5 + +engines: + + - name: bing + engine: bing + shortcut: bi + +doi_resolvers: + oadoi.org: 'https://oadoi.org/' + doi.org: 'https://doi.org/' + doai.io: 'https://dissem.in/' + sci-hub.se: 'https://sci-hub.se/' + sci-hub.st: 'https://sci-hub.st/' + sci-hub.ru: 'https://sci-hub.ru/' + +default_doi_resolver: 'oadoi.org' +``` + +Currently, only Bing works reliably in mainland China, so the config above only includes Bing. For overseas deployment, use [Sealos Singapore Region](https://cloud.sealos.io?uid=fnWRt09fZP) and add other search engines. Refer to the [SearXNG default config](https://github.com/searxng/searxng/blob/master/searx/settings.yml) for engine configurations. For example: + +``` + - name: duckduckgo + engine: duckduckgo + shortcut: ddg + + - name: google + engine: google + shortcut: go +``` + +## 3. Using with FastGPT + +Copy the public URL from your Sealos deployment and paste it into the SearXNG plugin URL field in FastGPT. + +| Copy Public URL | Paste into URL | +| --- | --- | +| ![alt text](/imgs/image-48.png) | ![alt text](/imgs/image-49.png) | + +## Response Format + +* Success returns an array of search results: + +```bash +{ + "result": "[{\"title\":\"Title1\",\"link\":\"Link1\",\"snippet\":\"Snippet1\"}, ...]" +} +``` + +* Empty results return a friendly message: + +```bash +{ + "result": "[]", + "error": { + "message": "No search results", + "code": 500 + } +} +``` + +* Failures may return these error messages via Promise.reject: + +```bash +- "Missing query parameter" +- "Missing url" +- "Failed to fetch data from Search XNG" +``` + +Issues typically stem from missing parameters or deployment problems. For more help, ask in the user community. + +## FAQ + +### No Search Results + +1. First, open the public URL directly and test if search works. +2. Check for timed-out search engines -- API calls won't return results if engines time out. diff --git a/document/content/docs/introduction/guide/plugins/upload_system_tool.en.mdx b/document/content/docs/introduction/guide/plugins/upload_system_tool.en.mdx new file mode 100644 index 0000000000..66f517e9ce --- /dev/null +++ b/document/content/docs/introduction/guide/plugins/upload_system_tool.en.mdx @@ -0,0 +1,59 @@ +--- +title: Upload System Tools Online +description: FastGPT System Tool Online Upload Guide +--- + +> Starting from FastGPT 4.14.0, system admins can upload and update system tools directly through the web interface for hot reloading. + +## Permission Requirements + +⚠️ **Important**: Only **root users** can use the online system tool upload feature. + +- Make sure you are logged in with the `root` account + +## Supported File Formats + +- **File type**: `.pkg` files +- **File size**: Maximum 100 MB +- **File count**: Up to 15 files per upload + +## Upload Steps + +### 1. Access the Configuration Page + + +![](/imgs/plugins/entry.png) + +### 2. Prepare Tool Files + +Before uploading, make sure your `.pkg` files are from the `dist/pkgs` folder, built by running `bun run build:pkg` in the fastgpt-plugin project. + +![](/imgs/plugins/files.png) + +### 3. Upload + +1. Click the **"Import/Update"** button +2. In the dialog that appears, click the file selection area +3. Select your prepared `.pkg` tool files +4. After confirming the file details, click **"Confirm Import"** + +### 4. Upload Process + +- A success message will appear after the upload completes +- The page auto-refreshes and the new tools will appear in the tool list + +## Features + +### Tool Management + +- **View tools**: All users can view installed system tools +- **Upload tools**: Only root users can upload new tools or update existing ones +- **Delete tools**: Only root users can delete uploaded tools + +## FAQ + +### Q: Can't see the "Import/Update" button + +**Reason:** The current user is not a root user + +**Solution:** Log in again with the root account diff --git a/document/content/docs/introduction/guide/team_permissions/customDomain.en.mdx b/document/content/docs/introduction/guide/team_permissions/customDomain.en.mdx new file mode 100644 index 0000000000..2f535b0520 --- /dev/null +++ b/document/content/docs/introduction/guide/team_permissions/customDomain.en.mdx @@ -0,0 +1,42 @@ +--- +title: Configure Custom Domain +description: How to configure a custom domain in FastGPT +--- + +FastGPT Cloud supports custom domain configuration starting from v4.14.4. + +## How to Configure a Custom Domain + +### 1. Open the "Custom Domain" Page + +In the sidebar, go to "Account" -> "Custom Domain" to open the configuration page. + +If your plan does not support this feature, follow the on-screen instructions to upgrade. + +![Open configuration page](/imgs/guide/team_permissions/customDomain/1.png) + +### 2. Add a Custom Domain + +1. Have your domain ready. Your domain must have an ICP filing. Currently supported filing providers are Alibaba Cloud, Tencent Cloud, and Volcano Engine. +2. Click the "Edit" button to enter edit mode. +3. Enter your domain, e.g. www.example.com +4. In your domain provider's DNS management console, add the CNAME record shown on the screen. +5. After adding the DNS record, click "Save". The system will automatically verify the DNS configuration -- this usually takes less than a minute. If verification takes too long, try again. +6. Once the status shows "Active", click "Confirm" to finish. + +![Configure custom domain](/imgs/guide/team_permissions/customDomain/2.png) + +You can now access FastGPT services and call FastGPT APIs using your own domain. + +## DNS Resolution Failure + +The system checks DNS resolution daily. If the DNS record becomes invalid, the custom domain will be disabled. You can re-verify it by clicking "Edit" on the "Custom Domain" management page. + +![Edit](/imgs/guide/team_permissions/customDomain/3.png) + +To change your custom domain or switch providers, delete the existing configuration and set it up again. + + +## Use Cases + +- [Integrate with WeCom Bot](/docs/use-cases/external-integration/wecom) diff --git a/document/content/docs/introduction/guide/team_permissions/invitation_link.en.mdx b/document/content/docs/introduction/guide/team_permissions/invitation_link.en.mdx new file mode 100644 index 0000000000..df7fa3cbfe --- /dev/null +++ b/document/content/docs/introduction/guide/team_permissions/invitation_link.en.mdx @@ -0,0 +1,62 @@ +--- +title: Invitation Links +description: How to use invitation links to invite team members +--- + +Starting from v4.9.1, team member invitations use the **invitation link** method, replacing the previous username-based approach. + +After upgrading, any pending invitations that haven't been accepted will be automatically cleared. Please use invitation links to re-invite members. + +## How to Use + +1. **On the team management page, admins can click the "Invite Members" button to open the invitation dialog** + +![](/imgs/guide/team_permissions/invitation_link/image1.png) + +2. **In the invitation dialog, click "Create Invitation Link" to generate a new link** + +![](/imgs/guide/team_permissions/invitation_link/image2.png) + +3. **Fill in the details** + +![](/imgs/guide/team_permissions/invitation_link/image3.png) + +Link description: We recommend describing the intended use case or purpose. The description cannot be changed after creation. + +Expiration: 30 minutes, 7 days, or 1 year + +Usage limit: 1 person or unlimited + +4. **Click "Copy Link" and send it to the people you want to invite** + +![](/imgs/guide/team_permissions/invitation_link/image4.png) + +5. **When a user visits the link, they will be redirected to the login page if not logged in or registered. After logging in, they will be taken to the team page to handle the invitation.** + +> Invitation links look like: fastgpt.cn/account/team?invitelinkid=xxxx + +![](/imgs/guide/team_permissions/invitation_link/image5.png) + +Click "Accept" to join the team. + +Click "Ignore" to close the dialog. The user can still accept the invitation by visiting the link again later. + +## Link Expiration and Auto-Cleanup + +### Why Links Expire + +Links are manually disabled by an admin. + +The invitation link reaches its expiration date and is automatically disabled. + +A single-use link (1 person limit) has already been used. + +Expired links cannot be accessed or re-enabled. + +### Link Limits + +Each user can have up to 10 **active** invitation links at a time. + +### Auto-Cleanup + +Expired links are automatically deleted after 30 days. diff --git a/document/content/docs/introduction/guide/team_permissions/meta.en.json b/document/content/docs/introduction/guide/team_permissions/meta.en.json new file mode 100644 index 0000000000..47824595dd --- /dev/null +++ b/document/content/docs/introduction/guide/team_permissions/meta.en.json @@ -0,0 +1,9 @@ +{ + "title": "Team & Permissions", + "description": "Team management, member groups, and permission settings to ensure data security and proper permission allocation in team collaboration.", + "pages": [ + "team_roles_permissions", + "invitation_link", + "customDomain" + ] +} diff --git a/document/content/docs/introduction/guide/team_permissions/team_roles_permissions.en.mdx b/document/content/docs/introduction/guide/team_permissions/team_roles_permissions.en.mdx new file mode 100644 index 0000000000..9e4953f39f --- /dev/null +++ b/document/content/docs/introduction/guide/team_permissions/team_roles_permissions.en.mdx @@ -0,0 +1,201 @@ +--- +title: Teams, Groups & Permissions +description: How to manage FastGPT teams, member groups, and permission settings +--- + +# Teams, Groups & Permissions + +## Permission System Overview + +FastGPT's permission system combines **attribute-based** and **role-based** access control, providing fine-grained permission management for team collaboration. Through **members, departments, and groups**, you can flexibly configure access to teams, apps, and knowledge bases. + +## Teams + +Each user can belong to multiple teams. The system automatically creates an initial team for every user. Manual creation of additional teams is not currently supported. + +## Permission Management + +FastGPT offers three permission management levels: + +**Member Permissions**: Highest priority, directly assigned to individuals + +**Department & Group Permissions**: Use union logic, lower priority than member permissions + +Permission evaluation follows this logic: + +First, check the user's individual member permissions + +Then, check permissions from the user's departments and groups (union) + +Final permissions are the combination of the above + +Authorization logic: + +![](/imgs/guide/team_permissions/team_roles_permissions/image1.jpeg) + +### Resource Permissions + +Different **resources** have different permissions. + +Resources refer to concepts like apps, knowledge bases, teams, etc. + +The table below shows the manageable permissions for different resources. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ResourceManageable PermissionsDescription
TeamCreate AppsCreate, delete, and other basic operations
Create Knowledge BasesCreate, delete, and other basic operations
Create Team APIKeyCreate, delete, and other basic operations
Manage MembersInvite/remove users, create groups, etc.
AppCan UseAllows conversation interaction
Can EditModify basic info, workflow orchestration, etc.
Can ManageAdd or remove collaborators
Knowledge BaseCan UseCan call this knowledge base in apps
Can EditModify knowledge base content
Can ManageAdd or remove collaborators
+ +### Collaborators + +You must add **collaborators** before managing their permissions: + +![](/imgs/guide/team_permissions/team_roles_permissions/image2.png) + +When managing team permissions, first select members/organizations/groups, then configure permissions. + +![](/imgs/guide/team_permissions/team_roles_permissions/image3.png) + +For resources like apps and knowledge bases, you can directly modify member permissions. + +![](/imgs/guide/team_permissions/team_roles_permissions/image4.png) + +Team permissions are set on a dedicated permissions page. + +![](/imgs/guide/team_permissions/team_roles_permissions/image5.png) + +## Special Permissions + +### Admin Permissions + +Admins primarily manage resource collaboration relationships, with these limitations: + +- Cannot modify or remove their own permissions +- Cannot modify or remove other admins' permissions +- Cannot grant admin permissions to other collaborators + +### Owner Permissions + +Each resource has a unique Owner with the highest permissions for that resource. Owners can transfer ownership, but will lose all permissions to the resource after transfer. + +### Root Permissions + +Root is the system's only super admin account, with complete access and management rights to all resources across all teams. + +## Tips + +### 1. Set Default Team Permissions + +Use the "All Members Group" to quickly set baseline permissions for the entire team. For example, grant everyone access to an app. + +**Note**: Individual member permissions override all-member group permissions. For example, if App A has all-member edit permissions, but User M is individually set to use-only, User M can only use the app, not edit it. + +### 2. Batch Permission Management + +Create groups or organizations to efficiently manage permissions for multiple users. Add users to a group, then grant permissions to the entire group. + +### Developer Reference +> The following content is for developers. Skip if you're not doing custom development. + +#### Permission Design Principles + +FastGPT's permission system is inspired by Linux permissions, using binary storage for permission bits. A permission bit of 1 means the permission is granted, 0 means no permission. Owner permissions are specially marked as all 1s. + +#### Permission Table + +Permission information is stored in MongoDB's resource_permissions collection, with these main fields: + +- teamId: Team identifier +- tmbId/groupId/orgId: Permission subject (one of three) +- resourceType: Resource type (team/app/dataset) +- permission: Permission value (number) +- resourceId: Resource ID (null for team resources) + +The system implements flexible and precise permission control through this data structure. + +The schema for this table is defined in packages/service/support/permission/schema.ts: + +```typescript +export const ResourcePermissionSchema = new Schema({ + teamId: { + type: Schema.Types.ObjectId, + ref: TeamCollectionName + }, + tmbId: { + type: Schema.Types.ObjectId, + ref: TeamMemberCollectionName + }, + groupId: { + type: Schema.Types.ObjectId, + ref: MemberGroupCollectionName + }, + orgId: { + type: Schema.Types.ObjectId, + ref: OrgCollectionName + }, + resourceType: { + type: String, + enum: Object.values(PerResourceTypeEnum), + required: true + }, + permission: { + type: Number, + required: true + }, + // Resrouce ID: App or DataSet or any other resource type. + // It is null if the resourceType is team. + resourceId: { + type: Schema.Types.ObjectId + } +}); +``` diff --git a/document/content/docs/introduction/index.en.mdx b/document/content/docs/introduction/index.en.mdx index b105a6195d..0d75b00e08 100644 --- a/document/content/docs/introduction/index.en.mdx +++ b/document/content/docs/introduction/index.en.mdx @@ -1,11 +1,11 @@ --- -title: Quick Introduction to FastGPT -description: FastGPT's Capabilities and Advantages +title: Getting Started with FastGPT +description: FastGPT capabilities and advantages --- import { Alert } from '@/components/docs/Alert'; -FastGPT is a knowledge base Q&A system based on LLM (Large Language Models), perfectly combining intelligent dialogue with visual orchestration to make AI application development simple and natural. Whether you are a developer or a business user, you can easily create your own AI applications. +FastGPT is a knowledge base Q&A system built on LLMs, combining intelligent conversation with visual orchestration to make AI application development simple and natural. Whether you're a developer or a business user, you can easily build your own AI applications. Quick Start @@ -17,37 +17,37 @@ Quick Start | --------------------- | --------------------------------- | | ![](/imgs/intro/image1.png) | ![](/imgs/intro/image2.png) | -# FastGPT's Advantages +# Why FastGPT ## 1. Simple and Flexible, Like Building Blocks 🧱 -As simple and fun as building with LEGO, FastGPT provides rich functional modules. You can build personalized AI applications through simple drag-and-drop, and implement complex business processes with zero code. -## 2. Make Data Smarter 🧠 -FastGPT provides a complete data intelligence solution, from data import, preprocessing to knowledge matching, and then to intelligent Q&A, with full-process automation. Combined with visual workflow design, you can easily create professional-grade AI applications. +Build AI applications as easily as snapping LEGO bricks together. FastGPT provides rich functional modules that let you create personalized AI apps through simple drag-and-drop — no coding required, even for complex business processes. +## 2. Make Your Data Smarter 🧠 +FastGPT provides a complete data intelligence solution — from data import and preprocessing to knowledge matching and intelligent Q&A — fully automated. Combined with visual workflow design, you can easily build professional-grade AI applications. ## 3. Open Source and Easy to Integrate 🔗 -FastGPT is open source under the Apache 2.0 license and supports secondary development. It can be quickly integrated through standard APIs without modifying the source code. It supports mainstream models such as ChatGPT, Claude, DeepSeek, and Wenxin Yiyan, with continuous iteration and optimization to maintain product vitality. +FastGPT is open source under the Apache 2.0 license and supports custom development. Integrate quickly through standard APIs without modifying source code. Supports mainstream models including ChatGPT, Claude, DeepSeek, and ERNIE Bot, with continuous iteration to keep the product evolving. --- # What Can FastGPT Do ## 1. Comprehensive Knowledge Base -You can easily import various documents and data, which will be automatically processed for knowledge structuring. It also features intelligent Q&A with multi-turn context understanding, providing users with a continuously optimized knowledge base management experience. +Import documents and data with automatic knowledge structuring. Features intelligent Q&A with multi-turn context understanding and a continuously improving knowledge base management experience. ![](/imgs/intro/image3.png) ## 2. Visual Workflow -FastGPT's intuitive drag-and-drop interface design allows you to build complex business processes with zero code. It has rich functional node components that can handle various business needs, with flexible process orchestration capabilities to customize business processes on demand. +FastGPT's intuitive drag-and-drop interface lets you build complex business processes with zero code. Rich functional node components handle diverse business needs with flexible process orchestration. ![](/imgs/intro/image4.png) ## 3. Intelligent Data Parsing -FastGPT's knowledge base system is extremely flexible in processing imported data. It can intelligently handle the complex structure of PDF documents, preserve images, tables, and LaTeX formulas, automatically recognize scanned files, and structure content into clear Markdown format. It also supports automatic image annotation and indexing, making visual content understandable and searchable, ensuring that knowledge is presented and applied completely and accurately in AI Q&A. +FastGPT's knowledge base system handles imported data with great flexibility — intelligently processing complex PDF structures while preserving images, tables, and LaTeX formulas. It automatically recognizes scanned files and structures content into clean Markdown format. It also supports automatic image annotation and indexing, making visual content searchable and ensuring knowledge is presented accurately in AI Q&A. ![](/imgs/intro/image5.png) ## 4. Workflow Orchestration -Based on Flow module workflow orchestration, you can design more complex Q&A processes. For example, querying databases, checking inventory, booking laboratories, etc. +Flow-based workflow orchestration lets you design complex Q&A processes — such as querying databases, checking inventory, or booking lab resources. ![](/imgs/intro/image6.png) ## 5. Powerful API Integration -FastGPT is fully aligned with OpenAI's official interface, supporting one-click integration with platforms such as Enterprise WeChat, Official Accounts, Feishu, and DingTalk, allowing AI capabilities to easily integrate into your business scenarios. +FastGPT is fully compatible with the OpenAI API interface, supporting one-click integration with WeCom, WeChat Official Account, Lark, DingTalk, and more — bringing AI capabilities into your business workflows. ![](/imgs/intro/image7.png) @@ -57,7 +57,7 @@ FastGPT is fully aligned with OpenAI's official interface, supporting one-click - Out-of-the-box knowledge base system - Visual low-code workflow orchestration -- Support for mainstream large models +- Support for mainstream LLMs - Simple and easy-to-use API interface - Flexible data processing capabilities @@ -69,9 +69,9 @@ FastGPT is fully aligned with OpenAI's official interface, supporting one-click --- -FastGPT is an open source project driven by users and contributors. If you have questions or suggestions about the product, you can seek support in the following ways. Our team and community will do our best to help you. +FastGPT is an open source project driven by users and contributors. If you have questions or suggestions, try the following support channels. Our team and community will do our best to help. -- 📱 Scan to join Feishu group 👇 +- 📱 Scan to join the Lark community group 👇 -- 🐞 Please submit any FastGPT bugs, issues, and requirements to [GitHub Issue](https://github.com/labring/fastgpt/issues/new/choose). +- 🐞 Submit any FastGPT bugs, issues, or feature requests to [GitHub Issues](https://github.com/labring/fastgpt/issues/new/choose). diff --git a/document/content/docs/introduction/meta.en.json b/document/content/docs/introduction/meta.en.json new file mode 100644 index 0000000000..57d1e6c2fb --- /dev/null +++ b/document/content/docs/introduction/meta.en.json @@ -0,0 +1,14 @@ +{ + "title": "Documentation", + "root": true, + "pages": [ + "---Getting Started---", + "index", + "cloud", + "commercial", + "development", + "---Features---", + "...guide" + ], + "order": 1 +} diff --git a/document/content/docs/openapi/app.en.mdx b/document/content/docs/openapi/app.en.mdx new file mode 100644 index 0000000000..99f6a51811 --- /dev/null +++ b/document/content/docs/openapi/app.en.mdx @@ -0,0 +1,195 @@ +--- +title: Application API +description: FastGPT OpenAPI Application Interface +--- + +## Prerequisites + +1. Prepare your API Key: You can use the global API Key directly +2. Get your application's AppId + +![alt text](/imgs/image-120.png) + + +## Log API + +### Get Cumulative Run Results + + + + + + ```bash + curl --location --request GET 'https://cloud.fastgpt.cn/api/proApi/core/app/logs/getTotalData?appId=68c46a70d950e8850ae564ba' \ +--header 'Authorization: Bearer apikey' + ``` + + + + + + ```bash + { + "code": 200, + "statusText": "", + "message": "", + "data": { + "totalUsers": 0, + "totalChats": 0, + "totalPoints": 0 + } + } + ``` + + + + + +
+ **Request Parameters:** + - appId: Application ID + + **Response Parameters:** + - totalUsers: Total number of users + - totalChats: Total number of conversations + - totalPoints: Total points consumed +
+ + + + + +### Get Application Log Dashboard + + + + + + ```bash +curl --location --request POST 'https://cloud.fastgpt.cn/api/proApi/core/app/logs/getChartData' \ +--header 'Authorization: Bearer apikey' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "appId": "68c46a70d950e8850ae564ba", + "dateStart": "2025-09-19T16:00:00.000Z", + "dateEnd": "2025-09-27T15:59:59.999Z", + "offset": 1, + "source": [ + "test", + "online", + "share", + "api", + "cronJob", + "team", + "feishu", + "official_account", + "wecom", + "mcp" + ], + "userTimespan": "day", + "chatTimespan": "day", + "appTimespan": "day" +}' + ``` + + + + + +```bash +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "userData": [ + { + "timestamp": 1758585600000, + "summary": { + "userCount": 1, + "newUserCount": 0, + "retentionUserCount": 0, + "points": 1.1132600000000001, + "sourceCountMap": { + "test": 1, + "online": 0, + "share": 0, + "api": 0, + "cronJob": 0, + "team": 0, + "feishu": 0, + "official_account": 0, + "wecom": 0, + "mcp": 0 + } + } + } + ], + "chatData": [ + { + "timestamp": 1758585600000, + "summary": { + "chatItemCount": 1, + "chatCount": 1, + "errorCount": 0, + "points": 1.1132600000000001 + } + } + ], + "appData": [ + { + "timestamp": 1758585600000, + "summary": { + "goodFeedBackCount": 0, + "badFeedBackCount": 0, + "chatCount": 1, + "totalResponseTime": 22.31 + } + } + ] + } +} +``` + + + + + +**Request Parameters:** +- appId: Application ID +- dateStart: Start time +- dateEnd: End time +- source: Log source +- offset: User retention offset +- userTimespan: User data timespan //day|week|month|quarter +- chatTimespan: Chat data timespan //day|week|month|quarter +- appTimespan: Application data timespan //day|week|month|quarter + +**Response Parameters:** + +- userData: User data array + - timestamp: Timestamp + - summary: Summary data object + - userCount: Active user count + - newUserCount: New user count + - retentionUserCount: Retained user count + - points: Total points consumed + - sourceCountMap: User count by source +- chatData: Chat data array + - timestamp: Timestamp + - summary: Summary data object + - chatItemCount: Chat message count + - chatCount: Session count + - errorCount: Error count + - points: Total points consumed +- appData: Application data array + - timestamp: Timestamp + - summary: Summary data object + - goodFeedBackCount: Positive feedback count + - badFeedBackCount: Negative feedback count + - chatCount: Chat count + - totalResponseTime: Total response time + + + + diff --git a/document/content/docs/openapi/chat.en.mdx b/document/content/docs/openapi/chat.en.mdx new file mode 100644 index 0000000000..2bee7f6f79 --- /dev/null +++ b/document/content/docs/openapi/chat.en.mdx @@ -0,0 +1,1246 @@ +--- +title: Chat API +description: FastGPT OpenAPI Chat Interface +--- + +# How to Get AppId + +You can find the AppId in your application details URL. + +![](/imgs/appid.png) + +# Start a Conversation + +- This API requires an application-specific API key, or it will return an error. +- Some packages require adding `v1` to the `BaseUrl`. If you get a 404 error, try adding `v1` and retry. + +{/* * 对话现在有`v1`和`v2`两个接口，可以按需使用，v2 自 4.9.4 版本新增，v1 接口同时不再维护 */} + +## Request Chat Agent and Workflow + +The `v1` chat API is compatible with the `GPT` interface! If you're using the standard `GPT` official API, you can access FastGPT by simply changing the `BaseUrl` and `Authorization`. However, note these rules: + +* Parameters like `model` and `temperature` are ignored. These values are determined by your workflow configuration. +* Won't return actual `Token` consumed. If needed, set `detail=true` and manually calculate `tokens` from `responseData`. + +### Request + + + + + + ```bash + curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \ + --header 'Authorization: Bearer fastgpt-xxxxxx' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "chatId": "my_chatId", + "stream": false, + "detail": false, + "responseChatItemId": "my_responseChatItemId", + "variables": { + "uid": "asdfadsfasfd2323", + "name": "张三" + }, + "messages": [ + { + "role": "user", + "content": "导演是谁" + } + ] + }' + ``` + + + + + + - Only `messages` differs slightly; other parameters are the same. + - Direct file uploads are not supported. Upload files to your object storage and provide the URL. + + ```bash + curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \ + --header 'Authorization: Bearer fastgpt-xxxxxx' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "chatId": "abcd", + "stream": false, + "messages": [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "导演是谁" + }, + { + "type": "image_url", + "image_url": { + "url": "图片链接" + } + }, + { + "type": "file_url", + "name": "文件名", + "url": "文档链接，支持 txt md html word pdf ppt csv excel" + } + ] + } + ] + }' + ``` + + + + + +
+- headers.Authorization: Bearer [apikey] +- chatId: string | undefined 。 + - 为时（不传入），不使用 FastGpt 提供的上下文功能，完全通过传入的 messages 构建上下文。 + - 为`非空字符串`时，意味着使用 chatId 进行对话，自动从 FastGpt 数据库取历史记录，并使用 messages数组最后一个内容作为用户问题，其余 message 会被忽略。请自行确保 chatId唯一，长度小于250，通常可以是自己系统的对话框ID。 +- messages: 结构与[GPT接口](https://platform.openai.com/docs/api-reference/chat/object) chat模式一致。 +- responseChatItemId: string | undefined 。如果传入，则会将该值作为本次对话的响应消息的 ID，FastGPT会自动将该 ID 存入数据库。请确保，在当前`chatId`下，`responseChatItemId`是唯一的。 +- detail:是否返回中间值（模块状态，响应的完整结果等），`stream模式`下会通过`event`进行区分，`非stream模式`结果保存在`responseData`中。 +- variables: 模块变量，一个对象，会替换模块中，输入框内容里的`[key]` +
+ + + + +### Response + + + + +```json +{ + "id": "adsfasf", + "model": "", + "usage": { + "prompt_tokens": 1, + "completion_tokens": 1, + "total_tokens": 1 + }, + "choices": [ + { + "message": { + "role": "assistant", + "content": "电影《铃芽之旅》的导演是新海诚。" + }, + "finish_reason": "stop", + "index": 0 + } + ] +} +``` + + + + +```bash +data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":""},"index":0,"finish_reason":null}]} + +data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"电"},"index":0,"finish_reason":null}]} + +data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"影"},"index":0,"finish_reason":null}]} + +data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"《"},"index":0,"finish_reason":null}]} +``` + + + + +```json +{ + "responseData": [ + // 不同模块的响应值, 不同版本具体值可能有差异，可先 log 自行查看最新值。 + { + "moduleName": "Dataset Search", + "price": 1.2000000000000002, + "model": "Embedding-2", + "tokens": 6, + "similarity": 0.61, + "limit": 3 + }, + { + "moduleName": "AI Chat", + "price": 454.5, + "model": "FastAI-4k", + "tokens": 303, + "question": "导演是谁", + "answer": "电影《铃芽之旅》的导演是新海诚。", + "maxToken": 2050, + "quoteList": [ + { + "dataset_id": "646627f4f7b896cfd8910e38", + "id": "8099", + "q": "本作的主人公是谁？", + "a": "本作的主人公是名叫铃芽的少女。", + "source": "手动修改" + }, + { + "dataset_id": "646627f4f7b896cfd8910e38", + "id": "8686", + "q": "电影《铃芽之旅》男主角是谁？", + "a": "电影《铃芽之旅》男主角是宗像草太，由松村北斗配音。", + "source": "" + }, + { + "dataset_id": "646627f4f7b896cfd8910e38", + "id": "19339", + "q": "电影《铃芽之旅》的导演是谁？22", + "a": "电影《铃芽之旅》的导演是新海诚。", + "source": "手动修改" + } + ], + "completeMessages": [ + { + "obj": "System", + "value": "下面是知识库内容:\n1. [本作的主人公是谁？\n本作的主人公是名叫铃芽的少女。]\n2. [电影《铃芽之旅》男主角是谁？\n电影《铃芽之旅》男主角是宗像草太，由松村北斗配音。]\n3. [电影《铃芽之旅》的导演是谁？22\n电影《铃芽之旅》的导演是新海诚。]\n" + }, + { + "obj": "System", + "value": "1.请记住，你的身份是百度的下一代知识增强语言模型，能够完全根据知识库提供的内容回答问题。\n\n2. 你忘记了关于电影《铃芽之旅》以外的内容。" + }, + { + "obj": "System", + "value": "你仅回答关于电影《玲芽之旅》的问题，其余问题直接回复: 我不清楚。" + }, + { + "obj": "Human", + "value": "导演是谁" + }, + { + "obj": "AI", + "value": "电影《铃芽之旅》的导演是新海诚。" + } + ] + } + ], + "id": "", + "model": "", + "usage": { + "prompt_tokens": 1, + "completion_tokens": 1, + "total_tokens": 1 + }, + "choices": [ + { + "message": { + "role": "assistant", + "content": "电影《铃芽之旅》的导演是新海诚。" + }, + "finish_reason": "stop", + "index": 0 + } + ] +} +``` + + + + +```bash +event: flowNodeStatus +data: {"status":"running","name":"知识库搜索"} + +event: flowNodeStatus +data: {"status":"running","name":"AI 对话"} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"content":"电影"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"content":"《铃"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"content":"芽之旅》"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"content":"的导演是新"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"content":"海诚。"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]} + +event: answer +data: [DONE] + +event: flowResponses +data: [{"moduleName":"知识库搜索","moduleType":"datasetSearchNode","runningTime":1.78},{"question":"导演是谁","quoteList":[{"id":"654f2e49b64caef1d9431e8b","q":"电影《铃芽之旅》的导演是谁？","a":"电影《铃芽之旅》的导演是新海诚!","indexes":[{"type":"qa","dataId":"3515487","text":"电影《铃芽之旅》的导演是谁？","_id":"654f2e49b64caef1d9431e8c","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8935586214065552},{"id":"6552e14c50f4a2a8e632af11","q":"导演是谁？","a":"电影《铃芽之旅》的导演是新海诚。","indexes":[{"defaultIndex":true,"type":"qa","dataId":"3644565","text":"导演是谁？\n电影《铃芽之旅》的导演是新海诚。","_id":"6552e14dde5cc7ba3954e417"}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8890955448150635},{"id":"654f34a0b64caef1d946337e","q":"本作的主人公是谁？","a":"本作的主人公是名叫铃芽的少女。","indexes":[{"type":"qa","dataId":"3515541","text":"本作的主人公是谁？","_id":"654f34a0b64caef1d946337f","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8738770484924316},{"id":"654f3002b64caef1d944207a","q":"电影《铃芽之旅》男主角是谁？","a":"电影《铃芽之旅》男主角是宗像草太，由松村北斗配音。","indexes":[{"type":"qa","dataId":"3515538","text":"电影《铃芽之旅》男主角是谁？","_id":"654f3002b64caef1d944207b","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8607980012893677},{"id":"654f2fc8b64caef1d943fd46","q":"电影《铃芽之旅》的编剧是谁？","a":"新海诚是本片的编剧。","indexes":[{"defaultIndex":true,"type":"qa","dataId":"3515550","text":"电影《铃芽之旅》的编剧是谁？22","_id":"654f2fc8b64caef1d943fd47"}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8468944430351257}],"moduleName":"AI 对话","moduleType":"chatNode","runningTime":1.86}] +``` + + + + +event取值： + + - answer: 返回给客户端的文本（最终会算作回答） + - fastAnswer: 指定回复返回给客户端的文本（最终会算作回答） + - toolCall: 执行工具 + - toolParams: 工具参数 + - toolResponse: 工具返回 + - flowNodeStatus: 运行到的节点状态 + - flowResponses: 节点完整响应 + - updateVariables: 更新变量 + - error: 报错 + + + + +### Response + +If your workflow contains interactive nodes, still call this API with `detail=true`. Get interactive node config from `event=interactive` data. For `stream=false`, find `type=interactive` elements in choices. + +When calling a workflow with interactive nodes, if an interactive node is encountered, it returns immediately with this info: + + + + +```json +{ + "interactive": { + "type": "userSelect", + "params": { + "description": "测试", + "userSelectOptions": [ + { + "value": "Confirm", + "key": "option1" + }, + { + "value": "Cancel", + "key": "option2" + } + ] + } + } +} +``` + + + + +```json +{ + "interactive": { + "type": "userInput", + "params": { + "description": "测试", + "inputForm": [ + { + "type": "input", + "key": "测试 1", + "label": "测试 1", + "description": "", + "value": "", + "defaultValue": "", + "valueType": "string", + "required": false, + "list": [ + { + "label": "", + "value": "" + } + ] + }, + { + "type": "numberInput", + "key": "测试 2", + "label": "测试 2", + "description": "", + "value": "", + "defaultValue": "", + "valueType": "number", + "required": false, + "list": [ + { + "label": "", + "value": "" + } + ] + } + ] + } + } +} +``` + + + + +### Continue Interactive Node + +After receiving interactive node info, render your UI to guide user input or selection. Then call this API again to continue the workflow. Use this format: + + + + +For user selection, simply pass the selected value to messages. + +```bash +curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \ +--header 'Authorization: Bearer fastgpt-xxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "stream": true, + "detail": true, + "chatId":"22222231", + "messages": [ + { + "role": "user", + "content": "Confirm" + } + ] +}' +``` + + + + +Form input is slightly more complex. Serialize the input as a JSON string for `messages`. Object keys match form keys, values are user inputs. Ensure `chatId` is consistent. + +```bash +curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \ +--header 'Authorization: Bearer fastgpt-xxxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "stream": true, + "detail": true, + "chatId":"22231", + "messages": [ + { + "role": "user", + "content": "{\"测试 1\":\"这是输入框的内容\",\"测试 2\":666}" + } + ] +}' +``` + + + + +## Request Plugin + +Plugin API is identical to chat API, with slight parameter differences: + +- 调用插件Type的应用时，接口默认为`detail`模式。 +- No need to pass `chatId` since plugins run only once. +- No need to pass `messages`. +- Pass `variables` to represent plugin inputs. +- Get plugin outputs from `pluginData`. + +### Request + +```bash +curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \ +--header 'Authorization: Bearer test-xxxxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "stream": false, + "chatId": "test", + "variables": { + "query":"你好" # 我的插件输入有一个参数，变量名叫 query + } +}' +``` + +### Response + + + + +- Find plugin output by locating `moduleType=pluginOutput` in `responseData`. Its `pluginOutput` contains the output. +- Stream output is still available via `choices`. + +```json +{ + "responseData": [ + { + "nodeId": "fdDgXQ6SYn8v", + "moduleName": "AI 对话", + "moduleType": "chatNode", + "totalPoints": 0.685, + "model": "FastAI-3.5", + "tokens": 685, + "query": "你好", + "maxToken": 2000, + "historyPreview": [ + { + "obj": "Human", + "value": "你好" + }, + { + "obj": "AI", + "value": "你好！有什么可以帮助你的吗？欢迎向我提问。" + } + ], + "contextTotalLen": 14, + "runningTime": 1.73 + }, + { + "nodeId": "pluginOutput", + "moduleName": "插件输出", + "moduleType": "pluginOutput", + "totalPoints": 0, + "pluginOutput": { + "result": "你好！有什么可以帮助你的吗？欢迎向我提问。" + }, + "runningTime": 0 + } + ], + "newVariables": { + "query": "你好" + }, + "id": "safsafsa", + "model": "", + "usage": { + "prompt_tokens": 1, + "completion_tokens": 1, + "total_tokens": 1 + }, + "choices": [ + { + "message": { + "role": "assistant", + "content": "你好！有什么可以帮助你的吗？欢迎向我提问。" + }, + "finish_reason": "stop", + "index": 0 + } + ] +} +``` + + + + +- Get plugin output by deserializing the `event=flowResponses` string into an array. Find `moduleType=pluginOutput` element; its `pluginOutput` contains the output. +- Stream output works the same as chat API. + +```bash +event: flowNodeStatus +data: {"status":"running","name":"AI 对话"} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"你"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"好"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"！"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"有"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"什"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"么"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"可以"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"帮"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"助"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"你"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"吗"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"？"},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]} + +event: answer +data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]} + +event: answer +data: [DONE] + +event: flowResponses +data: [{"nodeId":"fdDgXQ6SYn8v","moduleName":"AI 对话","moduleType":"chatNode","totalPoints":0.033,"model":"FastAI-3.5","tokens":33,"query":"你好","maxToken":2000,"historyPreview":[{"obj":"Human","value":"你好"},{"obj":"AI","value":"你好！有什么可以帮助你的吗？"}],"contextTotalLen":2,"runningTime":1.42},{"nodeId":"pluginOutput","moduleName":"插件输出","moduleType":"pluginOutput","totalPoints":0,"pluginOutput":{"result":"你好！有什么可以帮助你的吗？"},"runningTime":0}] +``` + + + + +event取值： + + - answer: 返回给客户端的文本（最终会算作回答） + - fastAnswer: 指定回复返回给客户端的文本（最终会算作回答） + - toolCall: 执行工具 + - toolParams: 工具参数 + - toolResponse: 工具返回 + - flowNodeStatus: 运行到的节点状态 + - flowResponses: 节点完整响应 + - updateVariables: 更新变量 + - error: 报错 + + + + +# Chat CRUD + +* The following APIs can be called with any `API Key`. +* 4.8.12 and above + +****Important Fields**** + +- chatId - The ID of a conversation window under an application +- dataId - The ID of a chat record under a conversation window + +## History + +## History + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/chat/history/getHistories' \ +--header 'Authorization: Bearer [apikey]' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "appId": "appId", + "offset": 0, + "pageSize": 20, + "source": "api" +}' +``` + + + + +
+- appId - Application ID +- offset - Offset (starting position) +- pageSize - Number of records +- source - Chat source. source=api means get API-created chats only (excludes web UI chats) +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "list": [ + { + "chatId": "usdAP1GbzSGu", + "updateTime": "2024-10-13T03:29:05.779Z", + "appId": "66e29b870b24ce35330c0f08", + "customTitle": "", + "title": "你好", + "top": false + }, + { + "chatId": "lC0uTAsyNBlZ", + "updateTime": "2024-10-13T03:22:19.950Z", + "appId": "66e29b870b24ce35330c0f08", + "customTitle": "", + "title": "测试", + "top": false + } + ], + "total": 2 + } +} +``` + + + + +### Update Chat Title + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/chat/history/updateHistory' \ +--header 'Authorization: Bearer [apikey]' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "appId": "appId", + "chatId": "chatId", + "customTitle": "自定义标题" +}' +``` + + + + + +
+- appId - Application ID +- chatId - History ID +- customTitle - Custom chat title +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +### Pin / Unpin + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/chat/history/updateHistory' \ +--header 'Authorization: Bearer [apikey]' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "appId": "appId", + "chatId": "chatId", + "top": true +}' +``` + + + + + +
+- appId - Application ID +- chatId - History ID +- top - Whether to pin. true = pin, false = unpin +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +## History + + + + +```bash +curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/delHistory?chatId=[chatId]&appId=[appId]' \ +--header 'Authorization: Bearer [apikey]' +``` + + + + + +
+- appId - Application ID +- chatId - History ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +## History + +Only clears chat history created via API Key. Does not clear history from web UI, share links, or other sources. + + + + +```bash +curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/clearHistories?appId=[appId]' \ +--header 'Authorization: Bearer [apikey]' +``` + + + + + +
+- appId - Application ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +## Chat Records + +Operations on chat records under a specific chatId. + +### Get Chat Initialization Info + + + + + ```bash + curl --location --request GET 'http://localhost:3000/api/core/chat/init?appId=[appId]&chatId=[chatId]' \ + --header 'Authorization: Bearer [apikey]' + ``` + + + + + +
+- appId - Application ID +- chatId - History ID +
+ + + + + + ```json + { + "code": 200, + "statusText": "", + "message": "", + "data": { + "chatId": "sPVOuEohjo3w", + "appId": "66e29b870b24ce35330c0f08", + "variables": {}, + "app": { + "chatConfig": { + "questionGuide": true, + "ttsConfig": { + "type": "web" + }, + "whisperConfig": { + "open": false, + "autoSend": false, + "autoTTSResponse": false + }, + "chatInputGuide": { + "open": false, + "textList": [], + "customUrl": "" + }, + "instruction": "", + "variables": [], + "fileSelectConfig": { + "canSelectFile": true, + "canSelectImg": true, + "maxFiles": 10 + }, + "_id": "66f1139aaab9ddaf1b5c596d", + "welcomeText": "" + }, + "chatModels": ["GPT-4o-mini"], + "name": "测试", + "avatar": "/imgs/app/avatar/workflow.svg", + "intro": "", + "type": "advanced", + "pluginInputs": [] + } + } + } + ``` + + + + +## Chat Records + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/chat/getPaginationRecords' \ +--header 'Authorization: Bearer [apikey]' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "appId": "appId", + "chatId": "chatId", + "offset": 0, + "pageSize": 10, + "loadCustomFeedbacks": true +}' +``` + + + + + +
+- appId - Application ID +- chatId - History ID +- offset - Offset +- pageSize - Number of records +- loadCustomFeedbacks - Whether to load custom feedbacks (optional) +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "list": [ + { + "_id": "670b84e6796057dda04b0fd2", + "dataId": "jzqdV4Ap1u004rhd2WW8yGLn", + "obj": "Human", + "value": [ + { + "text": { + "content": "你好" + } + } + ], + "customFeedbacks": [] + }, + { + "_id": "670b84e6796057dda04b0fd3", + "dataId": "x9KQWcK9MApGdDQH7z7bocw1", + "obj": "AI", + "value": [ + { + "text": { + "content": "你好！有什么我可以帮助你的吗？" + } + } + ], + "customFeedbacks": [], + "llmModuleAccount": 1, + "totalQuoteList": [], + "totalRunningTime": 2.42, + "historyPreviewLength": 2 + } + ], + "total": 2 + } +} +``` + + + + +## Chat Records + + + + +```bash +curl --location --request GET 'http://localhost:3000/api/core/chat/getResData?appId=[appId]&chatId=[chatId]&dataId=[dataId]' \ +--header 'Authorization: Bearer [apikey]' +``` + + + + + +
+- appId - Application ID +- chatId - Chat ID +- dataId - Chat Record ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": [ + { + "id": "mVlxkz8NfyfU", + "nodeId": "448745", + "moduleName": "common:core.module.template.work_start", + "moduleType": "workflowStart", + "runningTime": 0 + }, + { + "id": "b3FndAdHSobY", + "nodeId": "z04w8JXSYjl3", + "moduleName": "AI 对话", + "moduleType": "chatNode", + "runningTime": 1.22, + "totalPoints": 0.02475, + "model": "GPT-4o-mini", + "tokens": 75, + "query": "测试", + "maxToken": 2000, + "historyPreview": [ + { + "obj": "Human", + "value": "你好" + }, + { + "obj": "AI", + "value": "你好！有什么我可以帮助你的吗？" + }, + { + "obj": "Human", + "value": "测试" + }, + { + "obj": "AI", + "value": "测试成功！请问你有什么具体的问题或者需要讨论的话题吗？" + } + ], + "contextTotalLen": 4 + } + ] +} +``` + + + + +## Chat Records + + + + +```bash +curl --location --request DELETE 'http://localhost:3000/api/core/chat/item/delete?contentId=[contentId]&chatId=[chatId]&appId=[appId]' \ +--header 'Authorization: Bearer [apikey]' +``` + + + + + +
+- appId - Application ID +- chatId - History ID +- contentId - Chat Record ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +### Like / Unlike + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/updateUserFeedback' \ +--header 'Authorization: Bearer [apikey]' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "appId": "appId", + "chatId": "chatId", + "dataId": "dataId", + "userGoodFeedback": "yes" +}' +``` + + + + + +
+- appId - Application ID +- chatId - History ID +- dataId - Chat Record ID +- userGoodFeedback - User feedback when liking (optional). Omit to unlike. +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +### Dislike / Remove Dislike + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/updateUserFeedback' \ +--header 'Authorization: Bearer [apikey]' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "appId": "appId", + "chatId": "chatId", + "dataId": "dataId", + "userBadFeedback": "yes" +}' +``` + + + + + +
+- appId - Application ID +- chatId - History ID +- dataId - Chat Record ID +- userBadFeedback - User feedback when disliking (optional). Omit to remove dislike. +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +## Question Suggestions + +**4.8.16 New API (version** + +The new question suggestion feature requires both appId and chatId parameters. It automatically fetches the last 6 conversation turns from chatId as context. + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/ai/agent/v2/createQuestionGuide' \ +--header 'Authorization: Bearer [apikey]' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "appId": "appId", + "chatId": "chatId", + "questionGuide": { + "open": true, + "model": "GPT-4o-mini", + "customPrompt": "你是一个智能助手，请根据用户的问题生成猜你想问。" + } +}' +``` + + + + + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | ------ | ---- | ---------------------------------------------------------- | +| appId | string | ✅ | 应用 Id | +| chatId | string | ✅ | 对话 Id | +| questionGuide | object | | 自定义配置，不传的话，则会根据 appId，取最新发布版本的配置 | + +```ts +type CreateQuestionGuideParams = OutLinkChatAuthProps & { + appId: string; + chatId: string; + questionGuide?: { + open: boolean; + model?: string; + customPrompt?: string; + }; +}; +``` + + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": ["你对AI有什么看法？", "想了解AI的应用吗？", "你希望AI能做什么？"] +} +``` + + + diff --git a/document/content/docs/openapi/dataset.en.mdx b/document/content/docs/openapi/dataset.en.mdx new file mode 100644 index 0000000000..246032a8af --- /dev/null +++ b/document/content/docs/openapi/dataset.en.mdx @@ -0,0 +1,1305 @@ +--- +title: Dataset API +description: FastGPT OpenAPI Dataset API +--- + +| How to Get Dataset ID (datasetId) | How to Get Collection ID (collection_id) | +| ----------------------------- | ----------------------------------- | +| ![](/imgs/getDatasetId.jpg) | ![](/imgs/getfile_id.webp) | + +## Create Training Order + + + + +**New Example** + +```bash +curl --location --request POST 'http://localhost:3000/api/support/wallet/usage/createTrainingUsage' \ +--header 'Authorization: Bearer {{apikey}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "datasetId": "Dataset ID", + "name": "Optional, custom order name, e.g.: Document Training-fastgpt.docx" +}' +``` + + + + +data is the billId, which can be used for bill aggregation when adding dataset data. + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": "65112ab717c32018f4156361" +} +``` + + + + +## Dataset + +### Create a Dataset + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "parentId": null, + "type": "dataset", + "name":"测试", + "intro":"介绍", + "avatar": "", + "vectorModel": "text-embedding-ada-002", + "agentModel": "gpt-3.5-turbo-16k", + "vlmModel": "gpt-4.1" +}' +``` + + + + +
+ +- parentId - Parent ID for building directory structure. Usually can be null or omitted. +- type - `dataset` or `folder`, represents regular dataset or folder. If not provided, creates a regular dataset. +- name - Dataset name (required) +- intro - Description (optional) +- avatar - Avatar URL (optional) +- vectorModel - Vector model (recommended to leave empty, use system default) +- agentModel - Text processing model (recommended to leave empty, use system default) +- vlmModel - Image understanding model (recommended to leave empty, use system default) + +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": "65abc9bd9d1448617cba5e6c" +} +``` + + + + +### Get Dataset List + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/list?parentId=' \ +--header 'Authorization: Bearer xxxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "parentId":"" +}' +``` + + + + +
+- parentId - Parent ID. Pass empty string or null to get datasets in the root directory +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": [ + { + "_id": "65abc9bd9d1448617cba5e6c", + "parentId": null, + "avatar": "", + "name": "测试", + "intro": "", + "type": "dataset", + "permission": "private", + "canWrite": true, + "isOwner": true, + "vectorModel": { + "model": "text-embedding-ada-002", + "name": "Embedding-2", + "charsPointsPrice": 0, + "defaultToken": 512, + "maxToken": 8000, + "weight": 100 + } + } + ] +} +``` + + + + +### Get Dataset Details + + + + +```bash +curl --location --request GET 'http://localhost:3000/api/core/dataset/detail?id=6593e137231a2be9c5603ba7' \ +--header 'Authorization: Bearer {{authorization}}' \ +``` + + + + +
+- id: Dataset ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "_id": "6593e137231a2be9c5603ba7", + "parentId": null, + "teamId": "65422be6aa44b7da77729ec8", + "tmbId": "65422be6aa44b7da77729ec9", + "type": "dataset", + "status": "active", + "avatar": "/icon/logo.svg", + "name": "FastGPT test", + "vectorModel": { + "model": "text-embedding-ada-002", + "name": "Embedding-2", + "charsPointsPrice": 0, + "defaultToken": 512, + "maxToken": 8000, + "weight": 100 + }, + "agentModel": { + "model": "gpt-3.5-turbo-16k", + "name": "FastAI-16k", + "maxContext": 16000, + "maxResponse": 16000, + "charsPointsPrice": 0 + }, + "intro": "", + "permission": "private", + "updateTime": "2024-01-02T10:11:03.084Z", + "canWrite": true, + "isOwner": true + } +} +``` + + + + +### Delete a Dataset + + + + +```bash +curl --location --request DELETE 'http://localhost:3000/api/core/dataset/delete?id=65abc8729d1448617cba5df6' \ +--header 'Authorization: Bearer {{authorization}}' \ +``` + + + + +
+- id: Dataset ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +## Collection + +### Common Creation Parameters (Must Read) + +**Request** + +| Parameter | Description | Required | +| ---------------- | ----------------------------------------------------------------------------------------------------------- | ---- | +| datasetId | Dataset ID | ✅ | +| parentId： | Parent ID. Defaults to root directory if not provided | | +| trainingType | Data processing method. chunk: split by text length; qa: Q&A extraction | ✅ | +| indexPrefixTitle | Whether to auto-generate title index | | +| customPdfParse | Whether to enable enhanced PDF parsing. Default false: disabled; true: enabled | | +| autoIndexes | Whether to auto-generate indexes (commercial version only) | | +| imageIndex | Whether to auto-generate image indexes (commercial version only) | | +| chunkSettingMode | Chunk parameter mode. auto: system default; custom: manual specification | | +| chunkSplitMode | Chunk split mode. size: split by length; char: split by character. Ineffective when chunkSettingMode=auto. | | +| chunkSize | Chunk size, default 1500. Ineffective when chunkSettingMode=auto. | | +| indexSize | Index size, default 512, must be less than index model max token. Ineffective when chunkSettingMode=auto. | | +| chunkSplitter | Custom highest priority split symbol. Won't split further unless exceeding file processing max context. Ineffective when chunkSettingMode=auto. | | +| qaPrompt | QA split prompt | | +| tags | Collection tags (string array) | | +| createTime | File creation time (Date / String) | | + +**Response** + +- collectionId - New collection ID +- insertLen：Number of inserted chunks + +### Create an Empty Collection + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "datasetId":"6593e137231a2be9c5603ba7", + "parentId": null, + "name":"测试", + "type":"virtual", + "metadata":{ + "test":111 + } +}' +``` + + + + +
+- datasetId: Dataset ID(Required) +- parentId： Parent ID. Defaults to root directory if not provided +- name: Collection name (required) +- type: + - folder：Folder + - virtual: Virtual collection (manual collection) +- metadata： Metadata (not currently used) +
+ + + + + +data is the collection ID. + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": "65abcd009d1448617cba5ee1" +} +``` + + + + +### Create a Text Collection + +Pass in text to create a collection. The text will be split accordingly. + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/text' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "text":"xxxxxxxx", + "datasetId":"6593e137231a2be9c5603ba7", + "parentId": null, + "name":"测试训练", + + "trainingType": "qa", + "chunkSettingMode": "auto", + "qaPrompt":"", + + "metadata":{} +}' +``` + + + + +
+- text: Original text +- datasetId: Dataset ID(Required) +- parentId： Parent ID. Defaults to root directory if not provided +- name: Collection name (required) +- metadata： Metadata (not currently used) +
+ + + + + +data is the collection ID. + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "collectionId": "65abcfab9d1448617cba5f0d", + "results": { + "insertLen": 5, // Split into how many segments + "overToken": [], + "repeat": [], + "error": [] + } + } +} +``` + + + + +### Create a Link Collection + +Pass in a web link to create a collection. Content will be fetched from the webpage first, then split. + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/link' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "link":"https://doc.fastgpt.io/docs/course/quick-start/", + "datasetId":"6593e137231a2be9c5603ba7", + "parentId": null, + + "trainingType": "chunk", + "chunkSettingMode": "auto", + "qaPrompt":"", + + "metadata":{ + "webPageSelector":".docs-content" + } +}' +``` + + + + +
+- link: Web link +- datasetId: Dataset ID(Required) +- parentId： Parent ID. Defaults to root directory if not provided +- metadata.webPageSelector: Web page selector to specify which element to use as text (optional) +
+ + + + + +data is the collection ID. + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "collectionId": "65abd0ad9d1448617cba6031", + "results": { + "insertLen": 1, + "overToken": [], + "repeat": [], + "error": [] + } + } +} +``` + + + + +### Create a File Collection + +Pass in a file to create a collection. File content will be read and split. Currently supports: pdf, docx, md, txt, html, csv. + + + + +When uploading via code, note that Chinese filenames need to be encoded to avoid garbled text. + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/localFile' \ +--header 'Authorization: Bearer {{authorization}}' \ +--form 'file=@"C:\\Users\\user\\Desktop\\fastgpt测试File\\index.html"' \ +--form 'data="{\"datasetId\":\"6593e137231a2be9c5603ba7\",\"parentId\":null,\"trainingType\":\"chunk\",\"chunkSize\":512,\"chunkSplitter\":\"\",\"qaPrompt\":\"\",\"metadata\":{}}"' +``` + + + + +
+Use POST form-data format for upload. Contains file and data fields. + +- file: File +- data: Dataset-related info (pass as serialized JSON). See "Common Creation Parameters" above +
+ + + + + +data is the collection ID. + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "collectionId": "65abc044e4704bac793fbd81", + "results": { + "insertLen": 1, + "overToken": [], + "repeat": [], + "error": [] + } + } +} +``` + + + + +### Create an API Collection + +Pass in a file ID to create a collection. File content will be read and split. Currently supports: pdf, docx, md, txt, html, csv. + + + + +When uploading via code, note that Chinese filenames need to be encoded to avoid garbled text. + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/apiCollection' \ +--header 'Authorization: Bearer fastgpt-xxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "A Quick Guide to Building a Discord Bot.pdf", + "apiFileId":"A Quick Guide to Building a Discord Bot.pdf", + + "datasetId": "674e9e479c3503c385495027", + "parentId": null, + + "trainingType": "chunk", + "chunkSize":512, + "chunkSplitter":"", + "qaPrompt":"" +}' +``` + + + + +
+Use POST form-data format for upload. Contains file and data fields. + +- name: Collection name, recommended to use filename, required. +- apiFileId: File ID, required. +- datasetId: Dataset ID(Required) +- parentId： Parent ID. Defaults to root directory if not provided +- trainingType:Training mode (required) +- chunkSize: Length of each chunk (optional). chunk mode: 100~3000; qa mode: 4000~model max token (16k models usually recommended not to exceed 10000) +- chunkSplitter: Custom highest priority split symbol (optional) +- qaPrompt: QA split custom prompt (optional) +
+ + + + + +data is the collection ID. + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "collectionId": "65abc044e4704bac793fbd81", + "results": { + "insertLen": 1, + "overToken": [], + "repeat": [], + "error": [] + } + } +} +``` + + + + +### Create an External File Collection (Commercial) + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/proApi/core/dataset/collection/create/externalFileUrl' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "externalFileUrl":"https://image.xxxxx.com/fastgpt-dev/%E6%91%82.pdf", + "externalFileId":"1111", + "createTime": "2024-05-01T00:00:00.000Z", + "filename":"自定义File名.pdf", + "datasetId":"6642d105a5e9d2b00255b27b", + "parentId": null, + "tags": ["tag1","tag2"], + + "trainingType": "chunk", + "chunkSize":512, + "chunkSplitter":"", + "qaPrompt":"" +}' +``` + + + + + +| Parameter | Description | Required | +| --------------- | ------------------------------------ | ---- | +| externalFileUrl | File access URL (can be temporary) | ✅ | +| externalFileId | External file ID | | +| filename | Custom filename with extension | | +| createTime | File creation time (Date or ISO string both ok) | | + + + + + +data is the collection ID. + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "collectionId": "6646fcedfabd823cdc6de746", + "results": { + "insertLen": 1, + "overToken": [], + "repeat": [], + "error": [] + } + } +} +``` + + + + +### Get Collection List + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/listV2' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "offset":0, + "pageSize": 10, + "datasetId":"6593e137231a2be9c5603ba7", + "parentId": null, + "searchText":"" +}' +``` + + + + + +
+- offset: Offset +- pageSize: Items per page, max 30 (optional) +- datasetId: Dataset ID(Required) +- parentId: Parent ID (optional) +- searchText: Fuzzy search text (optional) +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "list": [ + { + "_id": "6593e137231a2be9c5603ba9", + "parentId": null, + "tmbId": "65422be6aa44b7da77729ec9", + "type": "virtual", + "name": "Manual entry", + "updateTime": "2099-01-01T00:00:00.000Z", + "dataAmount": 3, + "trainingAmount": 0, + "externalFileId": "1111", + "tags": ["11", "测试的"], + "forbid": false, + "trainingType": "chunk", + "permission": { + "value": 4294967295, + "isOwner": true, + "hasManagePer": true, + "hasWritePer": true, + "hasReadPer": true + } + }, + { + "_id": "65abd0ad9d1448617cba6031", + "parentId": null, + "tmbId": "65422be6aa44b7da77729ec9", + "type": "link", + "name": "快速上手 | FastGPT", + "rawLink": "https://doc.fastgpt.io/docs/course/quick-start/", + "updateTime": "2024-01-20T13:54:53.031Z", + "dataAmount": 3, + "trainingAmount": 0, + "externalFileId": "222", + "tags": ["测试的"], + "forbid": false, + "trainingType": "chunk", + "permission": { + "value": 4294967295, + "isOwner": true, + "hasManagePer": true, + "hasWritePer": true, + "hasReadPer": true + } + } + ], + "total": 93 + } +} +``` + + + + +### Get Collection Details + + + + +```bash +curl --location --request GET 'http://localhost:3000/api/core/dataset/collection/detail?id=65abcfab9d1448617cba5f0d' \ +--header 'Authorization: Bearer {{authorization}}' \ +``` + + + + + +
+- id: Collection ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "_id": "65abcfab9d1448617cba5f0d", + "parentId": null, + "teamId": "65422be6aa44b7da77729ec8", + "tmbId": "65422be6aa44b7da77729ec9", + "datasetId": { + "_id": "6593e137231a2be9c5603ba7", + "parentId": null, + "teamId": "65422be6aa44b7da77729ec8", + "tmbId": "65422be6aa44b7da77729ec9", + "type": "dataset", + "status": "active", + "avatar": "/icon/logo.svg", + "name": "FastGPT test", + "vectorModel": "text-embedding-ada-002", + "agentModel": "gpt-3.5-turbo-16k", + "intro": "", + "permission": "private", + "updateTime": "2024-01-02T10:11:03.084Z" + }, + "type": "virtual", + "name": "测试训练", + "trainingType": "qa", + "chunkSize": 8000, + "chunkSplitter": "", + "qaPrompt": "11", + "rawTextLength": 40466, + "hashRawText": "47270840614c0cc122b29daaddc09c2a48f0ec6e77093611ab12b69cba7fee12", + "createTime": "2024-01-20T13:50:35.838Z", + "updateTime": "2024-01-20T13:50:35.838Z", + "canWrite": true, + "sourceName": "测试训练" + } +} +``` + + + + +### Update Collection Info + + + + +**Update Collection Info by Collection ID** + +```bash +curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection/update' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "id":"65abcfab9d1448617cba5f0d", + "parentId": null, + "name": "测2222试", + "tags": ["tag1", "tag2"], + "forbid": false, + "createTime": "2024-01-01T00:00:00.000Z" +}' +``` + +**Update Collection Info by External File ID**， Just replace id with datasetId and externalFileId. + +```bash +curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection/update' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "datasetId":"6593e137231a2be9c5603ba7", + "externalFileId":"1111", + "parentId": null, + "name": "测2222试", + "tags": ["tag1", "tag2"], + "forbid": false, + "createTime": "2024-01-01T00:00:00.000Z" +}' +``` + + + + + +
+- id: Collection ID +- parentId: Update parent ID (optional) +- name: Update collection name (optional) +- tags: Update collection tags (optional) +- forbid: Update collection disabled status (optional) +- createTime: Update collection creation time (optional) +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +### Delete a Collection + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/delete' \ +--header 'Authorization: Bearer fastgpt-' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "collectionIds": ["65a8cdcb0d70d3de0bf08d0a"] +}' +``` + + + + + +
+- collectionIds: Collection ID list +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +## Data + +### Data Structure + +**Data Structure** + +| Field | Type | Description | Required | +| ------------- | ------- | -------- | ---- | +| teamId | String | Team ID | ✅ | +| tmbId | String | Member ID | ✅ | +| datasetId | String | Dataset ID | ✅ | +| collectionId | String | CollectionID | ✅ | +| q | String | Primary data | ✅ | +| a | String | Auxiliary data | ✖ | +| fullTextToken | String | Tokenization | ✖ | +| indexes | Index[] | Vector indexes | ✅ | +| updateTime | Date | Update time | ✅ | +| chunkIndex | Number | Chunk index | ✖ | + +**Index Structure** + +Maximum 5 custom indexes per data group + +| Field | Type | Description | Required | +| ------ | ------ | ------------------------------------------------------------------------------------------------------ | ---- | +| type | String | Optional index types: default-default index; custom-custom index; summary-summary index; question-question index; image-image index | | +| dataId | String | Associated vector ID. Pass this ID when updating data for incremental updates instead of full updates | | +| text | String | Text content | ✅ | + +`type` If not provided, defaults to `custom` index. A default index will also be created based on q/a. If a default index is provided, no additional one will be created. + +### Batch Add Data to Collection + +Note: Maximum 200 data groups per push. + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/data/pushData' \ +--header 'Authorization: Bearer apikey' \ +--header 'Content-Type: application/json' \ +--data-raw '{ +    "collectionId": "64663f451ba1676dbdef0499", + "trainingType": "chunk", + "prompt": "Optional. QA split guide prompt, ignored in chunk mode", + "billId": "可选。如果有这个值，本次的Data会被聚合到一个订单中，这个值可以重复使用。可以参考 [Create Training Order] 获取该值。", +    "data": [ + { + "q": "Who are you?", + "a": "I'm FastGPT Assistant" + }, + { + "q": "What can you do?", + "a": "I can do anything", + "indexes": [ + { + "text":"Custom index 1" + }, + { + "text":"Custom index 2" + } + ] + } + ] +}' +``` + + + + + +
+- collectionId: Collection ID (required) +- trainingType:Training mode (required) +- prompt: Custom QA split prompt. Must follow template strictly. Recommended not to pass. (optional) +- data：(Specific data) + + - q: Primary data（Required） + - a: Auxiliary data (optional) + - indexes: Custom indexes (optional). Can omit or pass empty array. By default, an index will be created from q and a. +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "data": { + "insertLen": 1, // Final number of successful insertions + "overToken": [], // Exceeding token + "repeat": [], // Number of duplicates + "error": [] // Other errors + } +} +``` + + + + + +[theme] content can be replaced with the data theme. Default: They may contain multiple theme contents + +``` +I'll give you a text, [theme], learn it, and organize the learning results, requirements: +1. Propose up to 25 questions. +2. Provide answers to each question. +3. Answers should be detailed and complete, and can include plain text, links, code, tables, formulas, media links, and other markdown elements. +4. Return multiple questions and answers in format: + +Q1: Question. +A1: Answer. +Q2: +A2: +…… + +My text:"""{{text}}""" +``` + + + + + +### Get Collection Data List + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/data/v2/list' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "offset": 0, + "pageSize": 10, + "collectionId":"65abd4ac9d1448617cba6171", + "searchText":"" +}' +``` + + + + + +
+- offset: Offset (optional) +- pageSize: Items per page, max 30 (optional) +- collectionId: Collection ID（Required） +- searchText: Fuzzy search term (optional) +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "list": [ + { + "_id": "65abd4b29d1448617cba61db", + "datasetId": "65abc9bd9d1448617cba5e6c", + "collectionId": "65abd4ac9d1448617cba6171", + "q": "N o . 2 0 2 2 1 2中 国 信 息 通 信 研 究 院京东探索研究院2022年 9月人工智能生成内容（AIGC）白皮书(2022 年)版权声明本白皮书版权属于中国信息通信研究院和京东探索研究院，并受法律保护。转载、摘编或利用其它方式使用本白皮书文字or观点的，应注明“来源：中国信息通信研究院和京东探索研究院”。违反上述声明者，编者将追究其相关法律责任。前 言习近平总书记曾指出，“数字技术正以新理念、新业态、新模式全面融入人类经济、政治、文化、社会、生态文明建设各领域和全过程”。在当前数字世界和物理世界加速融合的大背景下，人工智能生成内容（Artificial Intelligence Generated Content，简称 AIGC）正在悄然引导着一场深刻的变革，重塑甚至颠覆数字内容的生产方式和消费模式，将极大地丰富人们的数字生活，是未来全面迈向数字文明新时代不可或缺的支撑力量。", + "a": "", + "chunkIndex": 0 + }, + { + "_id": "65abd4b39d1448617cba624d", + "datasetId": "65abc9bd9d1448617cba5e6c", + "collectionId": "65abd4ac9d1448617cba6171", + "q": "本白皮书重点从 AIGC 技术、应用和治理等维度进行了阐述。在技术层面，梳理提出了 AIGC 技术体系，既涵盖了对现实世界各种内容的数字化呈现和增强，也包括了基于人工智能的自主内容创作。在应用层面，重点分析了 AIGC 在传媒、电商、影视等行业和场景的应用情况，探讨了以虚拟数字人、写作机器人等为代表的新业态和新应用。在治理层面，从政策监管、技术能力、企业应用等视角，分析了AIGC 所暴露出的版权纠纷、虚假信息传播等各种Question.最后，从政府、行业、企业、社会等层面，给出了 AIGC 发展和治理建议。由于人工智能仍处于飞速发展阶段，我们对 AIGC 的认识还有待进一步深化，白皮书中存在不足之处，敬请大家批评指正。目 录一、 人工智能生成内容的发展历程与概念.............................................................. 1（一）AIGC 历史沿革 .......................................................................................... 1（二）AIGC 的概念与内涵 .................................................................................. 4二、人工智能生成内容的技术体系及其演进方向.................................................... 7（一）AIGC 技术升级步入深化阶段 .................................................................. 7（二）AIGC 大模型架构潜力凸显 .................................................................... 10（三）AIGC 技术演化出三大前沿能力 ............................................................ 18三、人工智能生成内容的应用场景.......................................................................... 26（一）AIGC+传媒：人机协同生产，", + "a": "", + "chunkIndex": 1 + } + ], + "total": 63 + } +} +``` + + + + +### Get Single Data Details + + + + +```bash +curl --location --request GET 'http://localhost:3000/api/core/dataset/data/detail?id=65abd4b29d1448617cba61db' \ +--header 'Authorization: Bearer {{authorization}}' \ +``` + + + + + +
+- id: Data ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": { + "id": "65abd4b29d1448617cba61db", + "q": "N o . 2 0 2 2 1 2中 国 信 息 通 信 研 究 院京东探索研究院2022年 9月人工智能生成内容（AIGC）白皮书(2022 年)版权声明本白皮书版权属于中国信息通信研究院和京东探索研究院，并受法律保护。转载、摘编或利用其它方式使用本白皮书文字or观点的，应注明“来源：中国信息通信研究院和京东探索研究院”。违反上述声明者，编者将追究其相关法律责任。前 言习近平总书记曾指出，“数字技术正以新理念、新业态、新模式全面融入人类经济、政治、文化、社会、生态文明建设各领域和全过程”。在当前数字世界和物理世界加速融合的大背景下，人工智能生成内容（Artificial Intelligence Generated Content，简称 AIGC）正在悄然引导着一场深刻的变革，重塑甚至颠覆数字内容的生产方式和消费模式，将极大地丰富人们的数字生活，是未来全面迈向数字文明新时代不可或缺的支撑力量。", + "a": "", + "chunkIndex": 0, + "indexes": [ + { + "type": "default", + "dataId": "3720083", + "text": "N o . 2 0 2 2 1 2中 国 信 息 通 信 研 究 院京东探索研究院2022年 9月人工智能生成内容（AIGC）白皮书(2022 年)版权声明本白皮书版权属于中国信息通信研究院和京东探索研究院，并受法律保护。转载、摘编或利用其它方式使用本白皮书文字or观点的，应注明“来源：中国信息通信研究院和京东探索研究院”。违反上述声明者，编者将追究其相关法律责任。前 言习近平总书记曾指出，“数字技术正以新理念、新业态、新模式全面融入人类经济、政治、文化、社会、生态文明建设各领域和全过程”。在当前数字世界和物理世界加速融合的大背景下，人工智能生成内容（Artificial Intelligence Generated Content，简称 AIGC）正在悄然引导着一场深刻的变革，重塑甚至颠覆数字内容的生产方式和消费模式，将极大地丰富人们的数字生活，是未来全面迈向数字文明新时代不可或缺的支撑力量。", + "_id": "65abd4b29d1448617cba61dc" + } + ], + "datasetId": "65abc9bd9d1448617cba5e6c", + "collectionId": "65abd4ac9d1448617cba6171", + "sourceName": "中文-AIGC白皮书2022.pdf", + "sourceId": "65abd4ac9d1448617cba6166", + "isOwner": true, + "canWrite": true + } +} +``` + + + + +### Update Single Data + + + + +```bash +curl --location --request PUT 'http://localhost:3000/api/core/dataset/data/update' \ +--header 'Authorization: Bearer {{authorization}}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "dataId":"65abd4b29d1448617cba61db", + "q":"Test 111", + "a":"sss", + "indexes":[ + { + "dataId": "xxxx", + "type": "default", + "text": "Default index" + }, + { + "dataId": "xxx", + "type": "custom", + "text": "旧的Custom index 1" + }, + { + "type":"custom", + "text":"New custom index" + } + ] +}' +``` + + + + + +
+- dataId: Data ID +- q: Primary data (optional) +- a: Auxiliary data (optional) +- indexes: Custom indexes (optional). See `Batch Add Data to Collection` for types. If custom indexes exist when created, +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": null +} +``` + + + + +### Delete Single Data + + + + +```bash +curl --location --request DELETE 'http://localhost:3000/api/core/dataset/data/delete?id=65abd4b39d1448617cba624d' \ +--header 'Authorization: Bearer {{authorization}}' \ +``` + + + + + +
+- id: Data ID +
+ + + + + +```json +{ + "code": 200, + "statusText": "", + "message": "", + "data": "success" +} +``` + + + + +## Search Test + + + + +```bash +curl --location --request POST 'http://localhost:3000/api/core/dataset/searchTest' \ +--header 'Authorization: Bearer fastgpt-xxxxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "datasetId": "Dataset ID", + "text": "Who is the director", + "limit": 5000, + "similarity": 0, + "searchMode": "embedding", + "usingReRank": false, + + "datasetSearchUsingExtensionQuery": true, + "datasetSearchExtensionModel": "gpt-5", + "datasetSearchExtensionBg": "" +}' +``` + + + + + +
+- datasetId - Dataset ID +- text - Text to test +- limit - Maximum tokens +- similarity - Minimum similarity (0~1, optional) +- searchMode - Search mode: embedding | fullTextRecall | mixedRecall +- usingReRank - Use rerank +- datasetSearchUsingExtensionQuery - Use query extension +- datasetSearchExtensionModel - Query extension model +- datasetSearchExtensionBg - Query extension background description +
+ + + + + +Returns top k results. limit is the maximum tokens, up to 20000 tokens. + +```json +{ + "code": 200, + "statusText": "", + "data": [ + { + "id": "65599c54a5c814fb803363cb", + "q": "你是谁", + "a": "I'm FastGPT Assistant", + "datasetId": "6554684f7f9ed18a39a4d15c", + "collectionId": "6556cd795e4b663e770bb66d", + "sourceName": "GBT 15104-2021 装饰单板贴面人造板.pdf", + "sourceId": "6556cd775e4b663e770bb65c", + "score": 0.8050316572189331 + }, + ...... + ] +} +``` + + + diff --git a/document/content/docs/openapi/index.en.mdx b/document/content/docs/openapi/index.en.mdx new file mode 100644 index 0000000000..f02570cf22 --- /dev/null +++ b/document/content/docs/openapi/index.en.mdx @@ -0,0 +1,8 @@ +--- +title: OpenAPI Documentation +description: FastGPT OpenAPI Documentation +--- + +import { Redirect } from '@/components/docs/Redirect'; + + diff --git a/document/content/docs/openapi/intro.en.mdx b/document/content/docs/openapi/intro.en.mdx new file mode 100644 index 0000000000..81ab14e88c --- /dev/null +++ b/document/content/docs/openapi/intro.en.mdx @@ -0,0 +1,88 @@ +--- +title: OpenAPI Introduction +description: FastGPT OpenAPI Introduction +--- + +## Automated API Documentation + +The automated API documentation covers all endpoints in the current version, regardless of whether they can be called via API Key. + +All future endpoints will be auto-generated, with documentation continuously improved. + +- [China Mainland API Documentation](https://cloud.fastgpt.cn/openapi) +- [International API Documentation](https://cloud.fastgpt.io/openapi) + +## Usage Guide + +FastGPT OpenAPI lets you authenticate with an API Key to access FastGPT services and resources -- such as calling app chat endpoints, uploading knowledge base data, search testing, and more. For compatibility and security reasons, not all endpoints support API Key access. + +## How to Find Your BaseURL + +**Note: BaseURL is not an endpoint address -- it's the root URL for all endpoints. Requesting the BaseURL directly won't work.** + +![](/imgs/fastgpt-api-baseurl.png) + +## How to Get an API Key + +FastGPT has **2 types** of API Keys: a global key (cannot directly call app chat) and an app-specific key that includes an AppId (can directly call app chat). + +We recommend using `app-specific keys` only for app or chat-related endpoints, and `global keys` for everything else. + +| Global Key | App-Specific Key | +| --------------------- | --------------------- | +| ![](/imgs/fastgpt-api2.jpg) | ![](/imgs/fastgpt-api1.jpg) | + + +## Basic Configuration + +In OpenAPI, all endpoints authenticate via Header.Authorization. + +``` +baseUrl: "http://localhost:3000/api" +headers: { + Authorization: "Bearer {{apikey}}" +} +``` + +**Example: Start an App Chat** + +```sh +curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \ +--header 'Authorization: Bearer fastgpt-xxxxxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "chatId": "111", + "stream": false, + "detail": false, + "messages": [ + { + "content": "Who is the director", + "role": "user" + } + ] +}' +``` + +## Custom User ID + +Since `v4.8.13`, you can pass a custom user ID that will be saved in the chat history. + +```sh +curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \ +--header 'Authorization: Bearer fastgpt-xxxxxx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "chatId": "111", + "stream": false, + "detail": false, + "messages": [ + { + "content": "Who is the director", + "role": "user" + } + ], + "customUid": "xxxxxx" +}' +``` + +In the chat history, this record's user will be displayed as `xxxxxx`. diff --git a/document/content/docs/openapi/meta.en.json b/document/content/docs/openapi/meta.en.json new file mode 100644 index 0000000000..fc8e60e748 --- /dev/null +++ b/document/content/docs/openapi/meta.en.json @@ -0,0 +1,11 @@ +{ + "root": true, + "title": "OpenAPI Documentation", + "pages": [ + "intro", + "app", + "chat", + "dataset", + "share" + ] +} diff --git a/document/content/docs/openapi/share.en.mdx b/document/content/docs/openapi/share.en.mdx new file mode 100644 index 0000000000..34614036f3 --- /dev/null +++ b/document/content/docs/openapi/share.en.mdx @@ -0,0 +1,372 @@ +--- +title: Share Link Authentication +description: FastGPT Share Link Authentication +--- + +## Introduction + +In FastGPT V4.6.4, we changed how share links read data. A `localId` is generated for each user to identify them and pull chat history from the cloud. However, this only works on the same device and browser -- switching devices or clearing browser cache will lose those records. Due to this limitation, we only allow users to pull the last `20` records from the past `30 days`. + +Share link authentication is designed to quickly and securely integrate FastGPT's chat interface into your existing system with just 2 endpoints. This feature is only available in the commercial edition. + +## Usage Guide + +In the share link configuration, you can optionally fill in the `Identity Verification` field. This is the root URL for a `POST` request. Once configured, share link initialization, chat start, and chat completion will all send requests to specific endpoints under this URL. Below, we use `host` to represent the `identity verification root URL`. Your server only needs to return whether verification succeeded -- no other data is required. The format is as follows: + +### Unified Response Format + +```jsonc +{ + "success": true, + "message": "Error message", + "msg": "Same as message, error message", + "data": { + "uid": "Unique user identifier" // Required + } +} +``` + +`FastGPT` checks whether `success` is `true` to decide if the user can proceed. `message` and `msg` are equivalent -- you can return either one. When `success` is not `true`, this error message will be displayed to the user. + +`uid` is the unique user identifier and must be returned. The ID format must be a string that does not contain `|`, `/`, or `\\` characters, with a length of 255 **bytes** or less. Otherwise, an `Invalid UID` error will be returned. The `uid` is used to pull and save chat history -- see the practical example below. + +### Flow Diagram + +![](/imgs/sharelink_process.png) + +## Configuration Guide + +### 1. Configure the Identity Verification URL + +![](/imgs/share-setlink.png) + +Once configured, every time the share link is used, verification and reporting requests will be sent to the corresponding endpoints. + +You only need to configure the root URL here -- no need to specify the full request path. + +### 2. Add an Extra Query Parameter to the Share Link + +Add an extra parameter `authToken` to the share link URL. For example: + +Original link: `https://share.fastgpt.io/chat/share?shareId=648aaf5ae121349a16d62192` + +Full link: `https://share.fastgpt.io/chat/share?shareId=648aaf5ae121349a16d62192&authToken=userid12345` + +This `authToken` is typically a unique user credential (such as a token) generated by your system. FastGPT will include `token=[authToken]` in the `body` of the verification request. + +### 3. Implement the Chat Initialization Verification Endpoint + + + + +```bash +curl --location --request POST '{{host}}/shareAuth/init' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "token": "[authToken]" +}' +``` + + + + + +```json +{ + "success": true, + "data": { + "uid": "Unique user identifier" + } +} +``` + +The system will pull chat history for uid `username123` under this share link. + + + + + +```json +{ + "success": false, + "message": "Authentication failed" +} +``` + + + + +### 4. Implement the Pre-Chat Verification Endpoint + + + + +```bash +curl --location --request POST '{{host}}/shareAuth/start' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "token": "[authToken]", + "question": "User question", +}' +``` + + + + + +```json +{ + "success": true, + "data": { + "uid": "Unique user identifier" + } +} +``` + + + + + +```json +{ + "success": false, + "message": "Authentication failed" +} +``` + +```json +{ + "success": false, + "message": "Content policy violation" +} +``` + + + + +### 5. Implement the Chat Result Reporting Endpoint (Optional) + +This endpoint has no required response format. + +The response data follows the same format as the [chat endpoint](/docs/openapi/intro/#response), with an additional `token` field. + +Key fields to note: `totalPoints` (total AI credits consumed), `token` (total token consumption) + +```bash +curl --location --request POST '{{host}}/shareAuth/finish' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "token": "[authToken]", + "responseData": [ + { + "moduleName": "core.module.template.Dataset search", + "moduleType": "datasetSearchNode", + "totalPoints": 1.5278, + "query": "导演是谁\n《铃芽之旅》的导演是谁？\n这部电影的导演是谁？\n谁是《铃芽之旅》的导演？", + "model": "Embedding-2(旧版，不推荐使用)", + "tokens": 1524, + "similarity": 0.83, + "limit": 400, + "searchMode": "embedding", + "searchUsingReRank": false, + "extensionModel": "FastAI-4k", + "extensionResult": "《铃芽之旅》的导演是谁？\n这部电影的导演是谁？\n谁是《铃芽之旅》的导演？", + "runningTime": 2.15 + }, + { + "moduleName": "AI 对话", + "moduleType": "chatNode", + "totalPoints": 0.593, + "model": "FastAI-4k", + "tokens": 593, + "query": "导演是谁", + "maxToken": 2000, + "quoteList": [ + { + "id": "65bb346a53698398479a8854", + "q": "导演是谁？", + "a": "电影《铃芽之旅》的导演是新海诚。", + "chunkIndex": 0, + "datasetId": "65af9b947916ae0e47c834d2", + "collectionId": "65bb345c53698398479a868f", + "sourceName": "dataset - 2024-01-23T151114.198.csv", + "sourceId": "65bb345b53698398479a868d", + "score": [ + { + "type": "embedding", + "value": 0.9377183318138123, + "index": 0 + }, + { + "type": "rrf", + "value": 0.06557377049180328, + "index": 0 + } + ] + } + ], + "historyPreview": [ + { + "obj": "Human", + "value": "使用 标记中的内容作为本次对话的参考:\n\n\n导演是谁？\n电影《铃芽之旅》的导演是新海诚。\n------\n电影《铃芽之旅》的编剧是谁？22\n新海诚是本片的编剧。\n------\n电影《铃芽之旅》的女主角是谁？\n电影的女主角是铃芽。\n------\n电影《铃芽之旅》的制作团队中有哪位著名人士？2\n川村元气是本片的制作团队成员之一。\n------\n你是谁？\n我是电影《铃芽之旅》助手\n------\n电影《铃芽之旅》男主角是谁？\n电影《铃芽之旅》男主角是宗像草太，由松村北斗配音。\n------\n电影《铃芽之旅》的作者新海诚写了一本小说，叫什么名字？\n小说名字叫《铃芽之旅》。\n------\n电影《铃芽之旅》的女主角是谁？\n电影《铃芽之旅》的女主角是岩户铃芽，由原菜乃华配音。\n------\n电影《铃芽之旅》的故事背景是什么？\n日本\n------\n谁担任电影《铃芽之旅》中岩户环的配音？\n深津绘里担任电影《铃芽之旅》中岩户环的配音。\n\n\n回答要求：\n- 如果你不清楚答案，你需要澄清。\n- 避免提及你是从 获取的知识。\n- 保持答案与 中描述的一致。\n- 使用 Markdown 语法优化回答格式。\n- 使用与问题相同的语言回答。\n\n问题:\"\"\"导演是谁\"\"\"" + }, + { + "obj": "AI", + "value": "电影《铃芽之旅》的导演是新海诚。" + } + ], + "contextTotalLen": 2, + "runningTime": 1.32 + } + ] + + +}' +``` + +**Full responseData Field Reference:** + +```ts +type ResponseType = { + moduleType: FlowNodeTypeEnum; // Module type + moduleName: string; // Module name + moduleLogo?: string; // Logo + runningTime?: number; // Running time + query?: string; // User question / search query + textOutput?: string; // Text output + + tokens?: number; // Total context tokens + model?: string; // Model used + contextTotalLen?: number; // Total context length + totalPoints?: number; // Total AI credits consumed + + temperature?: number; // Temperature + maxToken?: number; // Model max tokens + quoteList?: SearchDataResponseItemType[]; // Citation list + historyPreview?: ChatItemType[]; // Context preview (history may be truncated) + + similarity?: number; // Minimum similarity threshold + limit?: number; // Max citation tokens + searchMode?: `${DatasetSearchModeEnum}`; // Search mode + searchUsingReRank?: boolean; // Whether rerank is used + extensionModel?: string; // Query expansion model + extensionResult?: string; // Query expansion result + extensionTokens?: number; // Query expansion total token length + + cqList?: ClassifyQuestionAgentItemType[]; // Question classification list + cqResult?: string; // Question classification result + + extractDescription?: string; // Content extraction description + extractResult?: Record; // Content extraction result + + params?: Record; // HTTP module params + body?: Record; // HTTP module body + headers?: Record; // HTTP module headers + httpResult?: Record; // HTTP module result + + pluginOutput?: Record; // Plugin output + pluginDetail?: ChatHistoryItemResType[]; // Plugin details + + isElseResult?: boolean; // Conditional result +}; +``` + +## Practical Example + +We'll use [Laf as the server](https://laf.dev/) to demonstrate how these 3 endpoints work. + +### 1. Create 3 Laf Endpoints + +![](/imgs/share-auth1.png) + + + + +In this endpoint, we require `token` to equal `fastgpt` to pass verification. (Not recommended for production -- avoid hardcoding values.) + +```ts +import cloud from '@lafjs/cloud'; + +export default async function (ctx: FunctionContext) { + const { token } = ctx.body; + + // Token decoding logic omitted + if (token === 'fastgpt') { + return { success: true, data: { uid: 'user1' } }; + } + + return { success: false, message: 'Authentication failed' }; +} +``` + + + + + +In this endpoint, we require `token` to equal `fastgpt` to pass verification. Additionally, if the question contains a specific character, it returns an error to simulate content moderation. + +```ts +import cloud from '@lafjs/cloud'; + +export default async function (ctx: FunctionContext) { + const { token, question } = ctx.body; + + // Token decoding logic omitted + if (token !== 'fastgpt') { + return { success: false, message: 'Authentication failed' }; + } + + if (question.includes('你')) { + return { success: false, message: 'Content policy violation' }; + } + + return { success: true, data: { uid: 'user1' } }; +} +``` + + + + + +The result reporting endpoint can handle custom logic as needed. + +```ts +import cloud from '@lafjs/cloud'; + +export default async function (ctx: FunctionContext) { + const { token, responseData } = ctx.body; + + const total = responseData.reduce((sum, item) => sum + item.price, 0); + const amount = total / 100000; + + // Database operations omitted + + return {}; +} +``` + + + + +### 2. Configure the Verification URL + +Copy any of the 3 endpoint URLs, e.g. `https://d8dns0.laf.dev/shareAuth/finish`, remove the `/shareAuth/finish` part, and enter the root URL `https://d8dns0.laf.dev` in the `Identity Verification` field. + +![](/imgs/share-auth2.jpg) + +### 3. Modify the Share Link Parameters + +Original share link: `https://share.fastgpt.io/chat/share?shareId=64be36376a438af0311e599c` + +Modified: `https://share.fastgpt.io/chat/share?shareId=64be36376a438af0311e599c&authToken=fastgpt` + +### 4. Test the Result + +1. Opening the original link or a link where `authToken` does not equal `fastgpt` will show an authentication error. +2. Sending content that contains the filtered character will show a content policy violation error. + +## Use Cases + +This authentication method is typically used to embed the `share link` directly into your application. Before opening the share link in your app, you should append the `authToken` parameter. + +Beyond integrating with your existing user system, you can also implement a `balance` feature -- deduct user balance via the `result reporting` endpoint and check user balance via the `pre-chat verification` endpoint. diff --git a/document/content/docs/openapi/translate_chat.py b/document/content/docs/openapi/translate_chat.py new file mode 100644 index 0000000000..a861b11485 --- /dev/null +++ b/document/content/docs/openapi/translate_chat.py @@ -0,0 +1,329 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +# Read the Chinese file +with open('chat.mdx', 'r', encoding='utf-8') as f: + lines = f.readlines() + +# Translation mappings for common terms +translations = { + '对话接口': 'Chat API', + '如何获取': 'How to Get', + '可在应用详情的路径里获取': 'You can find the AppId in your application details URL', + '发起对话': 'Start a Conversation', + '该接口的 API Key 需使用': 'This API requires', + '应用特定的 key': 'an application-specific API key', + '否则会报错': 'or it will return an error', + '有些包调用时': 'Some packages require', + '需要添加': 'adding', + '路径，有些不需要，如果出现404情况，可补充': 'to the path. If you get a 404 error, try adding', + '重试': 'and retry', + '请求对话 Agent 和工作流': 'Request Chat Agent and Workflow', + '对话接口兼容': 'chat API is compatible with', + '的接口！如果你的项目使用的是标准的': "interface! If you're using the standard", + '官方接口，可以直接通过修改': 'official API, you can access FastGPT by simply changing the', + '来访问 FastGpt 应用，不过需要注意下面几个规则：': 'However, note these rules:', + '传入的': 'Parameters like', + '等参数字段均无效，这些字段由编排决定，不会根据 API 参数改变。': 'are ignored. These values are determined by your workflow configuration.', + '不会返回实际消耗': "Won't return actual", + '值，如果需要，可以设置': 'consumed. If needed, set', + '，并手动计算': 'and manually calculate', + '里的': 'from', + '值。': 'values.', + '请求': 'Request', + '基础请求示例': 'Basic Request Example', + '图片/文件请求示例': 'Image/File Request Example', + '参数说明': 'Parameters', + '仅': 'Only', + '有部分区别，其他参数一致。': 'differs slightly; other parameters are the same.', + '目前不支持上传文件，需上传到自己的对象存储中，获取对应的文件链接。': 'Direct file uploads are not supported. Upload files to your object storage and provide the URL.', + '图片链接': 'Image URL', + '文件名': 'Filename', + '文档链接，支持': 'Document URL. Supports', + '为时（不传入），不使用': 'When empty (not provided), FastGPT context is disabled. Context is built entirely from', + '提供的上下文功能，完全通过传入的': 'provided.', + '构建上下文。': '', + '为': 'When set to a', + '非空字符串': 'non-empty string', + '时，意味着使用': ', uses', + '进行对话，自动从': 'for the conversation. Automatically fetches history from the FastGPT database and uses the last', + '数据库取历史记录，并使用': 'message as the user question. Other messages are ignored. Ensure', + '数组最后一个内容作为用户问题，其余': 'is unique and under 250 characters (typically your system', + '会被忽略。请自行确保': "'s conversation ID).", + '唯一，长度小于250，通常可以是自己系统的对话框ID。': '', + '结构与': 'Structure matches', + '模式一致。': 'chat format.', + '如果传入，则会将该值作为本次对话的响应消息的 ID，FastGPT会自动将该 ID 存入数据库。请确保，在当前': 'If provided, this value will be used as the response message ID. FastGPT will store it in the database. Ensure', + '下，': 'is unique within the current', + '是唯一的。': '.', + '是否返回中间值（模块状态，响应的完整结果等），': 'Whether to return intermediate values (module status, complete response data, etc.).', + '模式': 'mode', + '下会通过': 'uses', + '进行区分，': 'to distinguish events.', + '非': 'Non-', + '结果保存在': 'results are in', + '中。': '.', + '模块变量，一个对象，会替换模块中，输入框内容里的': 'Module variables (object). Replaces', + '响应': 'Response', + '响应示例': 'Response Example', + '取值：': 'Event values:', + '返回给客户端的文本（最终会算作回答）': 'Text returned to client (counted as answer)', + '指定回复返回给客户端的文本（最终会算作回答）': 'Specified reply text returned to client (counted as answer)', + '执行工具': 'Tool execution', + '工具参数': 'Tool parameters', + '工具返回': 'Tool response', + '运行到的节点状态': 'Node status', + '节点完整响应': 'Complete node response', + '更新变量': 'Update variables', + '报错': 'Error', +} + +# Start translation +output = [] +for line in lines: + # Keep code blocks and special syntax as-is + if line.strip().startswith('```') or line.strip().startswith('curl') or line.strip().startswith('{') or line.strip().startswith('}') or line.strip().startswith('"') or line.strip().startswith('event:') or line.strip().startswith('data:') or '|' in line: + output.append(line) + continue + + # Translate frontmatter + if line.strip().startswith('title:'): + output.append('title: Chat API\n') + continue + if line.strip().startswith('description:'): + output.append('description: FastGPT OpenAPI Chat Interface\n') + continue + + # Keep MDX components as-is + if '' in line or '' in line or '
' in line or '
' in line: + # But translate the values + translated = line + if 'items={[' in line: + translated = translated.replace('基础请求示例', 'Basic Request Example') + translated = translated.replace('图片/文件请求示例', 'Image/File Request Example') + translated = translated.replace('参数说明', 'Parameters') + translated = translated.replace('响应示例', 'Response Example') + translated = translated.replace('请求示例', 'Request Example') + translated = translated.replace('输出获取', 'Output Retrieval') + translated = translated.replace('用户选择', 'User Selection') + translated = translated.replace('表单输入', 'Form Input') + translated = translated.replace('event值', 'Event Values') + if 'value=' in line: + translated = translated.replace('基础请求示例', 'Basic Request Example') + translated = translated.replace('图片/文件请求示例', 'Image/File Request Example') + translated = translated.replace('参数说明', 'Parameters') + translated = translated.replace('响应示例', 'Response Example') + translated = translated.replace('请求示例', 'Request Example') + translated = translated.replace('输出获取', 'Output Retrieval') + translated = translated.replace('用户选择', 'User Selection') + translated = translated.replace('表单输入', 'Form Input') + translated = translated.replace('event值', 'Event Values') + translated = translated.replace('detail=false,stream=false 响应', 'detail=false, stream=false Response') + translated = translated.replace('detail=false,stream=true 响应', 'detail=false, stream=true Response') + translated = translated.replace('detail=true,stream=false 响应', 'detail=true, stream=false Response') + translated = translated.replace('detail=true,stream=true 响应', 'detail=true, stream=true Response') + output.append(translated) + continue + + # Keep image paths + if '![' in line: + output.append(line) + continue + + # Keep comments + if '{/*' in line: + output.append(line) + continue + + # Translate headers + if line.startswith('#'): + if '如何获取 AppId' in line: + output.append('# How to Get AppId\n') + elif '发起对话' in line: + output.append('# Start a Conversation\n') + elif '请求对话 Agent 和工作流' in line: + output.append('## Request Chat Agent and Workflow\n') + elif '请求' in line and '###' in line: + output.append('### Request\n') + elif '响应' in line and '###' in line: + output.append('### Response\n') + elif '交互节点响应' in line: + output.append('### Interactive Node Response\n') + elif '交互节点继续运行' in line: + output.append('### Continue Interactive Node\n') + elif '请求插件' in line: + output.append('## Request Plugin\n') + elif '请求示例' in line: + output.append('### Request Example\n') + elif '响应示例' in line: + output.append('### Response Example\n') + elif '对话 CRUD' in line: + output.append('# Chat CRUD\n') + elif '历史记录' in line: + output.append('## History\n') + elif '获取某个应用历史记录' in line: + output.append('### Get Application History\n') + elif '修改某个对话的标题' in line: + output.append('### Update Chat Title\n') + elif '置顶 / 取消置顶' in line: + output.append('### Pin / Unpin\n') + elif '删除某个历史记录' in line: + output.append('### Delete History\n') + elif '清空所有历史记录' in line: + output.append('### Clear All History\n') + elif '对话记录' in line: + output.append('## Chat Records\n') + elif '获取单个对话初始化信息' in line: + output.append('### Get Chat Initialization Info\n') + elif '获取对话记录列表' in line: + output.append('### Get Chat Record List\n') + elif '获取单个对话记录运行详情' in line: + output.append('### Get Chat Record Details\n') + elif '删除对话记录' in line: + output.append('### Delete Chat Record\n') + elif '点赞 / 取消点赞' in line: + output.append('### Like / Unlike\n') + elif '点踩 / 取消点踩' in line: + output.append('### Dislike / Remove Dislike\n') + elif '猜你想问' in line: + output.append('## Question Suggestions\n') + else: + output.append(line) + continue + + # Translate bullet points and regular text + translated = line + + # Common translations + translated = translated.replace('该接口的 API Key 需使用`应用特定的 key`，否则会报错。', 'This API requires an application-specific API key, or it will return an error.') + translated = translated.replace('有些包调用时，`BaseUrl`需要添加`v1`路径，有些不需要，如果出现404情况，可补充`v1`重试。', 'Some packages require adding `v1` to the `BaseUrl`. If you get a 404 error, try adding `v1` and retry.') + translated = translated.replace('可在应用详情的路径里获取 AppId。', 'You can find the AppId in your application details URL.') + translated = translated.replace('`v1`对话接口兼容`GPT`的接口！如果你的项目使用的是标准的`GPT`官方接口，可以直接通过修改`BaseUrl`和 `Authorization`来访问 FastGpt 应用，不过需要注意下面几个规则：', 'The `v1` chat API is compatible with the `GPT` interface! If you\'re using the standard `GPT` official API, you can access FastGPT by simply changing the `BaseUrl` and `Authorization`. However, note these rules:') + translated = translated.replace('传入的`model`，`temperature`等参数字段均无效，这些字段由编排决定，不会根据 API 参数改变。', 'Parameters like `model` and `temperature` are ignored. These values are determined by your workflow configuration.') + translated = translated.replace('不会返回实际消耗`Token`值，如果需要，可以设置`detail=true`，并手动计算 `responseData` 里的`tokens`值。', "Won't return actual `Token` consumed. If needed, set `detail=true` and manually calculate `tokens` from `responseData`.") + translated = translated.replace('仅`messages`有部分区别，其他参数一致。', 'Only `messages` differs slightly; other parameters are the same.') + translated = translated.replace('目前不支持上传文件，需上传到自己的对象存储中，获取对应的文件链接。', 'Direct file uploads are not supported. Upload files to your object storage and provide the URL.') + translated = translated.replace('图片链接', 'Image URL') + translated = translated.replace('文件名', 'Filename') + translated = translated.replace('文档链接，支持 txt md html word pdf ppt csv excel', 'Document URL. Supports txt, md, html, word, pdf, ppt, csv, excel') + translated = translated.replace('入参：', '**Request Parameters:**') + translated = translated.replace('出参：', '**Response Parameters:**') + translated = translated.replace('应用Id', 'Application ID') + translated = translated.replace('应用 Id', 'Application ID') + translated = translated.replace('历史记录 Id', 'History ID') + translated = translated.replace('对话 Id', 'Chat ID') + translated = translated.replace('对话记录 Id', 'Chat Record ID') + translated = translated.replace('自定义对话名', 'Custom chat title') + translated = translated.replace('是否置顶，ture 置顶，false 取消置顶', 'Whether to pin. true = pin, false = unpin') + translated = translated.replace('偏移量，即从第几条数据开始取', 'Offset (starting position)') + translated = translated.replace('记录数量', 'Number of records') + translated = translated.replace('对话源。source=api，表示获取通过 API 创建的对话（不会获取到页面上的对话记录）', 'Chat source. source=api means get API-created chats only (excludes web UI chats)') + translated = translated.replace('仅会情况通过 API Key 创建的对话历史记录，不会清空在线使用、分享链接等其他来源的对话历史记录。', 'Only clears chat history created via API Key. Does not clear history from web UI, share links, or other sources.') + translated = translated.replace('指的是某个 chatId 下的对话记录操作。', 'Operations on chat records under a specific chatId.') + translated = translated.replace('偏移量', 'Offset') + translated = translated.replace('是否读取自定义反馈（可选）', 'Whether to load custom feedbacks (optional)') + translated = translated.replace('用户点赞时的信息（可选），取消点赞时不填此参数即可', 'User feedback when liking (optional). Omit to unlike.') + translated = translated.replace('用户点踩时的信息（可选），取消点踩时不填此参数即可', 'User feedback when disliking (optional). Omit to remove dislike.') + translated = translated.replace('新版猜你想问，必须包含 appId 和 chatId 的参数才可以进行使用。会自动根据 chatId 去拉取最近 6 轮对话记录作为上下文来引导回答。', 'The new question suggestion feature requires both appId and chatId parameters. It automatically fetches the last 6 conversation turns from chatId as context.') + translated = translated.replace('参数名', 'Parameter') + translated = translated.replace('类型', 'Type') + translated = translated.replace('必填', 'Required') + translated = translated.replace('说明', 'Description') + translated = translated.replace('自定义配置，不传的话，则会根据 appId，取最新发布版本的配置', 'Custom configuration. If not provided, uses the latest published version config from appId') + translated = translated.replace('以下接口可使用任意`API Key`调用。', 'The following APIs can be called with any `API Key`.') + translated = translated.replace('以上版本才能使用', 'and above') + translated = translated.replace('重要字段', '**Important Fields**') + translated = translated.replace('指一个应用下，某一个对话窗口的 ID', 'The ID of a conversation window under an application') + translated = translated.replace('指一个对话窗口下，某一个对话记录的 ID', 'The ID of a chat record under a conversation window') + translated = translated.replace('如果工作流中包含交互节点，依然是调用该 API 接口，需要设置`detail=true`，并可以从`event=interactive`的数据中获取交互节点的配置信息。如果是`stream=false`，则可以从 choice 中获取`type=interactive`的元素，获取交互节点的选择信息。', 'If your workflow contains interactive nodes, still call this API with `detail=true`. Get interactive node config from `event=interactive` data. For `stream=false`, find `type=interactive` elements in choices.') + translated = translated.replace('当你调用一个带交互节点的工作流时，如果工作流遇到了交互节点，那么会直接返回，你可以得到下面的信息：', 'When calling a workflow with interactive nodes, if an interactive node is encountered, it returns immediately with this info:') + translated = translated.replace('紧接着上一节，当你接收到交互节点信息后，可以根据这些数据进行 UI 渲染，引导用户输入或选择相关信息。然后需要再次发起对话，来继续工作流。调用的接口与仍是该接口，你需要按以下格式来发起请求：', 'After receiving interactive node info, render your UI to guide user input or selection. Then call this API again to continue the workflow. Use this format:') + translated = translated.replace('对于用户选择，你只需要直接传递一个选择的结果给 messages 即可。', 'For user selection, simply pass the selected value to messages.') + translated = translated.replace('表单输入稍微麻烦一点，需要将输入的内容，以对象形式并序列化成字符串，作为`messages`的值。对象的 key 对应表单的 key，value 为用户输入的值。务必确保`chatId`是一致的。', 'Form input is slightly more complex. Serialize the input as a JSON string for `messages`. Object keys match form keys, values are user inputs. Ensure `chatId` is consistent.') + translated = translated.replace('插件的接口与对话接口一致，仅请求参数略有区别，有以下规定：', 'Plugin API is identical to chat API, with slight parameter differences:') + translated = translated.replace('调用插件类型的应用时，接口默认为`detail`模式。', 'When calling plugin-type applications, the API defaults to `detail` mode.') + translated = translated.replace('无需传入 `chatId`，因为插件只能运行一轮。', 'No need to pass `chatId` since plugins run only once.') + translated = translated.replace('无需传入`messages`。', 'No need to pass `messages`.') + translated = translated.replace('通过传递`variables`来代表插件的输入。', 'Pass `variables` to represent plugin inputs.') + translated = translated.replace('通过获取`pluginData`来获取插件输出。', 'Get plugin outputs from `pluginData`.') + translated = translated.replace('插件的输出可以通过查找`responseData`中, `moduleType=pluginOutput`的元素，其`pluginOutput`是插件的输出。', 'Find plugin output by locating `moduleType=pluginOutput` in `responseData`. Its `pluginOutput` contains the output.') + translated = translated.replace('流输出，仍可以通过`choices`进行获取。', 'Stream output is still available via `choices`.') + translated = translated.replace('插件的输出可以通过获取`event=flowResponses`中的字符串，并将其反序列化后得到一个数组。同样的，查找 `moduleType=pluginOutput`的元素，其`pluginOutput`是插件的输出。', 'Get plugin output by deserializing the `event=flowResponses` string into an array. Find `moduleType=pluginOutput` element; its `pluginOutput` contains the output.') + translated = translated.replace('流输出，仍和对话接口一样获取。', 'Stream output works the same as chat API.') + translated = translated.replace('后新版接口', 'New API (version') + + # Handle parameter descriptions with dashes + if translated.strip().startswith('- '): + # Keep as-is if it's already translated or contains code + if '`' in translated or 'ID' in translated or 'URL' in translated: + output.append(translated) + continue + + # Translate common parameter patterns + translated = translated.replace('- appId:', '- appId:') + translated = translated.replace('- chatId:', '- chatId:') + translated = translated.replace('- dataId:', '- dataId:') + translated = translated.replace('- offset:', '- offset:') + translated = translated.replace('- pageSize:', '- pageSize:') + translated = translated.replace('- source:', '- source:') + translated = translated.replace('- customTitle:', '- customTitle:') + translated = translated.replace('- top:', '- top:') + translated = translated.replace('- contentId:', '- contentId:') + translated = translated.replace('- userGoodFeedback:', '- userGoodFeedback:') + translated = translated.replace('- userBadFeedback:', '- userBadFeedback:') + translated = translated.replace('- loadCustomFeedbacks:', '- loadCustomFeedbacks:') + translated = translated.replace('- questionGuide:', '- questionGuide:') + translated = translated.replace('- dateStart:', '- dateStart:') + translated = translated.replace('- dateEnd:', '- dateEnd:') + translated = translated.replace('- userTimespan:', '- userTimespan:') + translated = translated.replace('- chatTimespan:', '- chatTimespan:') + translated = translated.replace('- appTimespan:', '- appTimespan:') + translated = translated.replace('- userData:', '- userData:') + translated = translated.replace('- chatData:', '- chatData:') + translated = translated.replace('- appData:', '- appData:') + translated = translated.replace('- timestamp:', '- timestamp:') + translated = translated.replace('- summary:', '- summary:') + translated = translated.replace('- userCount:', '- userCount:') + translated = translated.replace('- newUserCount:', '- newUserCount:') + translated = translated.replace('- retentionUserCount:', '- retentionUserCount:') + translated = translated.replace('- points:', '- points:') + translated = translated.replace('- sourceCountMap:', '- sourceCountMap:') + translated = translated.replace('- chatItemCount:', '- chatItemCount:') + translated = translated.replace('- chatCount', '- chatCount') + translated = translated.replace('- errorCount', '- errorCount') + translated = translated.replace('- goodFeedBackCount', '- goodFeedBackCount') + translated = translated.replace('- badFeedBackCount', '- badFeedBackCount:') + translated = translated.replace('- totalResponseTime', '- totalResponseTime') + + # Translate descriptions + translated = translated.replace('开始时间', 'Start time') + translated = translated.replace('结束时间', 'End time') + translated = translated.replace('日志来源', 'Log source') + translated = translated.replace('用户留存偏移量', 'User retention offset') + translated = translated.replace('用户数据时间跨度', 'User data timespan') + translated = translated.replace('对话数据时间跨度', 'Chat data timespan') + translated = translated.replace('应用数据时间跨度', 'Application data timespan') + translated = translated.replace('用户数据数组', 'User data array') + translated = translated.replace('对话数据数组', 'Chat data array') + translated = translated.replace('应用数据数组', 'Application data array') + translated = translated.replace('时间戳', 'Timestamp') + translated = translated.replace('汇总数据对象', 'Summary data object') + translated = translated.replace('活跃用户数量', 'Active user count') + translated = translated.replace('新用户数量', 'New user count') + translated = translated.replace('留存用户数量', 'Retained user count') + translated = translated.replace('总积分消耗', 'Total points consumed') + translated = translated.replace('各来源用户数量', 'User count by source') + translated = translated.replace('对话次数', 'Chat message count') + translated = translated.replace('会话次数', 'Session count') + translated = translated.replace('错误对话次数', 'Error count') + translated = translated.replace('好评反馈数量', 'Positive feedback count') + translated = translated.replace('差评反馈数量', 'Negative feedback count') + translated = translated.replace('总响应时间', 'Total response time') + + output.append(translated) + +# Write the translated file +with open('chat.en.mdx', 'w', encoding='utf-8') as f: + f.writelines(output) + +print("Translation complete!") diff --git a/document/content/docs/protocol/index.en.mdx b/document/content/docs/protocol/index.en.mdx new file mode 100644 index 0000000000..0e1d469064 --- /dev/null +++ b/document/content/docs/protocol/index.en.mdx @@ -0,0 +1,8 @@ +--- +title: Protocols +description: FastGPT Protocols +--- + +import { Redirect } from '@/components/docs/Redirect'; + + diff --git a/document/content/docs/protocol/meta.en.json b/document/content/docs/protocol/meta.en.json new file mode 100644 index 0000000000..5f5856811c --- /dev/null +++ b/document/content/docs/protocol/meta.en.json @@ -0,0 +1,11 @@ +{ + "title": "Legal", + "root": true, + "description": "Legal", + "pages": [ + "open-source", + "terms", + "privacy" + ], + "order": 3 +} diff --git a/document/content/docs/protocol/open-source.en.mdx b/document/content/docs/protocol/open-source.en.mdx index 62b0fa9bc9..6f9ed08a6d 100644 --- a/document/content/docs/protocol/open-source.en.mdx +++ b/document/content/docs/protocol/open-source.en.mdx @@ -3,18 +3,18 @@ title: Open Source License description: FastGPT Open Source License --- -The FastGPT project is open-sourced under the Apache License 2.0, but includes the following additional conditions: +The FastGPT project is open-sourced under the Apache License 2.0, with the following additional conditions: -- FastGPT may be used for commercial purposes, such as operating it as "backend-as-a-service" for other applications or providing it as an enterprise development platform. However, you must contact us to obtain a commercial license under the following circumstances: +- FastGPT may be used commercially -- for example, as a backend-as-a-service for other applications or as an application development platform for enterprises. However, a commercial license is required when the following conditions apply: - - Multi-tenant SaaS Service: Unless explicit written authorization from FastGPT is obtained, you may not use the source code of fastgpt.io to operate a multi-tenant SaaS service similar to fastgpt.io. - - Logo and Copyright Information: You may not remove or modify the FastGPT logo or copyright information within the FastGPT console. + - Multi-tenant SaaS: You may not use the fastgpt.io source code to operate a multi-tenant SaaS service similar to fastgpt.io without explicit written authorization from FastGPT. + - Logo and copyright: You may not remove or modify the logo or copyright information in the FastGPT console. - For commercial licensing inquiries, please contact us via email at dennis@sealos.io. + Contact us at dennis@sealos.io for licensing inquiries. -- As a contributor, you must agree to allow your contributions to: +- As a contributor, you agree that your contributed code may be used for the following purposes: - - Be used under license terms that FastGPT may adjust to stricter or more lenient conditions. - - Support commercial use cases such as the FastGPT cloud service. + - The maintainers reserve the right to change the open source license to a more restrictive or more permissive one. + - It may be used for commercial purposes, such as FastGPT's cloud service. -Outside of these specific terms, all other rights and restrictions are governed by the Apache License 2.0. All other details can be found in the full Apache License 2.0 text. The interactive design of this product is protected by patent. © 2023 Sealos. +All other rights and restrictions follow the Apache License 2.0. For full details, refer to the complete Apache License 2.0 text. The interaction design of this product is protected by design patents. © 2023 Sealos. diff --git a/document/content/docs/protocol/privacy.en.mdx b/document/content/docs/protocol/privacy.en.mdx index a312675bba..27aa2d719f 100644 --- a/document/content/docs/protocol/privacy.en.mdx +++ b/document/content/docs/protocol/privacy.en.mdx @@ -3,60 +3,60 @@ title: Privacy Policy description: FastGPT Privacy Policy --- -Last Updated: March 3, 2024 +Last updated: March 3, 2024 -We place a high value on your privacy protection. When using FastGPT cloud services (hereinafter referred to as "the Service"), we will collect, use, disclose, and protect your personal information in accordance with this policy. Please read and understand this privacy policy carefully. +We take your privacy seriously. This policy describes how we collect, use, disclose, and protect your personal information when you use the FastGPT cloud service ("the Service"). Please read and fully understand this Privacy Policy before using the Service. **Information We May Collect** -1. During registration or use of the Service, we may collect your personal information such as name, phone number, email address, and address. -2. Information generated during your use of the Service, including operation logs, IP addresses, device models, etc. -3. We may use Cookies or other technologies to collect and store information about your access to the Service to improve your user experience. +1. When you register for or use the Service, we may collect personal information such as your name, phone number, email address, and mailing address. +2. Information generated during your use of the Service, including operation logs, IP addresses, and device models. +3. We may use cookies or similar technologies to collect and store information about your visits to improve your experience. **How We Use Collected Information** -1. We process user personal information in accordance with legal requirements and agreements with users. -2. We may use the collected information to improve service quality, develop new products or features. -3. We may use the collected information to send you notifications or advertisements related to the Service. +1. We process your personal information in accordance with applicable laws and our agreements with you. +2. We may use collected information to improve service quality, develop new products or features, and similar purposes. +3. We may use collected information to send you Service-related notifications or advertisements. -**Disclosure of Information** +**Information Disclosure** 1. We will not disclose your personal information to third parties unless: - 1. You have previously consented; - 2. Required by law; - 3. To safeguard our legitimate rights or those of other users. + 1. You have given prior consent; + 2. Required by law or regulation; + 3. Necessary to protect our legitimate interests or those of other users. -2. We may share your personal information with affiliated companies or partners, but will implement confidentiality measures to ensure information security. +2. We may share your personal information with affiliates and partners, subject to appropriate confidentiality measures to ensure information security. -**Information Security** +**Information Protection** -1. We employ various security measures, including encryption and access controls, to protect your personal information from unauthorized access, use, or leaks. -2. We periodically assess the security of collected, stored, and processed personal information to ensure ongoing safety. -3. In the event of a personal information leak or security incident, we will immediately activate emergency plans and notify you within the scope prescribed by law. -4. We do **not** use your data for additional backups or model training purposes. -5. Data deletion performed on our Service is irreversible physical deletion. If non-physical deletion operations are allowed, we will explicitly label this in the Service. +1. We employ various security measures, including encryption and access controls, to protect your personal information from unauthorized access, use, or disclosure. +2. We regularly assess the security of the personal information we collect, store, and process. +3. In the event of a data breach or other security incident, we will immediately activate our emergency response plan and notify you promptly as required by applicable law. +4. We do not use your data for additional backup storage or model training. +5. Data deletions you perform in the Service are physical deletions and cannot be recovered. Any non-physical deletion operations will be clearly noted in the Service. -**User Rights** +**Your Rights** -1. You may request to view, modify, or delete your personal information at any time. -2. You may refuse our collection of personal information, but this may limit your access to certain Service features. -3. You may request us to stop processing your personal information, but this may prevent you from continuing to use the Service. +1. You may access, correct, or delete your personal information at any time. +2. You may refuse our collection of your personal information, though this may limit your access to certain features. +3. You may request that we stop processing your personal information, though this may prevent you from continuing to use the Service. -**Privacy Policy Updates** +**Policy Updates** -1. We may revise this privacy policy. If changes occur, we will post the updated version on the Service page. Your continued use of the Service after such updates implies consent to the revised terms. -2. We encourage you to review this policy periodically to stay informed about how we protect your information. +1. We may update this Privacy Policy from time to time. Changes will be posted on the Service page. Continued use of the Service constitutes acceptance of the updated policy. +2. We encourage you to review this Privacy Policy periodically. -**Minor Protection** +**Protection of Minors** -We take child privacy protection seriously. If you are under 18, please use the Service under parental supervision and ensure your guardian properly handles your personal information. +We take the protection of minors' personal information seriously. If you are a minor, please use the Service under the guidance of a guardian, and have your guardian help you handle personal information appropriately. -**Cross-Border Data Transfer** +**Cross-Border Data Transfers** -Due to servers potentially being located in different countries/regions, you agree that your personal information may be transmitted, stored, and processed in other jurisdictions to provide you with the Service. We will implement appropriate safeguards to ensure cross-border data remains adequately protected. +Our servers may be located in different countries or regions. You agree that we may transfer your personal information to other jurisdictions for storage and processing as needed to provide the Service. We will take appropriate measures to ensure cross-border data transfers remain adequately protected. **Contact Us** -1. For any questions, suggestions, or complaints about this policy, contact us at: archer@fastgpt.io. -2. We will respond promptly and address your concerns. +1. If you have any questions, suggestions, or complaints about this Privacy Policy, contact us at: archer@fastgpt.io. +2. We will respond and address your concerns as soon as possible. diff --git a/document/content/docs/protocol/terms.en.mdx b/document/content/docs/protocol/terms.en.mdx index c52a14bfba..6c7a6e2075 100644 --- a/document/content/docs/protocol/terms.en.mdx +++ b/document/content/docs/protocol/terms.en.mdx @@ -1,75 +1,70 @@ --- -title: Service Agreement -description: FastGPT Service Agreement +title: Terms of Service +description: FastGPT Terms of Service --- -Last Updated: March 3, 2024 +Last updated: March 3, 2024 -This FastGPT Service Agreement constitutes the terms and conditions agreed between you and ZHUHAI Sealos CLOUD COMPUTING CO., LTD. (referred to as "Sealos" or "the Company") regarding the use of FastGPT cloud services (hereinafter "the Service"). Please read and fully understand all clauses carefully, especially those related to liability exemptions, limitations on your rights, dispute resolution, and governing law. If you disagree with any terms, you shall not register or use the Service. +This FastGPT Terms of Service agreement ("Agreement") is between you and Zhuhai Huanjie Cloud Computing Co., Ltd. ("we," "us," or "the Company") regarding your use of the FastGPT cloud service ("the Service"). Please read all terms carefully, especially those regarding liability limitations, restrictions on your rights, dispute resolution, and applicable law. If you do not agree with any part of this Agreement, do not register for or use the Service. -**Article 1 Service Content** +**Article 1: Service Content** -1. Sealos will provide you with internet-based information technology services, including but not limited to storage, computing, and network transmission. -2. Sealos may send you updates and announcements via in-platform messages, emails, or SMS about the latest service developments. -3. Sealos will provide relevant technical support and customer service to assist with your Service usage. -4. Sealos guarantees a monthly service availability of no less than 99%. +1. We provide internet-based information technology services including storage, computing, and network transmission. +2. We may send you updates via in-app messages, email, or SMS from time to time. +3. We provide technical support and customer service to help you get the most out of the Service. +4. We guarantee a monthly service availability of no less than 99%. -**Article 2 Account Registration and Management** +**Article 2: Registration and Account Management** -1. You must register an account to use the Service. You confirm that all registration information provided is true, accurate, and complete, and agree to update it promptly. -2. You are responsible for safeguarding your account credentials, and accountable for all activities conducted through your account. If you discover unauthorized use, please immediately change your password or contact us. -3. Sealos reserves the right to review accounts and may suspend or terminate Service provision if accounts are found to violate laws, regulations, or this Agreement. +1. You must register an account before using the Service. You warrant that all registration information is true, accurate, and complete, and that you will keep it up to date. +2. You are responsible for safeguarding your account credentials and for all activity under your account. If you discover unauthorized use, change your password immediately or contact us. +3. We reserve the right to review your account. If we detect abnormal or illegal activity, we may suspend or terminate your access. -**Article 3 Service Usage Rules** +**Article 3: Usage Rules** -1. You shall not use the Service for any illegal activities or acts infringing upon others' rights, including but not limited to intellectual property infringement, unauthorized disclosure of confidential information, etc. -2. You shall not engage in malicious account registration through unreasonable means, including but not limited to purposes of profit-making, speculation, or arbitrage. -3. You shall not use the Service to spread illegal, harmful, or malicious software or information. -4. You must abide by all applicable laws/regulations and this Agreement, bearing full responsibility for published information and results from Service usage. -5. It is prohibited to generate content through Sealos' connected models that may harm individuals or society. Ensuring platform safety is critical for stable operations. Violations (including but not limited to the following) will result in immediate account termination without refund: +1. You may not use the Service for illegal activities or to infringe on the rights of others, including but not limited to intellectual property infringement and unauthorized disclosure of trade secrets. +2. You may not register accounts through malicious means, including but not limited to profiteering, speculation, or arbitrage. +3. You may not use the Service to distribute illegal, harmful, or malicious software or information. +4. You must comply with all applicable laws and this Agreement, and you bear full responsibility for all content you publish and all consequences arising from your use of the Service. +5. Using our connected model services to generate content that may harm individuals or society is prohibited. Platform safety is critical for long-term stable operations. Any account found using the platform's model capabilities to generate or distribute prohibited content will be immediately banned with no refund of account balance. Prohibited content includes but is not limited to: - Exploitation and Abuse - - Content describing, depicting, or promoting child sexual exploitation/abuse, regardless of legal status. This includes content creating contexts for child pornography. - - Content describing or meant to cultivate relationships with children for exploitative purposes, especially sexual exploitation including grooming. + - Content that describes, depicts, or promotes child sexual exploitation or abuse, regardless of legality. This includes content involving or sexualizing minors. + - Content used for grooming children. Grooming refers to adults building relationships with children for the purpose of exploitation, particularly sexual exploitation, trafficking, or other forms of exploitation. - Non-Consensual Intimate Content - - Prohibiting content describing, providing, or promoting non-consensual intimate activities. - - Sexual Services - - Prohibiting content describing, providing, or promoting commercial activity and sexual services, including encouraging or facilitating real-world sexual engagement. - - Human Trafficking - - Prohibiting content related to human trafficking purposes, including recruitment, facilitating transportation, funding, or enabling exploitation such as forced labor, domestic servitude, forced marriages, or forced medical procedures. - - Self-Harm/Suicide - - Prohibiting content depicting, praising, supporting, promoting, glorifying, encouraging, or instructing self-harm/suicide behaviors. - - Violent Content - - Prohibiting content describing or depicting graphic violence or bloodshed. - - Prohibiting content advocating terrorism; praising/supporting terrorist organizations/actors; encouraging violence; or assisting such organizations in recruitment. - - Prohibiting content threatening violence or inciting harm against others. - - Hate Speech & Discrimination - - Prohibiting content attacking, defaming, intimidating, degrading, or excluding individuals/groups based on actual or perceived characteristics like race, gender, religious belief, disability, caste, etc. - - Prohibiting threatening, abusive language/images targeting individuals/groups; advocating physical harm; or other abusive behaviors (e.g., stalking). - - Fraudulent Misinformation - - Prohibiting intentionally deceptive content that may harm public interest, particularly relating to health, safety, electoral integrity, or civil participation. - - Malicious Software - - Prohibiting content directly supporting illegal attacks or technical harm, such as providing malicious executable files, orchestrating DDoS attacks, or managing C2 servers. + - Content that describes, provides, or promotes non-consensual intimate activities. + - Content that describes, provides, promotes, or solicits commercial sexual activities and services, including encouraging or facilitating real sexual activities. + - Content that describes or facilitates human trafficking, including recruiting, transporting, paying for, or enabling exploitation such as forced labor, domestic servitude, indentured servitude, forced marriage, or forced medical procedures. + - Self-Harm and Suicide: Content that describes, praises, supports, promotes, glorifies, encourages, or instructs self-harm or suicide. + - Violent Content and Behavior + - Content that describes, depicts, or promotes graphic violence or gore. + - Content depicting terrorist acts; praising or supporting terrorist organizations, actors, or ideologies; encouraging terrorist activities; providing aid to terrorist organizations; or assisting in terrorist recruitment. + - Content that advocates or promotes violence against others through threats or incitement. + - Hate Speech and Discrimination + - Content that attacks, defames, intimidates, degrades, targets, or excludes individuals or groups based on characteristics such as race, ethnicity, nationality, gender, gender identity, sexual orientation, religion, age, disability, caste, or any other characteristic associated with systemic bias or marginalization. + - Content that threatens, intimidates, insults, or degrades individuals or groups through language or imagery, or promotes physical harm or abusive behavior such as stalking. + - Content that is intentionally deceptive and may harm the public interest, including false content related to health, safety, electoral integrity, or civic participation. + - Content that directly supports malicious software activities or illegal attacks, such as distributing malicious executables, organizing denial-of-service attacks, or managing command-and-control servers. -**Article 4 Fees and Payment** +**Article 4: Fees and Payment** -1. You agree to pay fees associated with the Service, with pricing subject to our official published rates. -2. Sealos reserves the right to adjust Service fees based on operational costs and market conditions. Updated pricing will apply according to the rate at the time of payment. +1. You agree to pay all fees associated with the Service based on our published pricing. +2. We may adjust pricing based on operational costs and market conditions. The price at the time of payment applies. -**Article 5 Liability Exemption and Limitations** +**Article 5: Disclaimer and Liability Limitations** -1. The Service is provided under existing technical conditions and cannot be guaranteed to be entirely free of issues or satisfy all your requirements. -2. Sealos will not be liable for data loss/damage caused by user operational errors. -3. Given the cross-border nature of generative AI, all users must adhere strictly to local laws. Use violating Sealos' Acceptable Use Policy (including but not limited to prohibited uses under legal statutes, government orders, or infringing others' rights) will result in self-assumed responsibility by the user. Sealos disclaims responsibility for issues arising from customer use: +1. The Service is provided on an as-is basis given existing technology and conditions. We do not guarantee the Service will be completely fault-free or meet all your requirements. +2. We are not liable for data loss or damage caused by your own operational errors. +3. Due to the nature of generative AI, regulations vary by country. All users must comply with the laws of their jurisdiction. If you use the Service in violation of FastGPT's Acceptable Use Policy -- including any use prohibited by law, regulation, or government order, or any use that infringes on the rights of others -- you assume full responsibility. We are not liable for issues arising from customer use. Below is a link to China's regulations on generative AI: -[Interim Measures for the Administration of Generative AI Services in China](http://www.cac.gov.cn/2023-04/11/c_1682854275475410.htm) +[Interim Measures for the Administration of Generative Artificial Intelligence Services (Draft for Comment)](http://www.cac.gov.cn/2023-04/11/c_1682854275475410.htm) -**Article 6 Intellectual Property Rights** +**Article 6: Intellectual Property** -1. Sealos holds all intellectual property rights regarding the Service, software, technology, and documentation. Without express permission, you may not copy, distribute, rent, or reverse-engineer such materials. -2. You retain ownership of intellectual property rights for all data/content (including but not limited to files, images) generated through Service usage. Sealos will not use, copy, or modify your materials. -3. Content/data from other Service users are owned by their original creators. You may not use, copy, or modify such materials without explicit consent. +1. We own all intellectual property rights to the Service and related software, technology, and documentation. You may not copy, distribute, rent, reverse-engineer, or otherwise exploit these materials without our express authorization. +2. You own all intellectual property rights to data and content (including files, images, etc.) you create through the Service. We will not use, copy, or modify your data or content. +3. Data and content from other users belong to those users. You may not use, copy, or modify their data or content without their permission. -**Article 7 Additional Provisions** +**Article 7: Miscellaneous** -1. If any clause is deemed unlawful or invalid, the remaining provisions shall remain enforceable. -2. Sealos retains final authority in interpreting this Agreement and privacy policies. For any inquiries, please contact us at archer@fastgpt.io. +1. If any provision of this Agreement is deemed invalid due to conflict with applicable law, the remaining provisions remain in full force and effect. +2. The Company reserves the right of final interpretation of this Agreement and the Privacy Policy. For questions, contact us at: archer@fastgpt.io. diff --git a/document/content/docs/toc.en.mdx b/document/content/docs/toc.en.mdx index dcfa960dbd..6a47d12372 100644 --- a/document/content/docs/toc.en.mdx +++ b/document/content/docs/toc.en.mdx @@ -3,7 +3,201 @@ title: FastGPT Toc description: FastGPT Toc --- +- [/en/docs/faq/app](/en/docs/faq/app) +- [/en/docs/faq/chat](/en/docs/faq/chat) +- [/en/docs/faq/dataset](/en/docs/faq/dataset) +- [/en/docs/faq/error](/en/docs/faq/error) +- [/en/docs/faq/external_channel_integration](/en/docs/faq/external_channel_integration) +- [/en/docs/faq/other](/en/docs/faq/other) +- [/en/docs/faq/points_consumption](/en/docs/faq/points_consumption) +- [/en/docs/introduction/cloud](/en/docs/introduction/cloud) +- [/en/docs/introduction/commercial](/en/docs/introduction/commercial) +- [/en/docs/introduction/development/configuration](/en/docs/introduction/development/configuration) +- [/en/docs/introduction/development/custom-models/bge-rerank](/en/docs/introduction/development/custom-models/bge-rerank) +- [/en/docs/introduction/development/custom-models/chatglm2](/en/docs/introduction/development/custom-models/chatglm2) +- [/en/docs/introduction/development/custom-models/chatglm2-m3e](/en/docs/introduction/development/custom-models/chatglm2-m3e) +- [/en/docs/introduction/development/custom-models/m3e](/en/docs/introduction/development/custom-models/m3e) +- [/en/docs/introduction/development/custom-models/marker](/en/docs/introduction/development/custom-models/marker) +- [/en/docs/introduction/development/custom-models/mineru](/en/docs/introduction/development/custom-models/mineru) +- [/en/docs/introduction/development/custom-models/ollama](/en/docs/introduction/development/custom-models/ollama) +- [/en/docs/introduction/development/custom-models/xinference](/en/docs/introduction/development/custom-models/xinference) +- [/en/docs/introduction/development/design/dataset](/en/docs/introduction/development/design/dataset) +- [/en/docs/introduction/development/design/design_plugin](/en/docs/introduction/development/design/design_plugin) +- [/en/docs/introduction/development/docker](/en/docs/introduction/development/docker) +- [/en/docs/introduction/development/faq](/en/docs/introduction/development/faq) +- [/en/docs/introduction/development/intro](/en/docs/introduction/development/intro) +- [/en/docs/introduction/development/migration/docker_db](/en/docs/introduction/development/migration/docker_db) +- [/en/docs/introduction/development/migration/docker_mongo](/en/docs/introduction/development/migration/docker_mongo) +- [/en/docs/introduction/development/modelConfig/ai-proxy](/en/docs/introduction/development/modelConfig/ai-proxy) +- [/en/docs/introduction/development/modelConfig/intro](/en/docs/introduction/development/modelConfig/intro) +- [/en/docs/introduction/development/modelConfig/one-api](/en/docs/introduction/development/modelConfig/one-api) +- [/en/docs/introduction/development/modelConfig/ppio](/en/docs/introduction/development/modelConfig/ppio) +- [/en/docs/introduction/development/modelConfig/siliconCloud](/en/docs/introduction/development/modelConfig/siliconCloud) +- [/en/docs/introduction/development/object-storage](/en/docs/introduction/development/object-storage) +- [/en/docs/introduction/development/proxy/cloudflare](/en/docs/introduction/development/proxy/cloudflare) +- [/en/docs/introduction/development/proxy/http_proxy](/en/docs/introduction/development/proxy/http_proxy) +- [/en/docs/introduction/development/proxy/nginx](/en/docs/introduction/development/proxy/nginx) +- [/en/docs/introduction/development/sealos](/en/docs/introduction/development/sealos) +- [/en/docs/introduction/development/signoz](/en/docs/introduction/development/signoz) +- [/en/docs/introduction/guide/DialogBoxes/htmlRendering](/en/docs/introduction/guide/DialogBoxes/htmlRendering) +- [/en/docs/introduction/guide/DialogBoxes/quoteList](/en/docs/introduction/guide/DialogBoxes/quoteList) +- [/en/docs/introduction/guide/admin/sso](/en/docs/introduction/guide/admin/sso) +- [/en/docs/introduction/guide/admin/teamMode](/en/docs/introduction/guide/admin/teamMode) +- [/en/docs/introduction/guide/course/ai_settings](/en/docs/introduction/guide/course/ai_settings) +- [/en/docs/introduction/guide/course/chat_input_guide](/en/docs/introduction/guide/course/chat_input_guide) +- [/en/docs/introduction/guide/course/fileInput](/en/docs/introduction/guide/course/fileInput) +- [/en/docs/introduction/guide/course/quick-start](/en/docs/introduction/guide/course/quick-start) +- [/en/docs/introduction/guide/dashboard/basic-mode](/en/docs/introduction/guide/dashboard/basic-mode) +- [/en/docs/introduction/guide/dashboard/evaluation](/en/docs/introduction/guide/dashboard/evaluation) +- [/en/docs/introduction/guide/dashboard/gapier](/en/docs/introduction/guide/dashboard/gapier) +- [/en/docs/introduction/guide/dashboard/intro](/en/docs/introduction/guide/dashboard/intro) +- [/en/docs/introduction/guide/dashboard/mcp_server](/en/docs/introduction/guide/dashboard/mcp_server) +- [/en/docs/introduction/guide/dashboard/mcp_tools](/en/docs/introduction/guide/dashboard/mcp_tools) +- [/en/docs/introduction/guide/dashboard/workflow/ai_chat](/en/docs/introduction/guide/dashboard/workflow/ai_chat) +- [/en/docs/introduction/guide/dashboard/workflow/content_extract](/en/docs/introduction/guide/dashboard/workflow/content_extract) +- [/en/docs/introduction/guide/dashboard/workflow/coreferenceResolution](/en/docs/introduction/guide/dashboard/workflow/coreferenceResolution) +- [/en/docs/introduction/guide/dashboard/workflow/custom_feedback](/en/docs/introduction/guide/dashboard/workflow/custom_feedback) +- [/en/docs/introduction/guide/dashboard/workflow/dataset_search](/en/docs/introduction/guide/dashboard/workflow/dataset_search) +- [/en/docs/introduction/guide/dashboard/workflow/document_parsing](/en/docs/introduction/guide/dashboard/workflow/document_parsing) +- [/en/docs/introduction/guide/dashboard/workflow/form_input](/en/docs/introduction/guide/dashboard/workflow/form_input) +- [/en/docs/introduction/guide/dashboard/workflow/http](/en/docs/introduction/guide/dashboard/workflow/http) +- [/en/docs/introduction/guide/dashboard/workflow/knowledge_base_search_merge](/en/docs/introduction/guide/dashboard/workflow/knowledge_base_search_merge) +- [/en/docs/introduction/guide/dashboard/workflow/laf](/en/docs/introduction/guide/dashboard/workflow/laf) +- [/en/docs/introduction/guide/dashboard/workflow/loop](/en/docs/introduction/guide/dashboard/workflow/loop) +- [/en/docs/introduction/guide/dashboard/workflow/question_classify](/en/docs/introduction/guide/dashboard/workflow/question_classify) +- [/en/docs/introduction/guide/dashboard/workflow/reply](/en/docs/introduction/guide/dashboard/workflow/reply) +- [/en/docs/introduction/guide/dashboard/workflow/sandbox](/en/docs/introduction/guide/dashboard/workflow/sandbox) +- [/en/docs/introduction/guide/dashboard/workflow/text_editor](/en/docs/introduction/guide/dashboard/workflow/text_editor) +- [/en/docs/introduction/guide/dashboard/workflow/tfswitch](/en/docs/introduction/guide/dashboard/workflow/tfswitch) +- [/en/docs/introduction/guide/dashboard/workflow/tool](/en/docs/introduction/guide/dashboard/workflow/tool) +- [/en/docs/introduction/guide/dashboard/workflow/user-selection](/en/docs/introduction/guide/dashboard/workflow/user-selection) +- [/en/docs/introduction/guide/dashboard/workflow/variable_update](/en/docs/introduction/guide/dashboard/workflow/variable_update) +- [/en/docs/introduction/guide/knowledge_base/RAG](/en/docs/introduction/guide/knowledge_base/RAG) +- [/en/docs/introduction/guide/knowledge_base/api_dataset](/en/docs/introduction/guide/knowledge_base/api_dataset) +- [/en/docs/introduction/guide/knowledge_base/collection_tags](/en/docs/introduction/guide/knowledge_base/collection_tags) +- [/en/docs/introduction/guide/knowledge_base/dataset_engine](/en/docs/introduction/guide/knowledge_base/dataset_engine) +- [/en/docs/introduction/guide/knowledge_base/lark_dataset](/en/docs/introduction/guide/knowledge_base/lark_dataset) +- [/en/docs/introduction/guide/knowledge_base/template](/en/docs/introduction/guide/knowledge_base/template) +- [/en/docs/introduction/guide/knowledge_base/third_dataset](/en/docs/introduction/guide/knowledge_base/third_dataset) +- [/en/docs/introduction/guide/knowledge_base/websync](/en/docs/introduction/guide/knowledge_base/websync) +- [/en/docs/introduction/guide/knowledge_base/yuque_dataset](/en/docs/introduction/guide/knowledge_base/yuque_dataset) +- [/en/docs/introduction/guide/plugins/bing_search_plugin](/en/docs/introduction/guide/plugins/bing_search_plugin) +- [/en/docs/introduction/guide/plugins/dev_system_tool](/en/docs/introduction/guide/plugins/dev_system_tool) +- [/en/docs/introduction/guide/plugins/doc2x_plugin_guide](/en/docs/introduction/guide/plugins/doc2x_plugin_guide) +- [/en/docs/introduction/guide/plugins/google_search_plugin_guide](/en/docs/introduction/guide/plugins/google_search_plugin_guide) +- [/en/docs/introduction/guide/plugins/searxng_plugin_guide](/en/docs/introduction/guide/plugins/searxng_plugin_guide) +- [/en/docs/introduction/guide/plugins/upload_system_tool](/en/docs/introduction/guide/plugins/upload_system_tool) +- [/en/docs/introduction/guide/team_permissions/customDomain](/en/docs/introduction/guide/team_permissions/customDomain) +- [/en/docs/introduction/guide/team_permissions/invitation_link](/en/docs/introduction/guide/team_permissions/invitation_link) +- [/en/docs/introduction/guide/team_permissions/team_roles_permissions](/en/docs/introduction/guide/team_permissions/team_roles_permissions) - [/en/docs/introduction/index](/en/docs/introduction/index) +- [/en/docs/openapi/app](/en/docs/openapi/app) +- [/en/docs/openapi/chat](/en/docs/openapi/chat) +- [/en/docs/openapi/dataset](/en/docs/openapi/dataset) +- [/en/docs/openapi/index](/en/docs/openapi/index) +- [/en/docs/openapi/intro](/en/docs/openapi/intro) +- [/en/docs/openapi/share](/en/docs/openapi/share) - [/en/docs/protocol/open-source](/en/docs/protocol/open-source) - [/en/docs/protocol/privacy](/en/docs/protocol/privacy) - [/en/docs/protocol/terms](/en/docs/protocol/terms) +- [/en/docs/upgrading/4-10/4100](/en/docs/upgrading/4-10/4100) +- [/en/docs/upgrading/4-10/4101](/en/docs/upgrading/4-10/4101) +- [/en/docs/upgrading/4-11/4110](/en/docs/upgrading/4-11/4110) +- [/en/docs/upgrading/4-11/4111](/en/docs/upgrading/4-11/4111) +- [/en/docs/upgrading/4-12/4120](/en/docs/upgrading/4-12/4120) +- [/en/docs/upgrading/4-12/4121](/en/docs/upgrading/4-12/4121) +- [/en/docs/upgrading/4-12/4122](/en/docs/upgrading/4-12/4122) +- [/en/docs/upgrading/4-12/4123](/en/docs/upgrading/4-12/4123) +- [/en/docs/upgrading/4-12/4124](/en/docs/upgrading/4-12/4124) +- [/en/docs/upgrading/4-13/4130](/en/docs/upgrading/4-13/4130) +- [/en/docs/upgrading/4-13/4131](/en/docs/upgrading/4-13/4131) +- [/en/docs/upgrading/4-13/4132](/en/docs/upgrading/4-13/4132) +- [/en/docs/upgrading/4-14/4140](/en/docs/upgrading/4-14/4140) +- [/en/docs/upgrading/4-14/4141](/en/docs/upgrading/4-14/4141) +- [/en/docs/upgrading/4-14/4142](/en/docs/upgrading/4-14/4142) +- [/en/docs/upgrading/4-14/4143](/en/docs/upgrading/4-14/4143) +- [/en/docs/upgrading/4-14/4144](/en/docs/upgrading/4-14/4144) +- [/en/docs/upgrading/4-14/4145](/en/docs/upgrading/4-14/4145) +- [/en/docs/upgrading/4-14/41451](/en/docs/upgrading/4-14/41451) +- [/en/docs/upgrading/4-14/4146](/en/docs/upgrading/4-14/4146) +- [/en/docs/upgrading/4-14/4147](/en/docs/upgrading/4-14/4147) +- [/en/docs/upgrading/4-14/4148](/en/docs/upgrading/4-14/4148) +- [/en/docs/upgrading/4-8/40](/en/docs/upgrading/4-8/40) +- [/en/docs/upgrading/4-8/41](/en/docs/upgrading/4-8/41) +- [/en/docs/upgrading/4-8/42](/en/docs/upgrading/4-8/42) +- [/en/docs/upgrading/4-8/421](/en/docs/upgrading/4-8/421) +- [/en/docs/upgrading/4-8/43](/en/docs/upgrading/4-8/43) +- [/en/docs/upgrading/4-8/44](/en/docs/upgrading/4-8/44) +- [/en/docs/upgrading/4-8/441](/en/docs/upgrading/4-8/441) +- [/en/docs/upgrading/4-8/442](/en/docs/upgrading/4-8/442) +- [/en/docs/upgrading/4-8/445](/en/docs/upgrading/4-8/445) +- [/en/docs/upgrading/4-8/446](/en/docs/upgrading/4-8/446) +- [/en/docs/upgrading/4-8/447](/en/docs/upgrading/4-8/447) +- [/en/docs/upgrading/4-8/45](/en/docs/upgrading/4-8/45) +- [/en/docs/upgrading/4-8/451](/en/docs/upgrading/4-8/451) +- [/en/docs/upgrading/4-8/452](/en/docs/upgrading/4-8/452) +- [/en/docs/upgrading/4-8/46](/en/docs/upgrading/4-8/46) +- [/en/docs/upgrading/4-8/461](/en/docs/upgrading/4-8/461) +- [/en/docs/upgrading/4-8/462](/en/docs/upgrading/4-8/462) +- [/en/docs/upgrading/4-8/463](/en/docs/upgrading/4-8/463) +- [/en/docs/upgrading/4-8/464](/en/docs/upgrading/4-8/464) +- [/en/docs/upgrading/4-8/465](/en/docs/upgrading/4-8/465) +- [/en/docs/upgrading/4-8/466](/en/docs/upgrading/4-8/466) +- [/en/docs/upgrading/4-8/467](/en/docs/upgrading/4-8/467) +- [/en/docs/upgrading/4-8/468](/en/docs/upgrading/4-8/468) +- [/en/docs/upgrading/4-8/469](/en/docs/upgrading/4-8/469) +- [/en/docs/upgrading/4-8/47](/en/docs/upgrading/4-8/47) +- [/en/docs/upgrading/4-8/471](/en/docs/upgrading/4-8/471) +- [/en/docs/upgrading/4-8/48](/en/docs/upgrading/4-8/48) +- [/en/docs/upgrading/4-8/481](/en/docs/upgrading/4-8/481) +- [/en/docs/upgrading/4-8/4810](/en/docs/upgrading/4-8/4810) +- [/en/docs/upgrading/4-8/4811](/en/docs/upgrading/4-8/4811) +- [/en/docs/upgrading/4-8/4812](/en/docs/upgrading/4-8/4812) +- [/en/docs/upgrading/4-8/4813](/en/docs/upgrading/4-8/4813) +- [/en/docs/upgrading/4-8/4814](/en/docs/upgrading/4-8/4814) +- [/en/docs/upgrading/4-8/4815](/en/docs/upgrading/4-8/4815) +- [/en/docs/upgrading/4-8/4816](/en/docs/upgrading/4-8/4816) +- [/en/docs/upgrading/4-8/4817](/en/docs/upgrading/4-8/4817) +- [/en/docs/upgrading/4-8/4818](/en/docs/upgrading/4-8/4818) +- [/en/docs/upgrading/4-8/4819](/en/docs/upgrading/4-8/4819) +- [/en/docs/upgrading/4-8/482](/en/docs/upgrading/4-8/482) +- [/en/docs/upgrading/4-8/4820](/en/docs/upgrading/4-8/4820) +- [/en/docs/upgrading/4-8/4821](/en/docs/upgrading/4-8/4821) +- [/en/docs/upgrading/4-8/4822](/en/docs/upgrading/4-8/4822) +- [/en/docs/upgrading/4-8/4823](/en/docs/upgrading/4-8/4823) +- [/en/docs/upgrading/4-8/483](/en/docs/upgrading/4-8/483) +- [/en/docs/upgrading/4-8/484](/en/docs/upgrading/4-8/484) +- [/en/docs/upgrading/4-8/485](/en/docs/upgrading/4-8/485) +- [/en/docs/upgrading/4-8/486](/en/docs/upgrading/4-8/486) +- [/en/docs/upgrading/4-8/487](/en/docs/upgrading/4-8/487) +- [/en/docs/upgrading/4-8/488](/en/docs/upgrading/4-8/488) +- [/en/docs/upgrading/4-8/489](/en/docs/upgrading/4-8/489) +- [/en/docs/upgrading/4-9/490](/en/docs/upgrading/4-9/490) +- [/en/docs/upgrading/4-9/491](/en/docs/upgrading/4-9/491) +- [/en/docs/upgrading/4-9/4910](/en/docs/upgrading/4-9/4910) +- [/en/docs/upgrading/4-9/4911](/en/docs/upgrading/4-9/4911) +- [/en/docs/upgrading/4-9/4912](/en/docs/upgrading/4-9/4912) +- [/en/docs/upgrading/4-9/4913](/en/docs/upgrading/4-9/4913) +- [/en/docs/upgrading/4-9/4914](/en/docs/upgrading/4-9/4914) +- [/en/docs/upgrading/4-9/492](/en/docs/upgrading/4-9/492) +- [/en/docs/upgrading/4-9/493](/en/docs/upgrading/4-9/493) +- [/en/docs/upgrading/4-9/494](/en/docs/upgrading/4-9/494) +- [/en/docs/upgrading/4-9/495](/en/docs/upgrading/4-9/495) +- [/en/docs/upgrading/4-9/496](/en/docs/upgrading/4-9/496) +- [/en/docs/upgrading/4-9/497](/en/docs/upgrading/4-9/497) +- [/en/docs/upgrading/4-9/498](/en/docs/upgrading/4-9/498) +- [/en/docs/upgrading/4-9/499](/en/docs/upgrading/4-9/499) +- [/en/docs/use-cases/app-cases/dalle3](/en/docs/use-cases/app-cases/dalle3) +- [/en/docs/use-cases/app-cases/english_essay_correction_bot](/en/docs/use-cases/app-cases/english_essay_correction_bot) +- [/en/docs/use-cases/app-cases/feishu_webhook](/en/docs/use-cases/app-cases/feishu_webhook) +- [/en/docs/use-cases/app-cases/fixingEvidence](/en/docs/use-cases/app-cases/fixingEvidence) +- [/en/docs/use-cases/app-cases/google_search](/en/docs/use-cases/app-cases/google_search) +- [/en/docs/use-cases/app-cases/lab_appointment](/en/docs/use-cases/app-cases/lab_appointment) +- [/en/docs/use-cases/app-cases/multi_turn_translation_bot](/en/docs/use-cases/app-cases/multi_turn_translation_bot) +- [/en/docs/use-cases/app-cases/submit_application_template](/en/docs/use-cases/app-cases/submit_application_template) +- [/en/docs/use-cases/app-cases/translate-subtitle-using-gpt](/en/docs/use-cases/app-cases/translate-subtitle-using-gpt) +- [/en/docs/use-cases/external-integration/dingtalk](/en/docs/use-cases/external-integration/dingtalk) +- [/en/docs/use-cases/external-integration/feishu](/en/docs/use-cases/external-integration/feishu) +- [/en/docs/use-cases/external-integration/official_account](/en/docs/use-cases/external-integration/official_account) +- [/en/docs/use-cases/external-integration/openapi](/en/docs/use-cases/external-integration/openapi) +- [/en/docs/use-cases/external-integration/wecom](/en/docs/use-cases/external-integration/wecom) diff --git a/document/content/docs/upgrading/4-10/4100.en.mdx b/document/content/docs/upgrading/4-10/4100.en.mdx new file mode 100644 index 0000000000..9fef64827d --- /dev/null +++ b/document/content/docs/upgrading/4-10/4100.en.mdx @@ -0,0 +1,57 @@ +--- +title: 'V4.10.0' +description: 'FastGPT V4.10.0 Update Notes' +--- + +## Upgrade Guide + +### Docker Deployment + +- Refer to the latest [docker-compose.yml](https://github.com/labring/FastGPT/blob/main/deploy/docker/docker-compose-pgvector.yml) file to add the `fastgpt-plugin` and `minio` services. +- Set the `fastgpt-plugin` environment variable `AUTH_TOKEN` to a sufficiently complex value. +- Set the `fastgpt-plugin` environment variable `MINIO_CUSTOM_ENDPOINT` to `http://ip:port` or a relevant domain name that is accessible to FastGPT users. +- Update the environment variables for the `fastgpt` and `fastgpt-pro` (commercial edition) containers: + +``` +PLUGIN_BASE_URL=http://fastgpt-plugin:3000 +PLUGIN_TOKEN=the AUTH_TOKEN value you just set +``` +- Update the `fastgpt` and `fastgpt-pro` image tags to: v4.10.0-fix +- Run `docker-compose up -d` to start/update all services. + +### Sealos Deployment + +- In the Sealos desktop `Object Storage`, create a new bucket with `publicRead` permissions and obtain the relevant credentials: + +![](/imgs/sealos-s3.png) + +- Deploy the `fastgpt-plugin` service using the image `registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-plugin:v0.1.0`. Expose internal port 3000 (no public access required) and set the following environment variables: + +``` +AUTH_TOKEN=authentication token + +# Log level: debug, info, warn, error +LOG_LEVEL=info + +# S3 configuration +MINIO_CUSTOM_ENDPOINT=External +MINIO_ENDPOINT=Internal address +MINIO_PORT=80 +MINIO_USE_SSL=false +MINIO_ACCESS_KEY=Access Key +MINIO_SECRET_KEY=Secret Key +MINIO_BUCKET=bucket name +``` + +- Update the environment variables and image tags for the `fastgpt` and `fastgpt-pro` (commercial edition) containers to: v4.10.0-fix + +``` +PLUGIN_BASE_URL=internal address of the fastgpt-plugin service +PLUGIN_TOKEN=the AUTH_TOKEN value you just set +``` + +## New Features + +1. Standalone system tool service with support for independent development and debugging of system tools. +2. Updated [System Tool Development Guide](/docs/introduction/guide/plugins/dev_system_tool/). +3. Updated [System Tool Design Documentation](/docs/introduction/guide/plugins/design_plugin/). diff --git a/document/content/docs/upgrading/4-10/4101.en.mdx b/document/content/docs/upgrading/4-10/4101.en.mdx new file mode 100644 index 0000000000..8bcf8bb519 --- /dev/null +++ b/document/content/docs/upgrading/4-10/4101.en.mdx @@ -0,0 +1,55 @@ +--- +title: 'V4.10.1 (Includes Migration Script)' +description: 'FastGPT V4.10.1 Update Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.10.1-fix3 +- Update FastGPT commercial edition image tag: v4.10.1 +- Update fastgpt-plugin image tag: v0.1.3 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +### 2. Run the Migration Script + +This script only needs to be run by commercial edition users. + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4101' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +- Adds new scheduled tasks for auto-synced knowledge bases. + +## New Features + +1. System tools now support streaming output. +2. Commercial edition: scheduled sync for third-party knowledge bases now supports full sync, including entire directories. + +## Improvements + +1. Scheduled task error logs are now recorded in the chat logs. +2. Encapsulated dynamic form rendering component for apps. +3. Directory breadcrumb navigation now truncates on overflow. + +## Bug Fixes + +1. Search-type system tools were not displaying correctly. +2. Backward compatibility issues with some system tools. +3. AI node: manually selecting chat history caused duplicate system records. +4. Knowledge base tags could not scroll to the bottom. +5. When importing files via API to an API-based knowledge base, custom API parsing parameters were not applied. + +## Tool Updates + +1. New: Flux official image generation tool. +2. New: JinaAI toolset. +3. New: Alibaba Cloud Bailian Flux and Tongyi Wanxiang image generation. +4. Fixed incorrect output value type for SiliconFlow image generation tool. diff --git a/document/content/docs/upgrading/4-10/meta.en.json b/document/content/docs/upgrading/4-10/meta.en.json new file mode 100644 index 0000000000..92225dfe93 --- /dev/null +++ b/document/content/docs/upgrading/4-10/meta.en.json @@ -0,0 +1,8 @@ +{ + "title": "4.10.x", + "description": "", + "pages": [ + "4101", + "4100" + ] +} diff --git a/document/content/docs/upgrading/4-11/4110.en.mdx b/document/content/docs/upgrading/4-11/4110.en.mdx new file mode 100644 index 0000000000..3cf3fdc5ce --- /dev/null +++ b/document/content/docs/upgrading/4-11/4110.en.mdx @@ -0,0 +1,54 @@ +--- +title: 'V4.11.0' +description: 'FastGPT V4.11.0 Update Notes' +--- + +## Upgrade Guide + +### 1. Update Environment Variables + +Commercial edition users can add the following evaluation-related environment variables, then click Save once in the admin panel after updating. + +``` +EVAL_CONCURRENCY=3 # Evaluation single-node concurrency +EVAL_LINE_LIMIT=1000 # Maximum lines per evaluation file +``` + +### 2. Update Images: + +- Update FastGPT image tag: v4.11.0 +- Update FastGPT commercial edition image tag: v4.11.0 +- Update fastgpt-plugin image tag: v0.1.5 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +## Project Changes + +1. Removed all restrictions on **open-source features**, including limits on the number of apps and knowledge bases. +2. Updated the roadmap to include `Context Management`, `AI-Generated Workflows`, `Advanced Orchestration Debug Mode`, and more. +3. The international domain has been changed from `fastgpt.io` to `fastgpt.io`. + +## New Features + +1. Commercial edition: added **App Evaluation (Beta)** for supervised scoring of apps. +2. Workflow nodes now support error-catching branches. +3. Chat page: independent tab UX. +4. Support for Signoz traces and logs system monitoring. +5. Added model configurations for Gemini 2.5, Grok 4, and Kimi. +6. Model invocation logs now include time-to-first-token and request IP. + +## Improvements + +1. Optimized code to prevent memory buildup from recursion, significantly reducing memory consumption during high-concurrency knowledge base preprocessing. +2. Knowledge base training: support for retrying all failed data in a collection at once. +3. Workflow valueTypeFormat to prevent data type inconsistencies. +4. Knowledge base list search now properly escapes special characters in regex. + +## Bug Fixes + +1. Question classification and content extraction nodes: default model failed frontend validation, preventing workflow execution and publishing. + +## Tool Updates + +1. Markdown text to Docx and Xlsx file conversion. diff --git a/document/content/docs/upgrading/4-11/4111.en.mdx b/document/content/docs/upgrading/4-11/4111.en.mdx new file mode 100644 index 0000000000..68eeb438e1 --- /dev/null +++ b/document/content/docs/upgrading/4-11/4111.en.mdx @@ -0,0 +1,46 @@ +--- +title: 'V4.11.1' +description: 'FastGPT V4.11.1 Update Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.11.1-fix2 +- Update FastGPT commercial edition image tag: v4.11.1-fix +- Update fastgpt-plugin image tag: v0.1.7 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +## New Features + +1. System tools: toolsets can now be used directly for tool calls. +2. MCP architecture rewrite — after updating MCP, all active MCP components are automatically updated without needing to remove and re-add them. +3. Chat log dashboard now supports custom field display. +4. Account deletion. +5. New documentation framework. +6. GLM 4.5 series model configurations. + +## Improvements + +1. Redemption code feature now supports specifying corporate payment mode. +2. Optimized payment plan mode. +3. Renaming a global variable no longer causes referenced values in nodes to be lost. +4. Moved model preset configurations to the FastGPT Plugin project. + +## Bug Fixes + +1. MCP object-type data was passed incorrectly. +2. Login page UI misalignment. +3. Excel files with line break characters caused chunking errors. +4. Doc2x PDF parsing: removed extraneous tags. +5. 404 page translations were not applied. + +## Tool Updates + +1. New: libulibu drawing tool. +2. New: Metaso search tool. +3. New: Signoz system monitoring integration. +4. Fixed: incorrect data type in the math expression tool. diff --git a/document/content/docs/upgrading/4-11/meta.en.json b/document/content/docs/upgrading/4-11/meta.en.json new file mode 100644 index 0000000000..c3adba25f2 --- /dev/null +++ b/document/content/docs/upgrading/4-11/meta.en.json @@ -0,0 +1,8 @@ +{ + "title": "4.11.x", + "description": "", + "pages": [ + "4111", + "4110" + ] +} diff --git a/document/content/docs/upgrading/4-12/4120.en.mdx b/document/content/docs/upgrading/4-12/4120.en.mdx new file mode 100644 index 0000000000..898c3b1066 --- /dev/null +++ b/document/content/docs/upgrading/4-12/4120.en.mdx @@ -0,0 +1,71 @@ +--- +title: 'V4.12.0 (Includes Migration Script)' +description: 'FastGPT V4.12.0 Update Notes, released on 2025-8-11' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.12.0 +- Update FastGPT commercial edition image tag: v4.12.0 +- Update fastgpt-plugin image tag: v0.1.9 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +### 2. Update Environment Variables + +Update the FastGPT commercial edition (fastgpt-pro) environment variables: + +```sh +# Secret key for file reading, must match the environment variable in the fastgpt image +FILE_TOKEN_KEY=filetokenkey +``` + +### 3. Run the Migration Script + +This script only needs to be run by commercial edition users. + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4120' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +**Script Functions** + +1. Initializes chat log permissions for team members. + +## New Features + +1. Commercial edition: app log data dashboard. +2. Commercial edition: simple chat page — select a model and preset tools to chat directly without building an app. +3. Chat page: quick team app switching. +4. Permission table restructured to use a Role-to-Permission mapping model. +5. Apps can now have chat log viewing permissions assigned individually. + +## Improvements + +1. Fixed 3 potential memory leak issues in the code. +2. Optimized workflow recursion checks to prevent infinite recursion. +3. Optimized the document reading Worker to use SharedBuffer, avoiding data copying. +4. Batch vector generation and storage to reduce network operations. +5. Knowledge base search: multi-query merged computation to reduce database operations. +6. Improved knowledge base selection UX. +7. Login page UI adjustments. +8. Stricter validation in workflows for whether a toolset can be added. +9. Chat log export now only exports selected columns, and fixed an issue where some columns could not be exported. + +## Bug Fixes + +1. Doc2x API update caused parsing failures. +2. Workflow: team app directories could be incorrectly added to workflows. +3. Workflow: array selector UI defect. +4. Member sync had incomplete permission deletion issues. + +## Tool Updates + +1. System tools can now return `citeLinks` in their response, enabling citation link display in the chat interface. diff --git a/document/content/docs/upgrading/4-12/4121.en.mdx b/document/content/docs/upgrading/4-12/4121.en.mdx new file mode 100644 index 0000000000..55c526dd03 --- /dev/null +++ b/document/content/docs/upgrading/4-12/4121.en.mdx @@ -0,0 +1,53 @@ +--- +title: 'V4.12.1 (Includes Migration Script)' +description: 'FastGPT V4.12.1 Update Notes, released on 2025-8-18' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.12.1-fix +- Update FastGPT commercial edition image tag: v4.12.1 +- Update fastgpt-plugin image tag: v0.1.10 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +### 2. Run the Migration Script + +This script only needs to be run by commercial edition users. + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4121' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +**Script Functions** + +1. Migrates historical chat logs into the new log dashboard format. + +## New Features + +1. Automatic prompt generation and optimization. +2. Added `SIGNOZ_STORE_LEVEL` parameter to control the Signoz log storage level. + +## Improvements + +1. Workflow response optimization: explicitly specifying which response values go into chat history, instead of determining by key. +2. Prevented infinite loops or deep recursion risks caused by variable substitution in workflows. +3. Chat log export now consistently exports full conversation details. +4. Paginator UI improvements. + +## Bug Fixes + +1. Tool secret input: boolean values could not pass form validation. +2. Chat page: pane switching could cause data inconsistencies. +3. Incorrect index on the chat log dashboard data table. + +## Tool Updates + +1. System tools now support individual Tool description configuration for better model comprehension. diff --git a/document/content/docs/upgrading/4-12/4122.en.mdx b/document/content/docs/upgrading/4-12/4122.en.mdx new file mode 100644 index 0000000000..2201cc0835 --- /dev/null +++ b/document/content/docs/upgrading/4-12/4122.en.mdx @@ -0,0 +1,49 @@ +--- +title: 'V4.12.2' +description: 'FastGPT V4.12.2 Update Notes, released on 2025-8-26' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.12.2-fix3 +- Update FastGPT commercial edition image tag: v4.12.2-fix3 +- Update fastgpt-plugin image tag: v0.1.11 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +## New Features + +1. Embedding model concurrency settings — no longer hardcoded to 10, since some embedding models don't support concurrency. Default is now 1, configurable in model settings. +2. Chat page: admins can configure featured apps to recommend to team members. +3. Chat page home: admins can configure shortcut apps for commonly used team applications. +4. Support for disabling the team chat homepage. + +## Improvements + +1. Added anomaly detection for **isolated branches** in workflows. +2. When truncating embedding vectors above 1536 dimensions, normalization is now enforced. For other dimensions, normalization is determined entirely by configuration, reducing unnecessary automatic computation. +3. Moved model provider configuration into the plugin SDK. +4. Encapsulated LLM call functions to simplify LLM requests and tool calls. +5. Optimized workflow scheduling code to avoid deep recursion. +6. Improved workflow recursion detection with grouped checks on recursive paths, supporting more diverse connection patterns. + +## Bug Fixes + +1. Standalone chat page: various UI issues. +2. Standalone chat page: plugin interactions could not be rendered. +3. Standalone chat page: incorrect default URL when using sub-routes. +4. Multi-select picker causing page crashes. +5. Mobile: shared links incorrectly loaded the authenticated chat page navigation. +6. User sync could encounter write conflict issues. +7. System plans could not be fully disabled — empty object defaults caused authentication errors. +8. Workflow: searching for team apps was not working. +9. App versions: incorrect `ref` field prevented normal usage. +10. OceanBase: batch inserts did not correctly return inserted IDs. +11. Interaction nodes conflicted with toolsets, causing toolsets to malfunction after an interaction node. + +## Tool Updates + +1. Doc2x tool: incorrect response values. diff --git a/document/content/docs/upgrading/4-12/4123.en.mdx b/document/content/docs/upgrading/4-12/4123.en.mdx new file mode 100644 index 0000000000..ed3a037c8f --- /dev/null +++ b/document/content/docs/upgrading/4-12/4123.en.mdx @@ -0,0 +1,40 @@ +--- +title: 'V4.12.3' +description: 'FastGPT V4.12.3 Update Notes, released on 2025-9-8' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.12.3 +- Update FastGPT commercial edition image tag: v4.12.3 +- Update fastgpt-plugin image tag: v0.1.12 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +## New Features + +1. Prompt editor now supports lists, tabs, and other rich text interactions. +2. Apps now have additional global variables: password, multi-select, and internal variables (hidden in on-site chat). + +## Improvements + +1. Corrected the RRF weight merging algorithm to use the standard RRF weight formula. +2. Multi-select component now supports dynamic width calculation to fit visible tags. +3. Variable update component rendering optimized for consistency with global variable rendering. + +## Bug Fixes + +1. In single-team mode, users who left could not rejoin the team. +2. Workflow file upload was enabled by default, but the input side did not include file output. +3. Consecutive user selections: branches could not run correctly. +4. Workflow: variable update array selector was not working properly. +5. App evaluation: only the first output text was captured instead of all output texts. + +## Plugin Updates + +1. Migrated system tool types to the plugin. +2. Moved model provider configuration to the plugin for hot-reload support. +3. Moved app templates to the plugin. diff --git a/document/content/docs/upgrading/4-12/4124.en.mdx b/document/content/docs/upgrading/4-12/4124.en.mdx new file mode 100644 index 0000000000..09467d38a6 --- /dev/null +++ b/document/content/docs/upgrading/4-12/4124.en.mdx @@ -0,0 +1,52 @@ +--- +title: 'V4.12.4 (Includes Migration Script)' +description: 'FastGPT V4.12.4 Update Notes, released on 2025-9-15' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.12.4 +- Update FastGPT commercial edition image tag: v4.12.4 +- Update fastgpt-plugin image tag: v0.1.13 +- mcp_server: no update required +- Update Sandbox image tag: v4.12.4 +- AIProxy: no update required + +### 2. Run the Migration Script + +This script only needs to be run by commercial edition users. + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4124' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +**Script Functions** + +1. Adds owner permissions to all resources. + +## New Features + +1. Commercial edition: WeCom publishing channel support. + +## Improvements + +1. Permission inheritance optimization: when a child resource has higher permissions than its parent, inheritance mode is no longer forcibly interrupted. +2. Prompt editor now supports list rendering. +3. Navigating back to the knowledge base list from the data page now preserves pagination. +4. After successfully uploading files to a knowledge base, the view returns to the corresponding upload directory. +5. Reduced transaction operations when deleting apps. +6. User selection UI improvements. + +## Bug Fixes + +1. HTTP tool null pointer error prevented editing. +2. Python code execution: input parameters could not be boolean values. + +## Plugin Updates + diff --git a/document/content/docs/upgrading/4-12/meta.en.json b/document/content/docs/upgrading/4-12/meta.en.json new file mode 100644 index 0000000000..8cd51651d8 --- /dev/null +++ b/document/content/docs/upgrading/4-12/meta.en.json @@ -0,0 +1,11 @@ +{ + "title": "4.12.x", + "description": "", + "pages": [ + "4124", + "4123", + "4122", + "4121", + "4120" + ] +} diff --git a/document/content/docs/upgrading/4-13/4130.en.mdx b/document/content/docs/upgrading/4-13/4130.en.mdx new file mode 100644 index 0000000000..fd00156739 --- /dev/null +++ b/document/content/docs/upgrading/4-13/4130.en.mdx @@ -0,0 +1,82 @@ +--- +title: 'V4.13.0 (Environment Variable Changes)' +description: 'FastGPT V4.13.0 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.13.0-fix +- Update FastGPT commercial edition image tag: v4.13.0-fix +- Update fastgpt-plugin image tag: v0.2.0-fix2 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed + +### 2. Update Environment Variables + +1. Update `fastgpt-plugin` environment variable names, and add `S3_PLUGIN_BUCKET`, `MONGODB_URI`, and `REDIS_URL` values. + +``` +S3_EXTERNAL_BASE_URL=https://xxx.com # S3 external URL +S3_ENDPOINT=localhost +S3_PORT=9000 +S3_USE_SSL=false +S3_ACCESS_KEY=minioadmin +S3_SECRET_KEY=minioadmin +S3_TOOL_BUCKET=fastgpt-tool # Bucket for temporary files created by system tools. Requires public read, private write. +S3_PLUGIN_BUCKET=fastgpt-plugin # Bucket for system plugin hot-install files. Private read/write. +RETENTION_DAYS=15 # Number of days to retain system tool temporary files +MONGODB_URI=mongodb://myusername:mypassword@mongo:27017/fastgpt?authSource=admin # MongoDB connection string +REDIS_URL=redis://default:mypassword@redis:6379 # Redis connection string +``` + +2. Add S3-related environment variables for `fastgpt` and `fastgpt-pro (commercial edition)`. + +``` +# S3 external URL +S3_EXTERNAL_BASE_URL= +S3_ENDPOINT=localhost +S3_PORT=9000 +S3_USE_SSL=false +S3_ACCESS_KEY=minioadmin +S3_SECRET_KEY=minioadmin +S3_PLUGIN_BUCKET=fastgpt-plugin # Bucket for system plugin hot-install files. Private read/write. +``` + +## New Features + +1. New HTTP Toolset type for apps, replacing the previous HTTP Plugin. +2. System administrators can now quickly install system tools via file upload. +3. Team administrators can assign model permissions. +4. Code execution node supports AI-assisted code generation. +5. Knowledge base file parsing now supports configuring maximum concurrency. (Open-source edition: configure via `systemEnv.datasetParseMaxProcess` in config.json. Commercial edition: configure via the admin dashboard.) + +## Improvements + +1. System tools now display the corresponding author name, with safe i18n translations. +2. Metered billing push and merge logic. +3. Node details in chat history are now stored in a separate table. +4. Removed invalid `dataId` index from `chat_items`. +5. Workflow UI performance improvements to reduce unnecessary re-renders. +6. Knowledge base citation authentication in chats now applies to the entire conversation instead of individual messages. +7. Improved UX for dynamic input/output variables in workflows. + +## Bug Fixes + +1. Global variables not passed in debug mode. +2. Parameters from upstream nodes not passed to downstream nodes in debug mode. +3. In debug mode, enabling "Auto Execute" would skip external variable input. +4. Auto voice reply not working. +5. Error capture configuration lost when copying nodes. +6. "Suggested Questions" custom prompt: previous values were cleared on save. +7. Knowledge base image URLs assembled incorrectly when a secondary route was configured. +8. Prompt editor cleared Markdown formatting during keyboard input. +9. Knowledge base collection page did not auto-refresh when training data was present. +10. Workflow quick-add node popup showed empty toolbox on second open. +11. PPTX file parsing order was incorrect. + +## Plugin Updates + +1. Added Volcengine Fusion Information Search tool. diff --git a/document/content/docs/upgrading/4-13/4131.en.mdx b/document/content/docs/upgrading/4-13/4131.en.mdx new file mode 100644 index 0000000000..b470aa6b8f --- /dev/null +++ b/document/content/docs/upgrading/4-13/4131.en.mdx @@ -0,0 +1,40 @@ +--- +title: 'V4.13.1' +description: 'FastGPT V4.13.1 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.13.1 +- Update FastGPT commercial edition image tag: v4.13.1 +- Update fastgpt-plugin image tag: v0.2.2 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed + +## New Features + +1. Added response size limit for HTTP requests. + +## Improvements + +1. When copying an app, the avatar is now duplicated to avoid sharing the same image link, which previously caused one app's avatar to disappear when the other's was updated. +2. Markdown parser now handles Windows paths correctly, preventing `\` from being treated as an escape character. + +## Bug Fixes + +1. In loop nodes, the previous round's interactive response value was not cleared at the end of each iteration. +2. After an interactive node responded, chat record statistics were not updated. +3. Prompt editor displayed incorrect default values in popups. +4. Form input fields with `.` in the variable name could not accept values properly. +5. When calling a sub-workflow, auto-flow knowledge base citations were not displayed in share links. + +## Plugin Updates + +1. Base64 decode tool now supports conversion to both text and images. +2. Moji Weather tool. +3. Biyou PPT generation tool. +4. Configurable maximum request body size and internal network request maximum response size to prevent memory overflow from oversized responses. +5. Added model presets for Claude 4.5, Qwen3, Kimi2, and DeepSeek 3.2. diff --git a/document/content/docs/upgrading/4-13/4132.en.mdx b/document/content/docs/upgrading/4-13/4132.en.mdx new file mode 100644 index 0000000000..efb45c7d74 --- /dev/null +++ b/document/content/docs/upgrading/4-13/4132.en.mdx @@ -0,0 +1,77 @@ +--- +title: 'V4.13.2 (Includes Upgrade Script)' +description: 'FastGPT V4.13.2 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.13.2 +- Update FastGPT commercial edition image tag: v4.13.2 +- Update fastgpt-plugin image tag: v0.2.4 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed + +### 2. Add FastGPT/FastGPT-pro Environment Variables + +``` +S3_PUBLIC_BUCKET=fastgpt-public # (Public read bucket name, corresponds to the previous S3_TOOL_BUCKET in the plugin project) +S3_PRIVATE_BUCKET=fastgpt-private # (Private read/write bucket name, corresponds to the previous S3_PLUGIN_BUCKET in the plugin project) +``` + +### 3. Fix fastgpt-plugin Environment Variables + +- Rename S3_TOOL_BUCKET to S3_PUBLIC_BUCKET +- Rename S3_PLUGIN_BUCKET to S3_PRIVATE_BUCKET + +### 4. Run the Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4132' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will remove the previous S3 circleLife policy. If you are using an external S3 service that does not support circleLife operations, this script may fail -- you can safely ignore the error (since setting the policy would have also failed). + + +## New Features + +1. HTTP Toolset now supports manual creation mode. +2. Introduced the project OpenAPI framework. +3. API key validity check endpoint. +4. Exported chat logs now include the current version's global variables at the end. + +## Improvements + +1. Non-administrators can no longer view team audit logs. +2. Introduced S3 for storing app avatars. +3. Workflow canvas performance improvements. + +## Bug Fixes + +1. LLM models defaulting to image support caused request errors. +2. Mongo watch was not re-triggered during multi-replica failover. +3. Text chunking did not process the remaining `LastText` data after all strategies were exhausted. +4. Variable input field failed validation when number value was 0. +5. Incorrect parallel execution detection in complex workflow loops. + +## Plugin Updates + +1. Added: Perplexity Search tool. +2. Added: Base64-to-file conversion tool. +3. Added: MiniMax TTS file generation tool. +4. Added: Openrouter Nano Banana image generation tool. +5. Added: Redis cache operation tool. +6. Added: Tavily Search tool. +7. Added: SiliconFlow qwen-image and qwen-image-edit tools. +8. Added: Lark Multidimensional Table operation suite. +9. Added: YouTube subtitle extraction. +10. Added: Alibaba Cloud Bailian qwen image edit. +11. Added: Markdown-to-PPT tool. +12. Added: Whisper speech-to-text tool. +13. System tools now support configuring whether to run in a Worker. diff --git a/document/content/docs/upgrading/4-13/meta.en.json b/document/content/docs/upgrading/4-13/meta.en.json new file mode 100644 index 0000000000..61f21a42b1 --- /dev/null +++ b/document/content/docs/upgrading/4-13/meta.en.json @@ -0,0 +1,9 @@ +{ + "title": "4.13.x", + "description": "", + "pages": [ + "4132", + "4131", + "4130" + ] +} diff --git a/document/content/docs/upgrading/4-14/4140.en.mdx b/document/content/docs/upgrading/4-14/4140.en.mdx new file mode 100644 index 0000000000..f132dd8174 --- /dev/null +++ b/document/content/docs/upgrading/4-14/4140.en.mdx @@ -0,0 +1,69 @@ +--- +title: 'V4.14.0 (Includes Upgrade Script)' +description: 'FastGPT V4.14.0 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.14.0 +- Update FastGPT commercial edition image tag: v4.14.0 +- Update fastgpt-plugin image tag: v0.3.0 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed + +### 2. Run the Upgrade Script + +Only required for commercial edition users who have used custom system tools. +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4140' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will migrate existing system tools to the latest data table. + +### 3. Install System Plugins + +Starting from V4.14.0, the fastgpt-plugin image only provides the runtime environment and no longer comes with pre-installed system plugins. All FastGPT systems must manually install system plugins. + +**Important Notes** +* Previously manually installed JS plugin packages will become invalid and need to be repackaged and reinstalled. +* Installing via the Plugin Marketplace will fetch data from the public FastGPT Marketplace by default. +* If your FastGPT instance cannot access the Plugin Marketplace, you can manually visit the [FastGPT Plugin Marketplace](https://marketplace.fastgpt.cn/), download the .pkg file, and import it into your system. +* In addition to installation, you can also sort tools, set default installations, manage tags, and more. +* Currently, the plugin system only includes tools. Triggers, document parsers, data chunking strategies, and index enhancement strategies will be added in future releases. +* After system plugins are installed, in multi-tenant systems, team administrators can activate the corresponding tools in the plugin library to use them in apps. For the open-source edition, the root team will have all system tools activated by default. + + +In addition to installation, you can also sort tools, set default installations, manage tags, and more. + +![alt text](/imgs/image-121.png) + +## New Features + +1. Added Plugin Marketplace, and removed custom plugin groups (only custom tags are retained). This release supports system tools that can be installed from the FastGPT Marketplace. Future releases will support more plugin types: workflow triggers, data source parsers, data chunking strategies, index enhancement strategies, and more. +2. Files uploaded in the chat dialog are now stored in S3 and will not auto-expire -- they are deleted only when the chat record is deleted. Security is improved with signed preview links that expire after 1 hour instead of being long-lived. +3. Global variables now support time point / time range / chat model selection types. +4. Plugin input now supports password type. + +## Improvements + +1. Improved regex performance for matching Base64 images in Markdown. +2. After a team member accepts an invitation, the default member name is now set to the member's account name. + +## Bug Fixes + +1. Prompt editor could not parse content correctly when special syntax was present. +2. Claude tool calls failed when indices started from 1, causing parameter errors. +3. S3 avatar deletion threw an error when the key was empty, blocking the process. +4. Workflow dependencies were not refreshed promptly when upstream I/O changed. +5. Exported chat logs were missing feedback records. +6. Cursor jumped to the end of the input when typing in the workflow welcome message field. +7. Interactive nodes combined with consecutive batch execution caused workflow logic errors. +8. After a workflow Redo operation, edit history could no longer push snapshots. +9. HTTP custom input was lost. diff --git a/document/content/docs/upgrading/4-14/4141.en.mdx b/document/content/docs/upgrading/4-14/4141.en.mdx new file mode 100644 index 0000000000..046d0129c9 --- /dev/null +++ b/document/content/docs/upgrading/4-14/4141.en.mdx @@ -0,0 +1,51 @@ +--- +title: 'V4.14.1 (Includes Upgrade Script)' +description: 'FastGPT V4.14.1 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.14.1 +- Update FastGPT commercial edition image tag: v4.14.1 +- Update fastgpt-plugin image tag: v0.3.1 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed + +### 2. Run the Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4141' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will create a copy of the original app directory for tool usage. + +## New Features + +1. New workbench interaction. The original "Plugin" has been renamed to "Workflow Tool" and moved under the My Tools category. +2. Workflows now provide a "Continue" button after running out of credits, so you don't have to start over. + +## Improvements + +1. MCP Client instances are now persisted within the same conversation turn and will not be destroyed. +2. When reloading models, the global model configuration is no longer cleared and re-added, which previously caused model call errors during the reload phase. +3. Auto-save now creates a team cloud save record. + +## Bug Fixes + +1. Interactive nodes did not work properly in debug mode. +2. Tab spacing was misaligned in the rich text editor. +3. When running nested Agents, the skip-node queue was not initialized, preventing normal execution. +4. Condition node threw an error when the right-side value was a number reference. +5. File selection input did not show the selection dialog when used as a workflow tool parameter. +6. HTTP plugin could not correctly handle HTTP (non-HTTPS) protocol requests. +7. UI issue with the default value editor for text-type global variables. +8. Code node content overlapped when exceeding 100 lines. +9. Deleting an app did not delete items inside its directory. +10. Browser did not pass the real-time date to the server. diff --git a/document/content/docs/upgrading/4-14/4142.en.mdx b/document/content/docs/upgrading/4-14/4142.en.mdx new file mode 100644 index 0000000000..8ad3e9468b --- /dev/null +++ b/document/content/docs/upgrading/4-14/4142.en.mdx @@ -0,0 +1,46 @@ +--- +title: 'V4.14.2' +description: 'FastGPT V4.14.2 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.14.2 +- Update FastGPT commercial edition image tag: v4.14.2 +- Update fastgpt-plugin image tag: v0.3.2 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed + +## New Features + +1. Refactored the underlying Agent Call mechanism with support for context compression during consecutive tool calls. +2. New Template Marketplace UI. +3. Quick knowledge base creation from the Agent editor page. + +## Improvements + +1. Template Marketplace cache duration set to 30 minutes. +2. Custom separator chunk size now uses the maximum chunk size. +3. Prevented logging from triggering recursive log storms; excluded log model from performance monitoring middleware. + +## Bug Fixes + +1. Simple app templates were not converted correctly. +2. When tool calls contained two or more consecutive user selections, the second user selection behaved abnormally. +3. Incorrect team app type in the portal. +4. When an app was exported as MCP and used by other apps, global variables no longer need to be filled in. + +## Plugin Updates + +1. Fix: Sub-tool avatars were missing. +2. Fix: Model avatars were missing. +3. Fix: Incorrect mongoose dependency reference in Worker caused errors for tools running longer than 10 seconds. +4. Improvement: Static files are no longer re-uploaded during hot reload in development mode. +5. Added: 5118 SEO keyword mining tool. +6. Added: Tavily content extraction advanced configuration; website sitemap tool. +7. Added: WeChat Official Account toolset. +8. Added: Document comparison tool. +9. Added: Model presets for Kimi V2 and GPT 5.1. diff --git a/document/content/docs/upgrading/4-14/4143.en.mdx b/document/content/docs/upgrading/4-14/4143.en.mdx new file mode 100644 index 0000000000..d4bb1e0d31 --- /dev/null +++ b/document/content/docs/upgrading/4-14/4143.en.mdx @@ -0,0 +1,55 @@ +--- +title: 'V4.14.3 (Includes Upgrade Script)' +description: 'FastGPT V4.14.3 Release Notes' +--- + + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.14.3 +- Update FastGPT commercial edition image tag: v4.14.3 +- Update fastgpt-plugin image tag: v0.3.3 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed + +### 2. Run the Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4143' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will migrate all knowledge base files from MongoDB GridFS to S3, including text datasets and image datasets, but not images extracted from documents (e.g., .docx files). + +## New Features + +1. Knowledge base files migrated to S3 (all file-related functionality has been migrated). +2. Global variables now support file upload. +3. Form input node now supports password, toggle, time point, time range, file upload, and chat model selection. +4. Plugin input now supports multi-select, time point, time range, and internal variables. +5. System plugins in the Plugin Marketplace now show whether a new version is available, with an update button. +6. Workflow execution QPM (queries per minute) rate limiting. + +## Improvements + +1. Improved UX for file upload input in workflow tools. +2. Added permission table validation middleware to improve permission system robustness. + +## Bug Fixes + +1. Workflow debug preview window lost input values due to re-rendering. +2. When the S3 service shared the same origin as the main service, file request URLs to S3 were incorrectly rewritten, causing 404 errors. + +## Plugin Updates + +1. Updated tool versioning logic with a computed version value for update detection. +2. WeChat Official Account toolset: now allows uploading multiple documents to the draft box at once. +3. Fixed tool cache not being refreshed correctly. +4. Fixed static files being re-uploaded when refreshing cache in development mode. +5. Fixed images not being uploaded correctly after uploading a .pkg file. diff --git a/document/content/docs/upgrading/4-14/4144.en.mdx b/document/content/docs/upgrading/4-14/4144.en.mdx new file mode 100644 index 0000000000..4fb2a764a8 --- /dev/null +++ b/document/content/docs/upgrading/4-14/4144.en.mdx @@ -0,0 +1,88 @@ +--- +title: 'V4.14.4 (Includes Upgrade Script)' +description: 'FastGPT V4.14.4 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.14.4 +- Update FastGPT commercial edition image tag: v4.14.4 +- Update fastgpt-plugin image tag: v0.3.4 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed + +### 2. Run the Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4144' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +1. Migrates files uploaded via the Dataset/local API (left over from 4.14.3) to S3. +2. Recalculates feedback for all existing chats and adds flags for filtering. This function runs slowly and is executed asynchronously -- the API will not return a result. Check the logs for the message: `Migration feedback completed!` + +## New Features + +1. Tool calls now support configurable streaming output. +2. AI credit alert notifications. +3. Chat logs now display IP geolocation. +4. Chat logs now display the app version name (if the version is updated mid-conversation, it will reflect the latest version). +5. Chat logs support filtering by thumbs up/down, with quick navigation to liked/disliked records in the chat details. +6. Upload local files to knowledge base via API, now saved to S3. All legacy GridFS code has been removed. +7. New subscription plan logic. +8. Configurable file whitelist for chat file uploads. +9. S3 now supports pathStyle and region configuration. +10. Support for multi-tenant custom domain configuration via Sealos. +11. File input in workflow tool references now supports manual entry (previously only variable references were supported). +12. Network proxy support (HTTP_PROXY, HTTPS_PROXY). + +## Improvements + +1. Increased S3 file upload timeout to 5 minutes. +2. Question optimization now uses JinaAI's marginal utility formula to find the search term with the highest marginal gain. +3. User notifications now support both Chinese and English, with improved templates. +4. Knowledge base deletion now uses an asynchronous queue-based approach. +5. Improved error messages for invalid images in LLM requests. +6. Completions API in non-stream mode with detail=false now includes `reason_content` in the response. +7. Added detection for invalid S3 keys. +8. Deleting apps and knowledge bases now requires entering the name for confirmation. +9. Mongo slow operation logs now accurately print the collection name and operation details. +10. Share link custom authentication: the returned uid is now limited to 200 characters max (longer values affected file uploads). + +## Bug Fixes + +1. Loop node arrays no longer filter out empty content. +2. Workflow tools did not pass custom DataId, causing "no permission" errors when viewing knowledge base during test runs. +3. In Chat Agent tool configuration, non-required boolean and number types could not be confirmed directly. +4. Workbench cards were misaligned when names were too long. +5. Global variables passed via URL query parameters in share links were not loaded in the frontend UI. +6. CSV file detection failed on Windows. +7. Models that were not started could not be tested during model testing. +8. MCP headers with special content caused errors. +9. When referencing another Agent in a workflow, the UI was not updated after switching versions. +10. HTTP node used null instead of empty string for global variables with empty string values. +11. Condition node connections broke when the node was collapsed. +12. Single-select and multi-select variable options were not displayed during node debugging. +13. Publish channel documentation links pointed to incorrect locations. +14. Checkbox hover style was incorrect in disabled state. +15. Default huggingface.svg icon displayed incorrectly when model avatar was missing. +16. Log export end date was off by one day. +17. Form input frontend default values were not passed to the actual values. +18. max_tokens parameter was not passed during tool calls. +19. Workflow condition node value type was not determined by combining the condition with the value. +20. Knowledge base data not using direct chunking mode had incorrect citation reader navigation order. The citation reader only loaded the same page. + +## Plugin Updates + +1. Added: GLM 4.6 and DeepSeek 3.2 series model presets. +2. Fixed: MinerU SaaS plugin could not select the VLM model version. +3. Fixed: WeChat Official Account plugin batch Markdown upload parameter passing issue. +4. Added: Tool to retrieve WeChat Official Account draft box list. +5. Improvement: Markdown-to-file now supports custom file names. +6. Fixed: Import cache issue preventing plugins from being updated. diff --git a/document/content/docs/upgrading/4-14/4145.en.mdx b/document/content/docs/upgrading/4-14/4145.en.mdx new file mode 100644 index 0000000000..d6c2b79306 --- /dev/null +++ b/document/content/docs/upgrading/4-14/4145.en.mdx @@ -0,0 +1,103 @@ +--- +title: 'V4.14.5 (Includes Upgrade Script)' +description: 'FastGPT V4.14.5 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Storage Bucket Environment Variables + +This version adds native support for OSS and COS in addition to MinIO, so the related environment variables need to be renamed. Below is the configuration for MinIO. For other providers, refer to [Object Storage Configuration](/docs/introduction/development/object-storage). + +**New Variables** + +``` +STORAGE_VENDOR=minio +STORAGE_REGION=us-east-1 +STORAGE_ACCESS_KEY_ID=minioadmin +STORAGE_SECRET_ACCESS_KEY=minioadmin +STORAGE_PUBLIC_BUCKET=fastgpt-public +STORAGE_PRIVATE_BUCKET=fastgpt-private +STORAGE_EXTERNAL_ENDPOINT=http://192.168.0.2:9000 # An address accessible by both the server and client. Can be a static host IP or domain name. Do not use 127.0.0.1 or localhost (containers cannot access loopback addresses). +STORAGE_S3_ENDPOINT=http://fastgpt-minio:9000 # protocol://domain(IP):port +``` + +**Remove Old Variables** + +* S3_EXTERNAL_BASE_URL +* S3_ENDPOINT +* S3_PORT +* S3_USE_SSL +* S3_ACCESS_KEY +* S3_SECRET_KEY +* S3_PUBLIC_BUCKET +* S3_PRIVATE_BUCKET + +### 2. Update Images: + +- Update FastGPT image tag: v4.14.5-fix +- Update FastGPT commercial edition image tag: v4.14.5 +- Update fastgpt-plugin image tag: v0.4.0 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed +- Update mongo 5.x to version 5.0.32 to fix CVE-2025-14847. Simply change the image tag to `5.0.32`. + +### 3. Run the Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4145' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +1. Retries all failed S3 deletion tasks. +2. Adds the `showFullText` field to all share-type OutLink records. +3. Renames fields: + - showNodeStatus -> showRunningStatus + - responseDetail -> showCite + - showRawSource -> canDownloadSource + + +## New Features + +1. Workflow canvas now includes a demo mode, with improved collapsed mode styling and reduced edge overlap. +2. Workflow now has a quick-jump button for nested apps. +3. Workflow export now supports choosing whether to filter sensitive information. +4. Chat record deletion is now soft-delete, with the ability to delete chat records from the log management page. +5. When updating an Agent/tool, the update timestamp is propagated to all parent directories so they appear at the top of the list. +6. Portal page now supports configuring visibility for individual app execution. +7. API endpoint to export chunks from a single knowledge base collection. +8. Upgraded Mongo 5.x to 5.0.32 to fix CVE-2025-14847. +9. Email configuration now supports configuring security mode and port number. + +## Improvements + +1. Optimized Redis key retrieval logic to prevent blocking when fetching a large number of keys. +2. Improved reconnection logic for MongoDB, Redis, and MQ. +3. Variable input fields can now be copied in disabled state. +4. LLM empty response detection now excludes content filter errors from being misidentified as no response. +5. Improved error messages for AI chat and tool calls with more raw data. +6. Increased file parsing API request size limit to 10MB. +7. Citation list below chat responses now only shows knowledge base content actually cited by the AI. +8. Updated MCP SDK version. +9. Optimized Chats table indexes: reduced redundancy and added conditional indexes. + +## Bug Fixes + +1. Critical: Workflow parallel merge could cause duplicate execution. +2. MCP tool creation with custom auth headers threw an error. +3. Fetching chat log list threw an error when user avatar was empty. +4. chatAgent showed question optimization as enabled in the frontend UI when it was actually disabled. +5. maxTokens field was not assigned when loading default models, causing empty model max response configuration. +6. S3 file cleanup queue was blocked due to network instability, preventing deletion tasks from executing. +7. Chat log API adapted for mongo 4.x syntax. +8. Variable update node incorrectly converted file URL string arrays to object arrays. +9. Multiple form input nodes sharing sessionStorage caused default values not to display. +10. Code execution node still used the old language for AI code generation after switching languages. +11. Multiple custom feedback nodes writing concurrently triggered database write conflicts. +12. Custom feedback nodes following interactive nodes failed to write. + +## Plugin Updates diff --git a/document/content/docs/upgrading/4-14/41451.en.mdx b/document/content/docs/upgrading/4-14/41451.en.mdx new file mode 100644 index 0000000000..34fd59cc97 --- /dev/null +++ b/document/content/docs/upgrading/4-14/41451.en.mdx @@ -0,0 +1,47 @@ +--- +title: 'V4.14.5.1 (Includes Upgrade Script)' +description: 'FastGPT V4.14.5.1 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.14.5.1 +- Update FastGPT commercial edition image tag: v4.14.5.1 +- Update fastgpt-plugin image tag: v0.4.0 +- mcp_server: no update needed +- Sandbox: no update needed +- AIProxy: no update needed +- mongo: no update needed + +### 2. Run the Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv41451' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +1. Migrates system secret key configuration for system tools. + +## New Features + +1. Markdown tables now support CSV export. + +## Improvements + +1. Workflow trackpad scrolling is no longer blocked when encountering input fields. +2. Workflow node paste now positions precisely at the mouse cursor. +3. Precisely removes extraneous system fields from LLM requests to prevent errors with certain model APIs. +4. Uses path.extname to extract file extensions from URLs. + +## Bug Fixes + +1. After setting system secret keys for a system toolset, child tools could not read the configured secret keys. +2. Password-type global variables had incorrect required field validation. +3. Time-type global variable month picker was obscured. +4. Line breaks were lost in the manual copy dialog. +5. Chat API threw an error when file upload type variables were not provided. diff --git a/document/content/docs/upgrading/4-14/4146.en.mdx b/document/content/docs/upgrading/4-14/4146.en.mdx new file mode 100644 index 0000000000..1006090680 --- /dev/null +++ b/document/content/docs/upgrading/4-14/4146.en.mdx @@ -0,0 +1,65 @@ +--- +title: 'V4.14.6' +description: 'FastGPT V4.14.6 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.14.6.1 +- Update FastGPT commercial edition image tag: v4.14.6 +- Update fastgpt-plugin image tag: v0.5.2 +- mcp_server: no update needed +- sandbox: no update needed +- AIProxy: no update needed +- mongo: no update needed + +### 2. Update System Plugins + +Go to the Plugin Marketplace and update the following system tools (skip this step if you already upgraded to 4.14.6): + +* base64Decode: Base64 decode conversion +* dallle3: DALL-E 3 image generation +* docDiff: Document diff comparison +* drawing: BI charts +* gptImage: GPT image generation +* markdownTransform: Markdown file conversion +* mineru: MinerU PDF parsing +* minimax: MiniMax chat +* openrouterMultiModal: OpenRouter multimodal +* stability: Stability image generation + +## New Features + +1. System tools now support configurable custom category attributes. +2. Subscription plans now support configuring maximum file upload count and size. +3. Plugin Marketplace supports batch plugin updates. +4. Cloud service supports dedicated WeCom integration. +5. Seekdb vector database preset configuration. + +## Improvements + +### Feature Improvements +1. Workflow trackpad scrolling is no longer blocked when encountering input fields. +2. Workflow node paste now positions precisely at the mouse cursor. +3. Precisely removes extraneous system fields from LLM requests to prevent errors with certain model APIs. + +### Code Quality + +1. Replaced useRequest with useRequest2 to reduce unused code. + +## Bug Fixes + +1. After setting system secret keys for a system toolset, child tools could not read the configured secret keys. +2. Date picker overflow issue resolved with dynamic position adaptation. +3. "Explore More" link for system tools on the workflow editor page pointed to the wrong URL. +4. Default model avatar path /imgs/model/huggingface.svg was incorrect. +5. Empty values are now filtered out when setting tool tags. + +## Plugin Updates + +1. Added tutorial documentation for Lark Multidimensional Table. +2. WeCom-related plugins: Get WeCom enterprise access_token; WeCom smart table toolset. +3. Added model preset for qwen-flash. +4. Adjusted preset parameters for qwen3-max and qwen-plus. diff --git a/document/content/docs/upgrading/4-14/4147.en.mdx b/document/content/docs/upgrading/4-14/4147.en.mdx new file mode 100644 index 0000000000..7b6c789456 --- /dev/null +++ b/document/content/docs/upgrading/4-14/4147.en.mdx @@ -0,0 +1,117 @@ +--- +title: 'V4.14.7 (Includes Upgrade Script)' +description: 'FastGPT V4.14.7 Release Notes' +--- + +## Upgrade Guide + +### 1. Update Images + +- Update FastGPT image tag: v4.14.7.2 +- Update FastGPT commercial edition image tag: v4.14.7.1 +- Update fastgpt-plugin image tag: v0.5.4 +- mcp_server: no update needed (4.14.7 image is not available; use the previous version) +- sandbox: no update needed +- Update AIProxy image tag: 0.3.15 +- mongo: no update needed + +### 2. Update System Environment Variables + +The logging system has been updated, including log output, log collection, and log analysis. + +```dotenv +# Remove these environment variables +LOG_LEVEL= +STORE_LOG_LEVEL= +SIGNOZ_BASE_URL= +SIGNOZ_SERVICE_NAME= +SIGNOZ_STORE_LEVEL= + +# Add the following 6 variables (same variables for fastgpt, fastgpt-pro, fastgpt-plugin, and fastgpt-mcp-server) +LOG_ENABLE_CONSOLE=true # Enable console output +LOG_CONSOLE_LEVEL=debug # Minimum log level for console output +LOG_ENABLE_OTEL=false # 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 URL. Do not omit /v1/logs +``` + +### 3. Update System Plugins + +Go to the Plugin Marketplace and update the following system tools (skip this step if you already upgraded to 4.14.6). You can also directly download the [zip package](https://github.com/labring/fastgpt-plugin/raw/refs/heads/main/.github/assets/upgrade_pkg.zip) and install it. + +* base64Decode: Base64 decode conversion +* dallle3: DALL-E 3 image generation +* docDiff: Document diff comparison +* drawing: BI charts +* gptImage: GPT image generation +* markdownTransform: Markdown file conversion +* mineru: MinerU PDF parsing +* minimax: MiniMax chat +* openrouterMultiModal: OpenRouter multimodal +* stability: Stability image generation + +### 4. Run the Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4147' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +1. Adds chat log records containing errors to the statistics table. + +### 5. API Changes + +In the new version's chat records, the `type` field has been removed from the value. `/api/core/chat/getPaginationRecords` has temporary backward compatibility, but users of this API should update their value parsing logic as soon as possible -- simply check whether fields like `text`, `tools`, etc. exist. + +## New Features + +1. Context-engineering-based Agent mode, suitable for long task decomposition scenarios. (Beta) +2. Temporarily added LLM request tracing for debugging. All LLM request bodies and responses are retained (default retention: 6 hours, configurable via `LLM_REQUEST_TRACKING_RETENTION_HOURS`). +3. Knowledge base search now supports filtering by collectionIds. +4. Model monitoring now includes cache hit rate. +5. Share link with custom authentication: the finish event now transmits chatId. +6. Chat log list now includes an error-only filter option. +7. Chat log list now supports precise user filtering. +8. Dependency pre-check: validates infrastructure and sub-service availability at startup for easier troubleshooting. +9. MCP service parsing now supports `$ref` syntax in schemas. +10. Rebuilt the logging system using [LogTape](https://logtape.org/), covering log output, collection, and analysis. Mongo-based log storage has been removed -- use an OTEL collector instead. + +## Improvements + +1. Improved UX for tool selection and knowledge base selection in Chat Agent. +2. MCP now automatically filters out extraneous fields on save to maintain mongo 4.x compatibility. +3. Backend automatically filters out unconfigured tools to prevent model errors from calling unconfigured tools. Uses the same filter function to ensure frontend-backend consistency. +4. Added memory selection for workflow AI models in chat log mode. +5. Tool calls now auto-fill empty arguments with `"{}"` to prevent errors from providers that don't support empty strings. +6. Adapted for Kimi 2.5 tool calls in thinking mode. +7. Improved internal network domain validation. +8. Orphaned edges are removed before workflow execution. +9. When calling workflows via API with file links, the file type is now saved directly from the input instead of being inferred from the URL, ensuring 100% correct file types. + +## Bug Fixes + +1. Some global variable types had incorrect defaultValueType assignments in workflows. +2. Workflow AI node thinking output was not rendered correctly. +3. Precisely retrieves permissions for individual MCP sub-tools to prevent unauthorized access. +4. Toolset ToolName starting with a number caused tool call failures. +5. Converting a simple app to a workflow did not duplicate the avatar. +6. When importing workflows, reference-type model fields were incorrectly identified as invalid models and cleared. +7. On iPhone Safari, share links had a chance of triggering requests with an empty uid on first visit. +8. MCP could not pass file links when exposing an Agent. +9. Creating an HTTP tool with variables in the body caused JSON parsing errors. +10. Workflow canvas auto-positioning stopped working after switching tabs. +11. When a workflow node encountered an uncaught system error, it did not correctly follow the error capture branch. + +## Plugin Updates + +1. Added user info retrieval tool. +2. Added Kimi 2.5 model preset. + +## Code Quality + +1. Added vector database integration tests. +2. Improved packages/global unit test coverage to 90+. diff --git a/document/content/docs/upgrading/4-14/4148.en.mdx b/document/content/docs/upgrading/4-14/4148.en.mdx new file mode 100644 index 0000000000..89d63d4362 --- /dev/null +++ b/document/content/docs/upgrading/4-14/4148.en.mdx @@ -0,0 +1,17 @@ +--- +title: 'V4.14.8 (In Progress)' +description: 'FastGPT V4.14.8 Release Notes' +--- + + +## New Features + +1. Upgraded Next.js to version 15. + +## Improvements + +1. Compatible with MCP JSON Schema type values not in the enum type list. + +## Bug Fixes + +1. New SDK compatibility: consecutive calls to the same MCP service caused errors due to multiple connections. diff --git a/document/content/docs/upgrading/4-14/meta.en.json b/document/content/docs/upgrading/4-14/meta.en.json new file mode 100644 index 0000000000..61a286ee63 --- /dev/null +++ b/document/content/docs/upgrading/4-14/meta.en.json @@ -0,0 +1,16 @@ +{ + "title": "4.14.x", + "description": "", + "pages": [ + "4148", + "4147", + "4146", + "41451", + "4145", + "4144", + "4143", + "4142", + "4141", + "4140" + ] +} diff --git a/document/content/docs/upgrading/4-8/40.en.mdx b/document/content/docs/upgrading/4-8/40.en.mdx new file mode 100644 index 0000000000..bf2372de2a --- /dev/null +++ b/document/content/docs/upgrading/4-8/40.en.mdx @@ -0,0 +1,64 @@ +--- +title: V4.0 +description: Upgrade guide from older versions to FastGPT V4.0 +--- + +import { Alert } from '@/components/docs/Alert'; + +If you are **upgrading from an older version to V4**, the MongoDB schema has changed significantly. You'll need to run the initialization scripts described below. + +## Rename Collections + +Connect to your MongoDB database and run these two commands: + +```js +db.models.renameCollection('apps'); +db.sharechats.renameCollection('outlinks'); +``` + + + Note: When upgrading from an older version to V4, MongoDB will automatically create empty collections with these names. You need to manually drop those empty collections first before running the commands above. + + +## Initialize Fields in Several Collections + +Run the following 3 commands sequentially. They may take a while to complete. If a command fails, you can safely re-run it (already-initialized records will be skipped) until all data has been updated. + +```js +db.chats.find({ appId: { $exists: false } }).forEach(function (item) { + db.chats.updateOne( + { + _id: item._id + }, + { $set: { appId: item.modelId } } + ); +}); + +db.collections.find({ appId: { $exists: false } }).forEach(function (item) { + db.collections.updateOne( + { + _id: item._id + }, + { $set: { appId: item.modelId } } + ); +}); + +db.outlinks.find({ shareId: { $exists: false } }).forEach(function (item) { + db.outlinks.updateOne( + { + _id: item._id + }, + { $set: { shareId: item._id.toString(), appId: item.modelId } } + ); +}); +``` + +## Initialization APIs + +Deploy the new version, then send 3 HTTP requests (remember to include `headers.rootkey` — this value comes from your environment variables): + +1. https://xxxxx/api/admin/initv4 +2. https://xxxxx/api/admin/initChat +3. https://xxxxx/api/admin/initOutlink + +Requests 1 and 2 may crash due to insufficient memory. If that happens, simply re-run them. diff --git a/document/content/docs/upgrading/4-8/41.en.mdx b/document/content/docs/upgrading/4-8/41.en.mdx new file mode 100644 index 0000000000..ff3397d1e1 --- /dev/null +++ b/document/content/docs/upgrading/4-8/41.en.mdx @@ -0,0 +1,25 @@ +--- +title: V4.1 +description: Upgrade guide from older versions to FastGPT V4.1 +--- + +If you are **upgrading from an older version to V4.1**, the chat storage structure has been redesigned. You'll need to initialize the existing stored data. + +## Update Environment Variables + +V4.1 simplified the PostgreSQL and MongoDB connection variables — you now only need a single URL for each: + +Note: `/fastgpt` and `/postgres` refer to database names and must match the values from your previous configuration. + +```bash +# MongoDB config — no changes needed. If connection fails, try removing ?authSource=admin +- MONGODB_URI=mongodb://username:password@mongo:27017/fastgpt?authSource=admin +# PostgreSQL config — no changes needed +- PG_URL=postgresql://username:password@pg:5432/postgres +``` + +## Initialization API + +Deploy the new version, then send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables): + +- https://xxxxx/api/admin/initChatItem diff --git a/document/content/docs/upgrading/4-8/42.en.mdx b/document/content/docs/upgrading/4-8/42.en.mdx new file mode 100644 index 0000000000..ae1c4fb25b --- /dev/null +++ b/document/content/docs/upgrading/4-8/42.en.mdx @@ -0,0 +1,17 @@ +--- +title: V4.2 +description: Upgrade guide from older versions to FastGPT V4.2 +--- + +99.9% of users are unaffected. The V4.2 upgrade primarily changes the `QAModel` format in the configuration file, converting it from an array to an object: + +```json +"QAModel": { + "model": "gpt-3.5-turbo-16k", + "name": "GPT35-16k", + "maxToken": 16000, + "price": 0 +} +``` + +The rationale behind this change is that there's no need to offer multiple choices — just pick the most suitable model for the task. diff --git a/document/content/docs/upgrading/4-8/421.en.mdx b/document/content/docs/upgrading/4-8/421.en.mdx new file mode 100644 index 0000000000..dfaf8d151c --- /dev/null +++ b/document/content/docs/upgrading/4-8/421.en.mdx @@ -0,0 +1,20 @@ +--- +title: V4.2.1 +description: Upgrade guide from older versions to FastGPT V4.2.1 +--- + +For self-hosted deployments with a custom configuration file, you need to update the `VectorModels` field. Add `defaultToken` and `maxToken` — these correspond to the default token count for direct chunking and the maximum token limit supported by the model (generally recommended not to exceed 3000). + +```json +"VectorModels": [ + { + "model": "text-embedding-ada-002", + "name": "Embedding-2", + "price": 0, + "defaultToken": 500, + "maxToken": 3000 + } +] +``` + +The rationale behind this change is that there's no need to offer multiple choices — just pick the most suitable model for the task. diff --git a/document/content/docs/upgrading/4-8/43.en.mdx b/document/content/docs/upgrading/4-8/43.en.mdx new file mode 100644 index 0000000000..9fa3dc0d95 --- /dev/null +++ b/document/content/docs/upgrading/4-8/43.en.mdx @@ -0,0 +1,26 @@ +--- +title: V4.3 (includes upgrade script) +description: Upgrade guide from older versions to FastGPT V4.3 +--- + +## Run the Initialization API + +Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables): + +1. https://xxxxx/api/admin/initv43 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv43' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will add a new `file_id` column to the `modeldata` table in PostgreSQL, used for storing file IDs. + +## Add Environment Variable + +Add a `FILE_TOKEN_KEY` environment variable, used to generate file preview links with a 30-minute expiration. + +``` +FILE_TOKEN_KEY=filetokenkey +``` diff --git a/document/content/docs/upgrading/4-8/44.en.mdx b/document/content/docs/upgrading/4-8/44.en.mdx new file mode 100644 index 0000000000..d6c5cfc6ef --- /dev/null +++ b/document/content/docs/upgrading/4-8/44.en.mdx @@ -0,0 +1,18 @@ +--- +title: V4.4 (includes upgrade script) +description: Upgrade guide from older versions to FastGPT V4.4 +--- + +## Run the Initialization API + +Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables): + +1. https://xxxxx/api/admin/initv44 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv44' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will initialize certain fields in MongoDB. diff --git a/document/content/docs/upgrading/4-8/441.en.mdx b/document/content/docs/upgrading/4-8/441.en.mdx new file mode 100644 index 0000000000..51ad231d88 --- /dev/null +++ b/document/content/docs/upgrading/4-8/441.en.mdx @@ -0,0 +1,18 @@ +--- +title: V4.4.1 (includes upgrade script) +description: Upgrade guide from older versions to FastGPT V4.4.1 +--- + +## Run the Initialization API + +Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables): + +1. https://xxxxx/api/admin/initv441 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv441' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will initialize the `dataset.files` collection in MongoDB, marking all data as available. diff --git a/document/content/docs/upgrading/4-8/442.en.mdx b/document/content/docs/upgrading/4-8/442.en.mdx new file mode 100644 index 0000000000..e100ffd6af --- /dev/null +++ b/document/content/docs/upgrading/4-8/442.en.mdx @@ -0,0 +1,18 @@ +--- +title: V4.4.2 (includes upgrade script) +description: Upgrade guide from older versions to FastGPT V4.4.2 +--- + +## Run the Initialization API + +Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables): + +1. https://xxxxx/api/admin/initv442 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv442' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will reinitialize the indexes on the MongoDB `Bill` collection, as the previous TTL expiration was incorrect. diff --git a/document/content/docs/upgrading/4-8/445.en.mdx b/document/content/docs/upgrading/4-8/445.en.mdx new file mode 100644 index 0000000000..84f90670d0 --- /dev/null +++ b/document/content/docs/upgrading/4-8/445.en.mdx @@ -0,0 +1,27 @@ +--- +title: V4.4.5 (includes upgrade script) +description: FastGPT V4.4.5 Update +--- + +## Run the Initialization API + +Send 1 HTTP request (remember to include `headers.rootkey` — this value comes from your environment variables): + +1. https://xxxxx/api/admin/initv445 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv445' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This initializes the variable module by merging it into the user guide module. + +## What's New + +### FastGPT V4.4.5 + +1. Added — Next-step suggestions: the model can now generate 3 predicted follow-up questions. +2. Commercial edition — Share link restrictions and hook-based identity verification (can integrate with your existing user system). +3. Commercial edition — API Key management: added alias, quota limits, and expiration. Includes a built-in appId, so no additional connection is needed. +4. Improved — Global variables and opening message merged into a single module. diff --git a/document/content/docs/upgrading/4-8/446.en.mdx b/document/content/docs/upgrading/4-8/446.en.mdx new file mode 100644 index 0000000000..2b198ee9df --- /dev/null +++ b/document/content/docs/upgrading/4-8/446.en.mdx @@ -0,0 +1,10 @@ +--- +title: V4.4.6 +description: FastGPT V4.4.6 Update +--- + +## What's New + +1. Advanced orchestration — New "App Call" module that lets you invoke other apps. +2. Added — Required connection validation. +3. Fixed — Identity issue with next-step suggestions in anonymous (no-login) mode. diff --git a/document/content/docs/upgrading/4-8/447.en.mdx b/document/content/docs/upgrading/4-8/447.en.mdx new file mode 100644 index 0000000000..e9b0c96191 --- /dev/null +++ b/document/content/docs/upgrading/4-8/447.en.mdx @@ -0,0 +1,27 @@ +--- +title: V4.4.7 (includes upgrade script) +description: FastGPT V4.4.7 Update (includes upgrade script) +--- + +## Run the Initialization API + +Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain): + +1. https://xxxxx/api/admin/initv447 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv447' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This initializes PostgreSQL indexes and converts empty `file_id` objects to `manual` objects. If you have a large dataset, this may take a while — you can monitor progress via logs. + +## What's New + +### FastGPT V4.4.7 + +1. Improved Knowledge Base file CRUD operations. +2. Added support for reading links as a data source. +3. Differentiated between manual entries and annotations, enabling data traceability back to a specific file. +4. Upgraded the OpenAI SDK. diff --git a/document/content/docs/upgrading/4-8/45.en.mdx b/document/content/docs/upgrading/4-8/45.en.mdx new file mode 100644 index 0000000000..49a39d76f4 --- /dev/null +++ b/document/content/docs/upgrading/4-8/45.en.mdx @@ -0,0 +1,87 @@ +--- +title: V4.5 (Complex Update Required) +description: FastGPT V4.5 Update +--- + +FastGPT V4.5 introduces PgVector 0.5's HNSW index, which dramatically improves knowledge base search performance — roughly 3x to 10x faster than the `IVFFlat` index, easily achieving millisecond-level searches across millions of records. The downside is that index building is very slow: on a 4C16G machine with 5 million records, a `parallel build` took about 48 hours. For detailed parameter configuration, refer to the [PgVector official documentation](https://github.com/pgvector/pgvector). + +The following database operations are required for the upgrade: + +## PgVector Upgrade: Sealos Deployment + +1. Open the Database app from the [Sealos Desktop](https://cloud.sealos.io?uid=fnWRt09fZP). +2. Click on the details of the **pg** database. +3. Click Restart in the upper-right corner and wait for it to complete. +4. Click "One-Click Connect" on the left sidebar and wait for the Terminal to open. +5. Run the following SQL commands in order: + +```sql +-- Upgrade the extension +ALTER EXTENSION vector UPDATE; +-- Verify the upgrade was successful — the vector extension version should be 0.5.0 (previously 0.4.1) +\dx + +-- The following two statements set the memory available to PG during index building. Adjust based on your database specs — a good rule of thumb is 1/4 of total memory. +alter system set maintenance_work_mem = '2400MB'; +select pg_reload_conf(); + +-- Rebuild database indexes and collation +REINDEX DATABASE postgres; + +-- Start building the index. This takes a very long time — just close the Terminal by clicking the X in the upper-right corner. +CREATE INDEX CONCURRENTLY vector_index ON modeldata USING hnsw (vector vector_ip_ops) WITH (m = 16, ef_construction = 64); +-- You can reconnect to the Terminal and run the command below. If you see "vector_index" hnsw (vector vector_ip_ops) WITH (m='16', ef_construction='64'), the build is complete (make sure there is no INVALID at the end). +\d modeldata +``` + +| | | +| -------------------- | -------------------- | +| ![](/imgs/v45-1.jpg) | ![](/imgs/v45-2.jpg) | +| ![](/imgs/v45-3.jpg) | ![](/imgs/v45-4.jpg) | + +## PgVector Upgrade: Docker Compose Deployment + +The commands below are based on the provided docker-compose template. If you've changed the database username or password, adjust accordingly. + +1. Update the PG image version in `docker-compose.yml` to `ankane/pgvector:v0.5.0` or `registry.cn-hangzhou.aliyuncs.com/fastgpt/pgvector:v0.5.0`. +2. Restart the PG container (`docker-compose pull && docker-compose up -d`) and wait for it to complete. +3. Enter the container: `docker exec -it pg bash` +4. Connect to the database: `psql 'postgresql://username:password@localhost:5432/postgres'` +5. Run the following SQL commands: + +```sql +-- Upgrade the extension +ALTER EXTENSION vector UPDATE; +-- Verify the upgrade was successful — the vector extension version should be 0.5.0 (previously 0.4.2) +\dx + +-- The following two statements set the memory available to PG during index building. Adjust based on your database specs — a good rule of thumb is 1/4 of total memory. +alter system set maintenance_work_mem = '2400MB'; +select pg_reload_conf(); + +-- Rebuild database indexes and collation +REINDEX DATABASE postgres; +ALTER DATABASE postgres REFRESH COLLATION VERSION; + +-- Start building the index. This takes a very long time — just close the terminal window. Do NOT use ctrl+c to cancel. +CREATE INDEX CONCURRENTLY vector_index ON modeldata USING hnsw (vector vector_ip_ops) WITH (m = 16, ef_construction = 64); +-- You can reconnect to the database and run the command below. If you see "vector_index" hnsw (vector vector_ip_ops) WITH (m='16', ef_construction='64'), the build is complete (make sure there is no INVALID at the end). +\d modeldata + + +``` + +## New Features + +### Fast GPT V4.5 + +1. New - Upgraded PgVector extension with HNSW index, dramatically improving knowledge base search speed. +2. New - AI Chat node now includes a "Return AI Content" option, allowing you to prevent AI responses from being sent directly to the browser. +3. New - Support for selecting models in the Question Classifier. +4. Improved - TextSplitter now uses a recursive splitting approach. +5. Improved - Advanced orchestration UX performance. +6. Fixed - Share link authentication issue. + +## Configuration File Changes Required + +For the latest configuration, refer to: [V4.5 Latest config.json](/docs/introduction/development/configuration) diff --git a/document/content/docs/upgrading/4-8/451.en.mdx b/document/content/docs/upgrading/4-8/451.en.mdx new file mode 100644 index 0000000000..df6d498cac --- /dev/null +++ b/document/content/docs/upgrading/4-8/451.en.mdx @@ -0,0 +1,32 @@ +--- +title: V4.5.1 (Includes Migration Script) +description: FastGPT V4.5.1 Update +--- + +## Run the Initialization API + +Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain). + +1. https://xxxxx/api/admin/initv451 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv451' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +What the initialization does: + +1. Renames database fields. +2. Initializes knowledge base-related fields in the Mongo APP collection. +3. Initializes PG and Mongo content — creates a collection in Mongo for each file and assigns the references back to PG. + +**This initialization endpoint may be very slow. If the request times out, don't worry — just check the logs.** + +## What's New + +### Fast GPT V4.5.1 + +1. New - Knowledge base folder management. +2. Fixed - OpenAI 4.x SDK incompatibility with OneAPI's Zhipu and Alibaba interfaces. +3. Fixed - Some nodes failing to trigger completion events. diff --git a/document/content/docs/upgrading/4-8/452.en.mdx b/document/content/docs/upgrading/4-8/452.en.mdx new file mode 100644 index 0000000000..9b85b296f1 --- /dev/null +++ b/document/content/docs/upgrading/4-8/452.en.mdx @@ -0,0 +1,11 @@ +--- +title: V4.5.2 +description: FastGPT V4.5.2 Update +--- + +## What's New + +### Fast GPT V4.5.2 + +1. New - Module plugins, allowing you to assemble custom plugins for module reuse. +2. Improved - Knowledge base citation prompts. diff --git a/document/content/docs/upgrading/4-8/46.en.mdx b/document/content/docs/upgrading/4-8/46.en.mdx new file mode 100644 index 0000000000..8e47f00aa4 --- /dev/null +++ b/document/content/docs/upgrading/4-8/46.en.mdx @@ -0,0 +1,61 @@ +--- +title: V4.6 (Includes Migration Script) +description: FastGPT V4.6 Update +--- + +**V4.6 introduces basic team functionality, allowing you to invite other users to manage resources collaboratively. After upgrading to this version, older migration scripts cannot be run, and the upgrade cannot be rolled back.** + +## 1. Update Images and Modify Configuration + +Update the image to the latest or V4.6 version. For the commercial edition, update to V0.2.1. + +For the latest configuration, refer to: [V4.6 Latest config.json](/docs/introduction/development/configuration). The commercial edition configuration file has also been updated — refer to the latest Lark documentation. + +## 2. Run the Initialization APIs + +Send 2 HTTP requests (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain). + +**These initialization endpoints may be very slow. If the request times out, don't worry — just check the logs. Important: Make sure initv46 completes successfully before running initv46-2.** + +1. https://xxxxx/api/admin/initv46 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv46' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +2. https://xxxxx/api/admin/initv46-2 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv46-2' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +What the initialization does: +1. Creates the default team. +2. Initializes team fields for all resources in Mongo. +3. Initializes PG fields. +4. Initializes Mongo Data. + +## V4.6 New Features + +1. New - Team workspace. +2. New - Multi-vector support (multiple vectors mapped to a single dataset). +3. New - TTS (text-to-speech). +4. New - Support for configuring text preprocessing models in knowledge bases. +5. New (Online environment) - ReRank vector recall for improved retrieval accuracy. +6. Improved - Knowledge base export now triggers a streaming download instead of showing a loading spinner. + +## V4.6 Bug Fix + +The initial V4.6 release was missing a field, which caused knowledge base data to not display during file imports. Run the following script to fix this: + +https://xxxxx/api/admin/initv46-fix + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv46-fix' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` diff --git a/document/content/docs/upgrading/4-8/461.en.mdx b/document/content/docs/upgrading/4-8/461.en.mdx new file mode 100644 index 0000000000..536d1902d4 --- /dev/null +++ b/document/content/docs/upgrading/4-8/461.en.mdx @@ -0,0 +1,12 @@ +--- +title: V4.6.1 +description: FastGPT V4.6.1 +--- + + +## V4.6.1 New Features + +1. New - GPT-4V model support. +2. New - Whisper voice input. +3. Improved - TTS streaming. +4. Improved - TTS caching. diff --git a/document/content/docs/upgrading/4-8/462.en.mdx b/document/content/docs/upgrading/4-8/462.en.mdx new file mode 100644 index 0000000000..984e8f3ea2 --- /dev/null +++ b/document/content/docs/upgrading/4-8/462.en.mdx @@ -0,0 +1,28 @@ +--- +title: V4.6.2 (Includes Migration Script) +description: FastGPT V4.6.2 +--- + +## 1. Run the Initialization API + +Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain). + +1. https://xxxxx/api/admin/initv462 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv462' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +What the initialization does: + +1. Initializes full-text indexing. + +## V4.6.2 New Features + +1. New - Full-text indexing (requires a ReRank model; working on making it available in the community edition — the model API is somewhat specialized). +2. New - Plugin sources (expected to be officially used in V4.7/V4.8). +3. Improved - PDF parsing. +4. Improved - DOCX file parsing, now converts to Markdown while preserving images. +5. Fixed and improved the TextSplitter function. diff --git a/document/content/docs/upgrading/4-8/463.en.mdx b/document/content/docs/upgrading/4-8/463.en.mdx new file mode 100644 index 0000000000..f2db5571ef --- /dev/null +++ b/document/content/docs/upgrading/4-8/463.en.mdx @@ -0,0 +1,29 @@ +--- +title: V4.6.3 (Includes Migration Script) +description: FastGPT V4.6.3 +--- + +## 1. Run the Initialization API + +Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain). + +1. https://xxxxx/api/admin/initv463 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv463' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +What the initialization does: +1. Initializes certain fields in the Mongo dataset, collection, and data documents. + +## V4.6.3 New Features + +1. New (Commercial edition) - Web site sync. +2. New - Collection metadata tracking. +3. Improved - URL content fetching. +4. Improved - Streaming file reads to prevent memory overflow. +5. Improved - Vision models now automatically convert URLs to base64, enabling local debugging. +6. Improved - Image compression quality levels. +7. Fixed - Image compression failure errors that could cause file reading to hang. diff --git a/document/content/docs/upgrading/4-8/464.en.mdx b/document/content/docs/upgrading/4-8/464.en.mdx new file mode 100644 index 0000000000..f5136c495d --- /dev/null +++ b/document/content/docs/upgrading/4-8/464.en.mdx @@ -0,0 +1,37 @@ +--- +title: V4.6.4 (Includes Migration Script) +description: FastGPT V4.6.4 +--- + +## 1. Run the Initialization API + +Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain). + +1. https://xxxxx/api/admin/initv464 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv464' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +What the initialization does: + +1. Initializes the createTime field in PG. +2. Initializes the feedback field for chats in Mongo. + +## V4.6.4 New Features + +1. Rewritten - Share link identity logic, now using localID to track user IDs. +2. New (Commercial edition) - Share link SSO support. With just 3 API endpoints via an authentication URL, you can fully integrate your existing user system. See [Share Link Authentication](/docs/openapi/share/) for details. +3. New - More embedding options for share links, with additional DIY customization. +4. Improved - History module. The old history module has been deprecated — simply enter the value directly in the relevant field. +5. Adjusted - Knowledge base search module topK logic now uses MaxToken calculation, accommodating text chunks of varying lengths. +6. Adjusted - Authentication order to prioritize API keys, preventing cookies from overriding API key authentication. +7. Link fetching now supports multiple selectors. See [Web Site Sync Usage](/docs/introduction/guide/knowledge_base/websync/). +8. Fixed - Image upload authentication issue in share links. +9. Fixed - Mongo connection pool not being released. +10. Fixed - Dataset description (Intro) not updating. +11. Fixed - Markdown code block rendering issue. +12. Fixed - Root permission issue. +13. Optimized Dockerfile. diff --git a/document/content/docs/upgrading/4-8/465.en.mdx b/document/content/docs/upgrading/4-8/465.en.mdx new file mode 100644 index 0000000000..bd8e274ecb --- /dev/null +++ b/document/content/docs/upgrading/4-8/465.en.mdx @@ -0,0 +1,28 @@ +--- +title: V4.6.5 (Configuration Changes Required) +description: FastGPT V4.6.5 +--- + +## Configuration Changes + +Since OpenAI has begun deprecating function calls in favor of tool choice, FastGPT has updated its configuration and invocation methods accordingly. You'll need to make some changes to your configuration file: + +[View the latest configuration file](/docs/introduction/development/configuration/) + +1. The main change is renaming the `functionCall` field to `toolChoice` in your model configuration. Models with this set to `true` will use OpenAI's tools mode by default; models without it or with it set to `false` will use prompt-based generation. + +The question optimization model and content extraction model now share the same configuration. + +2. Add `"ReRankModels": []` to your configuration. + +## V4.6.5 New Features + +1. New - [Question Optimization node](/docs/introduction/guide/dashboard/workflow/coreferenceresolution/) +2. New - [Text Editor node](/docs/introduction/guide/dashboard/workflow/text_editor/) +3. New - [Classifier node](/docs/introduction/guide/dashboard/workflow/tfswitch//) +4. New - [Custom Feedback node](/docs/introduction/guide/dashboard/workflow/custom_feedback/) +5. New - The Content Extraction node now supports model selection and field enumerations. +6. Improved - DOCX parsing with table support (tables are converted to Markdown). +7. Improved - Advanced orchestration connection line interactions. +8. Improved - Fixed CPU-intensive computation caused by html2md that was blocking the thread. +9. Fixed - Prompt extraction descriptions in advanced orchestration. diff --git a/document/content/docs/upgrading/4-8/466.en.mdx b/document/content/docs/upgrading/4-8/466.en.mdx new file mode 100644 index 0000000000..9d402524b5 --- /dev/null +++ b/document/content/docs/upgrading/4-8/466.en.mdx @@ -0,0 +1,29 @@ +--- +title: V4.6.6 (Configuration Changes Required) +description: FastGPT V4.6.6 +--- + +## Configuration Changes + +To reduce code duplication, we've made some changes to the configuration file: [View the latest configuration file](/docs/introduction/development/configuration/) + +## Commercial Edition Changes + +1. Update the commercial edition image to version 4.6.6. +2. Move `SystemParams.pluginBaseUrl` from the old configuration file to an environment variable: + + PRO_URL=commercial edition image address (no longer needs to end with /api), for example: + PRO_URL=http://fastgpt-plugin.ns-hsss5d.svc.cluster.local:3000 + +3. The `FeConfig` section has been removed from the configuration file. You can now configure it directly through the commercial edition's web interface. All FastGPT parameters and models can be configured from the commercial edition dashboard — no need to modify `config.json` anymore. + +## V4.6.6 Release Notes + +1. Check out the [FastGPT 2024 RoadMap](https://github.com/labring/FastGPT?tab=readme-ov-file#-%E5%9C%A8%E7%BA%BF%E4%BD%BF%E7%94%A8). +2. New - HTTP node now supports a JSON editor for request headers. +3. New - [ReRank Model Deployment](/docs/introduction/development/custom-models/bge-rerank/) +4. New - Search modes: separated vector semantic search, full-text search, and reranking, with RRF (Reciprocal Rank Fusion) for merging results. +5. Improved - Question classifier prompts with ID-guided classification. Tested with Chinese commercial API models (Baidu, Alibaba, Zhipu, iFlytek) — all work correctly in Prompt mode. +6. UI improvements — the interface will be gradually updated with a new design going forward. +7. Code optimization: Icons extracted and auto-generated. +8. Fixed - Link-based datasets not saving selectors, causing syncs to run without them. diff --git a/document/content/docs/upgrading/4-8/467.en.mdx b/document/content/docs/upgrading/4-8/467.en.mdx new file mode 100644 index 0000000000..48782c7ca5 --- /dev/null +++ b/document/content/docs/upgrading/4-8/467.en.mdx @@ -0,0 +1,31 @@ +--- +title: V4.6.7 (Initialization Required) +description: FastGPT V4.6.7 +--- + +## 1. Run the Initialization API + +Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain). + +1. https://xxxxx/api/admin/initv467 + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv467' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +What the initialization does: + +1. Re-associates images with their datasets. +2. Sets null values in the PG table. + +## V4.6.7 Release Notes + +1. Redesigned knowledge base UI with a new import workflow. +2. Optimized knowledge base and chat data indexing. +3. Knowledge base OpenAPI — you can now [manage knowledge bases via API](/docs/openapi/dataset). +4. New - Input field variable hints. After typing `{`, you'll see available variable suggestions. Based on community feedback on advanced orchestration, we plan to improve variable handling in the February release, adding support for node-scoped local variables and more global variables. +5. Improved - Switching teams now saves your selection, so you'll automatically log into that team on your next visit. +6. Fixed - chatId conflicts when using the API for conversations. +7. Fixed - Potential window.onLoad conflicts when embedding via iframe. diff --git a/document/content/docs/upgrading/4-8/468.en.mdx b/document/content/docs/upgrading/4-8/468.en.mdx new file mode 100644 index 0000000000..efdad00bd5 --- /dev/null +++ b/document/content/docs/upgrading/4-8/468.en.mdx @@ -0,0 +1,94 @@ +--- +title: V4.6.8 (Initialization Required) +description: FastGPT V4.6.8 Release Notes +--- + +## Docker Deployment - Manually Update MongoDB + +1. Modify the mongo section in docker-compose.yml by adding the `command` and `entrypoint` fields: + +```yml +mongo: + image: mongo:5.0.18 + # image: registry.cn-hangzhou.aliyuncs.com/fastgpt/mongo:5.0.18 # Alibaba Cloud + container_name: mongo + ports: + - 27017:27017 + networks: + - fastgpt + command: mongod --keyFile /data/mongodb.key --replSet rs0 + environment: + # Make sure the password matches your previous configuration + - MONGO_INITDB_ROOT_USERNAME=username + - MONGO_INITDB_ROOT_PASSWORD=password + volumes: + - ./mongo/data:/data/db + entrypoint: + - bash + - -c + - | + openssl rand -base64 128 > /data/mongodb.key + chmod 400 /data/mongodb.key + chown 999:999 /data/mongodb.key + echo 'const isInited = rs.status().ok === 1 + if(!isInited){ + rs.initiate({ + _id: "rs0", + members: [ + { _id: 0, host: "mongo:27017" } + ] + }) + }' > /data/initReplicaSet.js + # Start MongoDB service + exec docker-entrypoint.sh "$@" & + + # Wait for MongoDB to start + until mongo -u myusername -p mypassword --authenticationDatabase admin --eval "print('waited for connection')" > /dev/null 2>&1; do + echo "Waiting for MongoDB to start..." + sleep 2 + done + + # Run the replica set initialization script + mongo -u myusername -p mypassword --authenticationDatabase admin /data/initReplicaSet.js + + # Wait for the MongoDB process started by docker-entrypoint.sh + wait $! +``` + +2. Restart MongoDB + +```bash +# Restart Mongo +docker-compose down +docker-compose up -d +``` + +## Sealos Deployment - No MongoDB Update Required + +## Update Configuration File + +Removed duplicate model configurations. All LLM models are now consolidated into a single property. [View the latest configuration file](/docs/introduction/development/configuration/) + +## Commercial Edition Initialization + +Commercial edition users need to run an initialization to format team information. + +Send 1 HTTP request (replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your commercial edition domain): + +```bash +curl --location --request POST 'https://{{host}}/api/init/v468' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will initialize the billing system. For internal use, you can increase the free storage quota. + +## V4.6.8 Release Notes + +1. New - Knowledge Base search merge module. +2. New - Redesigned HTTP module with more flexible parameter input. Supports automatic input/output data type conversion (e.g., JSON output is automatically converted to string type for use by other modules). Additional examples are available in the documentation. +3. Improved - Query completion. Query completion is now built into the Knowledge Base Search module, enabling both "reference resolution" and "query expansion" in a single pass. See [Knowledge Base Search Introduction](/docs/introduction/guide/dashboard/workflow/dataset_search/) for details. +4. Improved - LLM model configuration no longer distinguishes between chat, classification, and extraction models. Default parameters per model are now supported via `defaultConfig` to avoid parameter conflicts between different models. +5. Improved - Streaming response, inspired by `ChatNextWeb`'s streaming implementation for smoother output. This may also fix previously reported issues with garbled text and interruptions that resolved after refreshing. +6. Fixed - Voice input file upload failure. +7. Fixed - Chat box regeneration not working. diff --git a/document/content/docs/upgrading/4-8/469.en.mdx b/document/content/docs/upgrading/4-8/469.en.mdx new file mode 100644 index 0000000000..340c709579 --- /dev/null +++ b/document/content/docs/upgrading/4-8/469.en.mdx @@ -0,0 +1,45 @@ +--- +title: V4.6.9 (Includes Upgrade Script) +description: FastGPT V4.6.9 Release Notes +--- + +## Update Commercial Edition Environment Variables + +Add the OneAPI address and token: + +``` +OPENAI_BASE_URL=http://oneapi:3000/v1 +CHAT_API_KEY=sk-fastgpt +``` + +## Initialization Script + +From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv469' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +1. Resets the usage tracking table. +2. Runs stale data cleanup (removes invalid files, images, Knowledge Base collections, and vectors). + +## External API Updates + +1. Due to billing system changes, the [share link chat reporting endpoint](/docs/openapi/share/#5-编写对话结果上报接口可选) requires some adjustments. The `price` field has been replaced by `totalPoints`. The `inputToken` and `outputToken` fields are no longer provided — only a `token` field (total token count) is returned. + +## V4.6.9 Release Notes + +1. Commercial Edition - Knowledge Base now supports an "Enhanced Processing" training mode that generates additional index types. +2. New - Improved variable hints for the HTTP module. +3. New - HTTP module supports OpenAI single-endpoint import. +4. New - Global variables now support external variables, which can be passed via share link query parameters or the API `variables` parameter. +5. New - Content extraction module now supports default values. +6. Improved - Query completion now includes English language support. It can also be configured as a standalone module for reuse. +7. Improved - Rewrote the usage tracking system. +8. Improved - Token-based history filtering now keeps an even number of messages to prevent errors with certain models. +9. Improved - Share link SEO now displays the app name and avatar directly. +10. Fixed - Annotation feature. +11. Fixed - QA generation thread count error. +12. Fixed - Question classification connection type error. diff --git a/document/content/docs/upgrading/4-8/47.en.mdx b/document/content/docs/upgrading/4-8/47.en.mdx new file mode 100644 index 0000000000..e86f3f5327 --- /dev/null +++ b/document/content/docs/upgrading/4-8/47.en.mdx @@ -0,0 +1,66 @@ +--- +title: V4.7 (Initialization Required) +description: FastGPT V4.7 Release Notes +--- + +## 1. Update Configuration File + +Added Boolean values to control which models are available for different feature modules, and added model logos. [View the latest configuration file](/docs/introduction/development/configuration/) + +## 2. Initialization Script + +After upgrading the image, send 1 HTTP request from any terminal. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your domain. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv47' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +Script functions: + +1. Initializes the parentId for plugins. + +## 3. Upgrade ReRank Model + +V4.7 changed the ReRank model format to be compatible with Cohere's format, allowing direct use of Cohere's API. If you're using a local ReRank model, update the image to: `registry.cn-hangzhou.aliyuncs.com/fastgpt/bge-rerank-base:v0.1`. + +Cohere's reranking model doesn't perform as well with Chinese text compared to BGE. To integrate Cohere: + +1. Apply for a Cohere API key: https://dashboard.cohere.com/api-keys +2. Update the FastGPT configuration file: + +```json +{ + "reRankModels": [ + { + "model": "rerank-multilingual-v2.0", // The model name must match a Cohere model + "name": "Rerank", // Any display name + "requestUrl": "https://api.cohere.ai/v1/rerank", + "requestAuth": "Your Cohere API key" + } + ] +} +``` + +## V4.7 Release Notes + +1. New - Tool calling module that allows LLM models to dynamically select other modules or plugins based on user intent. +2. New - Classification and content extraction now support functionCall mode. Models that support functionCall but not toolCall can now be used. Set `functionCall` to `true` and `toolChoice` to `false` in the LLM model configuration. If `toolChoice` is true, tool mode will be used instead. +3. New - HTTP plugin for quickly generating plugins via OpenAPI. +4. New - ReRank model now compatible with [Cohere's format](https://docs.cohere.com/reference/rerank-1), enabling direct use of Cohere's rerank models. +5. New - Helm chart installation support. +6. Improved - Advanced workflow editor performance. +7. Improved - Extracted Flow controller to packages. +8. Improved - AI model selection. +9. Improved - Manual Knowledge Base input dialog. +10. Improved - Variable input dialog. +11. Improved - Docker deployment now auto-initializes replica sets. +12. Improved - Browser file reading now auto-detects encoding to reduce garbled text. +13. Fixed - Community edition rerank model selection not working. +14. Fixed - HTTP request body sending `undefined` when not in use (caused some GET requests to fail). +15. New - HTTP URL now supports variables. +16. Fixed - V4.6.9 extraction prompts prone to hallucination. +17. Fixed - PG HNSW index not actually taking effect. After this update, search speed is significantly improved (though there may be some precision loss — refer to the PgVector documentation for index tuning). Details: https://github.com/pgvector/pgvector?tab=readme-ov-file#troubleshooting +18. Fixed - Safari browser voice input issue. +19. Fixed - Custom split rules now accept regex special characters (previously caused frontend crashes). diff --git a/document/content/docs/upgrading/4-8/471.en.mdx b/document/content/docs/upgrading/4-8/471.en.mdx new file mode 100644 index 0000000000..197a695fe0 --- /dev/null +++ b/document/content/docs/upgrading/4-8/471.en.mdx @@ -0,0 +1,35 @@ +--- +title: V4.7.1 (Includes Upgrade Script) +description: FastGPT V4.7.1 Release Notes +--- + +## Initialization Script + +From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your FastGPT domain. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/clearInvalidData' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This request runs stale data cleanup (removes invalid files, images, Knowledge Base collections, and vectors). + +## Update Configuration File + +Added Laf environment configuration. [View the latest configuration file](/docs/introduction/development/configuration/) + +## V4.7.1 Release Notes + +1. New - Full voice input configuration. Supports toggling voice input on/off (including on share pages), auto-send after voice input, and auto voice playback after input (streaming). +2. New - PPTX and XLSX file reading. Note that all file reading now happens server-side, which consumes more server resources and prevents content preview during upload. +3. New - Laf cloud function integration. You can use cloud functions from your Laf account as HTTP modules. +4. New - Scheduled cleanup timer for stale data. Uses incremental cleanup (cleans data from the last N hours), so keep the service running continuously. For a full cleanup after extended downtime, use the `clearInvalidData` endpoint. +5. Commercial Edition - Admin panel system notification configuration. +6. Improved - Knowledge Base export now supports IP-based mode. +7. Changed - CSV import template no longer validates headers; automatically reads the first two columns. +8. Fixed - Tool calling module connection data type validation error. +9. Fixed - Custom index input data destructuring failure. +10. Fixed - ReRank model data format. +11. Fixed - Query completion history bug. +12. Fixed - Share page slow loading in certain edge cases (caused by database connections not being triggered during SSR). diff --git a/document/content/docs/upgrading/4-8/48.en.mdx b/document/content/docs/upgrading/4-8/48.en.mdx new file mode 100644 index 0000000000..36441d2051 --- /dev/null +++ b/document/content/docs/upgrading/4-8/48.en.mdx @@ -0,0 +1,51 @@ +--- +title: V4.8 +description: FastGPT V4.8 Release Notes +--- + +import { Alert } from '@/components/docs/Alert'; + +## New Workflow + +FastGPT Workflow V2 is here, with a cleaner and more streamlined workflow experience. + + +**Due to significant workflow changes, many parts need to be manually rebuilt. Please rebuild plugins first, then apps.** + +We recommend updating your workflows as soon as possible to avoid future compatibility issues as the platform continues to evolve. + + +A `version` field has been added to apps and plugins to distinguish between old and new workflows. After upgrading to V4.8, all saved and newly created workflows use the new version. Old workflows will show a reset prompt dialog. Workflows called via API or share links will continue to work until you save them again. + +## Commercial Edition Configuration Update + +Commercial edition users who have configured email verification codes need to update the admin panel: go to Admin Panel -> Project Settings -> Login Settings -> Email Login Settings -> update the **Email SMTP Server Address**. Previously only aliases were supported; now you can configure custom addresses. Here are some alias-to-address mappings: + +qq: smtp.qq.com +gmail: smtp.gmail.com + +## V4.8 Release Notes + +1. Refactored - Workflow engine. +2. New - If/ElseIf/Else conditional node. @newfish-cmyk (If/Else nodes from the preview version need to be deleted and recreated) +3. New - Variable update node for modifying workflow output variables or global variables at runtime. @newfish-cmyk +4. New - Workflow auto-save and version management. +5. New - Workflow Debug mode for testing individual nodes or stepping through the workflow. +6. New - Scheduled app execution for easy cron-like tasks. +7. New - Improved plugin custom input with rendered input components. +8. New - Share link pre-chat hook. https://github.com/labring/FastGPT/pull/1252 @gaord +9. Improved - Workflow connections now support 4-directional linking for easier loop construction. +10. Improved - Workflow context passing performance. +11. Improved - Ctrl+Enter and Alt+Enter line break cursor positioning. +12. Improved - Variable configuration storage in chat to prevent edits from affecting existing conversations. +13. Improved - Simple mode now auto-updates the debug panel after config changes without saving. +14. Improved - Worker process management; token calculation is now delegated to worker processes. +15. Improved - Tool calling now supports specifying field data types (string, boolean, number). https://github.com/labring/FastGPT/issues/1236 +16. Improved - Completions API size limit. https://github.com/labring/FastGPT/issues/1241 +17. Improved - Node API middleware and API-side code. @c121914yu +18. Improved - Chat history is now trimmed to an even number of messages to support models that require paired messages. Max length increased to 50 rounds. https://github.com/labring/FastGPT/issues/1384 +19. Improved - HTTP node now terminates the process on error. https://github.com/labring/FastGPT/issues/1290 +20. Fixed - Tool calling name cannot start with a number (random IDs occasionally generated numeric prefixes). @c121914yu +21. Fixed - Share link global variable query params being cached. @c121914yu +22. Fixed - Tool calling field compatibility. https://github.com/labring/FastGPT/issues/1253 +23. Fixed - HTTP module URL cursor issue. https://github.com/labring/FastGPT/issues/1334 @maquannene diff --git a/document/content/docs/upgrading/4-8/481.en.mdx b/document/content/docs/upgrading/4-8/481.en.mdx new file mode 100644 index 0000000000..0680c041cd --- /dev/null +++ b/document/content/docs/upgrading/4-8/481.en.mdx @@ -0,0 +1,34 @@ +--- +title: V4.8.1 (Includes Upgrade Script) +description: FastGPT V4.8.1 Release Notes +--- + +## Initialization Script + +From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your FastGPT domain. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv481' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +Due to previously inconsistent collection names, this initialization will reset table names. Before running, make sure the `dataset.trainings` table has no data. It's best to pause all active operations before initializing to avoid data conflicts. + +## Run Stale Data Cleanup + +From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your FastGPT domain. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/clearInvalidData' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +After initialization, you can run this command. The previous scheduled cleanup timer had some issues and missed certain data. This allows you to trigger a full cleanup manually. + +## V4.8.1 Release Notes + +If you're using the Chat API, note that a new `event: updateVariables` event has been added for updating variables. + +[View the full release notes](https://github.com/labring/FastGPT/releases/tag/v4.8.1) diff --git a/document/content/docs/upgrading/4-8/4810.en.mdx b/document/content/docs/upgrading/4-8/4810.en.mdx new file mode 100644 index 0000000000..5ec0b75193 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4810.en.mdx @@ -0,0 +1,100 @@ +--- +title: V4.8.10 (Includes Migration Script) +description: FastGPT V4.8.10 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your database + + +### 2. Commercial Edition — Update environment variables + +1. Add the sandbox environment variable to the `fastgpt-pro` image: `SANDBOX_URL=http://xxxxx:3000` +2. Add the following environment variables to both the `fastgpt-pro` and `fastgpt` images for better system log storage: + +``` +LOG_LEVEL=debug +STORE_LOG_LEVEL=warn +``` + +### 3. Update image tags + +- Update the FastGPT image tag to v4.8.10 +- Update the FastGPT commercial edition image tag to v4.8.10 +- Sandbox image update is optional + +## 4. Run initialization + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4810' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +1. Initializes publish record version markers +2. Initializes invoice records + +------- + +## V4.8.10 Release Notes + +For full details, see: [4.8.10 release](https://github.com/labring/FastGPT/releases/tag/v4.8.10) + +1. New - Template marketplace. +2. New - Workflow node drag-and-drop auto-alignment and snapping. +3. New - User selection node (not yet supported in Debug mode). +4. New - Added `uid` global variable to workflows. +5. New - Workflow undo and redo. +6. New - Workflow edit history for the current session, replacing auto-save. +7. New - Workflow versions support renaming. +8. New - The "App Call" node in workflows is deprecated and migrated to a standalone node that works the same way as plugins, with support for passing global variables and user-uploaded files. +9. New - Plugins now support usage instructions configuration. +10. New - Plugin custom inputs support radio buttons. +11. New - HTTP node supports `text/plain` mode. +12. New - HTTP node supports timeout configuration, additional Body types, and a new variable selection mode for params and headers. +13. New - Workflow export/import now supports JSON files directly for easier sharing. +14. New - Verification code security check. +15. Commercial - Lark bot integration. +16. Commercial - WeChat Official Account integration. +17. Commercial - Self-service invoice requests. +18. Commercial - SSO customization. +19. Improved - Workflow loop validation to prevent skip-loop idle spinning. Also supports fully concurrent branch execution. +20. Improved - Workflow nested execution to prevent potential parameter pollution. +21. Improved - Added data type constraints to some global variables. +22. Improved - Node selection to prevent path loading errors when switching tabs. +23. Improved - Updated React Markdown component with Base64 image support. +24. Improved - Chat dialog performance. +25. Improved - Radio buttons auto-scroll to the selected position when opened. +26. Improved - Disabling a Knowledge Base collection directory now recursively disables all children. +27. Improved - SSE response code. +28. Improved - Improved copy functionality when SSL certificate is not available. +29. Improved - Knowledge Base list UI. +30. Improved - Knowledge Base detail page UI. +31. Improved - Support running without network configuration. +32. Improved - Updated .env.template MongoDB documentation for better clarity. +33. Improved - New payment mode. +34. Improved - Default user avatars. +35. Fixed - Prompt mode tool calls including `0:` prefix markers in non-stream mode. +36. Fixed - Chat log authentication: users who are only app administrators could not view chat log details. +37. Fixed - Unable to export Knowledge Base when using Milvus deployment. +38. Fixed - Creating an app copy failed to copy system configuration. +39. Fixed - Image recognition mode regex for auto-parsing image URLs was not strict enough. +40. Fixed - Content extraction data types not matching output data types. +41. Fixed - Workflow run time statistics were incorrect. +42. Fixed - Tool calls could produce `undefined` in stream mode. +43. Fixed - Reranker typo. +44. Fixed - Home host typo. +45. Fixed - i18n display. +46. Fixed - Global variable keys could be defined with duplicates. +47. Fixed - Global variables not persisting in Debug mode. +48. Fixed - Global variables not persisting via API. +49. Fixed - OpenAPI `detail=false` mode should not return tool call results, only text (resolves CoW compatibility issue). +50. Fixed - Knowledge Base tags loading repeatedly. +51. Fixed - Custom separators not taking effect when re-fetching web links. +52. Fixed - Plugin runtime passing extra global variables, potentially polluting plugin-internal variables. +53. Docs - QA docs. +54. Docs - Updated feishu.md. +55. Docs - Updated baseURL. diff --git a/document/content/docs/upgrading/4-8/4811.en.mdx b/document/content/docs/upgrading/4-8/4811.en.mdx new file mode 100644 index 0000000000..6ac479df41 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4811.en.mdx @@ -0,0 +1,135 @@ +--- +title: V4.8.11 (Commercial Edition Initialization) +description: FastGPT V4.8.11 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your data + +### 2. Update configuration file + +To add the OpenAI o1 model, add the following configuration: + +```json +{ + "model": "o1-mini", + "name": "o1-mini", + "avatar": "/imgs/model/openai.svg", + "maxContext": 125000, + "maxResponse": 65000, + "quoteMaxToken": 120000, + "maxTemperature": 1.2, + "charsPointsPrice": 0, + "censor": false, + "vision": false, + "datasetProcess": true, + "usedInClassify": true, + "usedInExtractFields": true, + "usedInToolCall": true, + "toolChoice": false, + "functionCall": false, + "customCQPrompt": "", + "customExtractPrompt": "", + "defaultSystemChatPrompt": "", + "defaultConfig": { + "temperature": 1 + } +}, +{ + "model": "o1-preview", + "name": "o1-preview", + "avatar": "/imgs/model/openai.svg", + "maxContext": 125000, + "maxResponse": 32000, + "quoteMaxToken": 120000, + "maxTemperature": 1.2, + "charsPointsPrice": 0, + "censor": false, + "vision": false, + "datasetProcess": true, + "usedInClassify": true, + "usedInExtractFields": true, + "usedInToolCall": true, + "toolChoice": false, + "functionCall": false, + "customCQPrompt": "", + "customExtractPrompt": "", + "defaultSystemChatPrompt": "", + "defaultConfig": { + "temperature": 1 + } +} +``` + +------- + +### 3. Update image tags and restart + +- Update the FastGPT image tag to v4.8.11-fix +- Update the FastGPT commercial edition image tag to v4.8.11 +- Update the FastGPT Sandbox image tag to v4.8.11 + +### 4. Commercial Edition initialization + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/init/4811' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This initializes team member groups. + +## V4.8.11 Release Notes + +1. New - Form input node, allowing users to enter information during workflow execution. +2. New - Loop execution node that accepts an array for batch processing, currently supporting up to 50 items in serial execution. +3. New - Nodes can now be collapsed. +4. New - Simple Mode supports a new history mode that records local change history. +5. New - Chat history now uses scroll-based loading instead of only loading 30 messages. +6. New - Workflow adds a trackpad-priority mode, toggled via the button in the bottom-right corner. +7. New - Sandbox adds a string-to-Base64 global method (global variable `strToBase64`). +8. New - Support for OpenAI o1 models. Requires adding `defaultConfig` to the model configuration to override `temperature`, `max_tokens`, and `stream` settings, as o1 does not support stream mode. +9. New - AI chat node Knowledge Base references now support configuring `role=system` and `role=user`. Nodes with custom prompts already configured will keep `user` mode; all others will switch to `system` mode. +10. New - Plugins support uploading system files. +11. New - Plugin outputs support designating specific fields as tool responses. +12. New - When nesting child apps in workflows, you can now set "non-stream mode". Simple Mode can also select workflows as plugins. Simple Mode always forces non-stream mode when calling child apps. +13. New - In debug mode, child app calls return detailed execution data. +14. New - Logs for nested child app calls are now preserved in all modes. +15. New - Chat logs display team members. +16. New - Commercial edition supports configuring AI-generated copy prompts in the admin panel. +17. New - Jest unit testing framework. +18. New - Tool call parameter node for fully custom parameter declarations with tool calls. +19. New - BI chart plugin. +20. New - Surya OCR recognition module example. +21. New - Right-click to add comments in workflows. +22. Commercial - Team member groups. +23. Improved - Workflow nesting limited to 20 levels to prevent infinite loops from improper configurations. +24. Improved - Workflow handler performance. +25. Improved - Workflow shortcuts no longer trigger copy and undo during debug testing. +26. Improved - Removed extra "#" from names when copying workflow nodes. +27. Improved - Stream output continues even after switching browser tabs. +28. Improved - Enhanced external file Knowledge Base APIs. +29. Improved - Updated config.json path. +30. Improved - Properly handle hyperlinks starting with `//`. +31. Improved - Workflow Textarea scrolls normally instead of zooming. +32. Improved - Trimmed leading/trailing spaces from some input fields. +33. Improved - Returning to workflow now navigates to the last remembered tab. +34. Improved - Workflow canvas prevents trackpad browser zoom. +35. Improved - Some workflow nodes auto-select user question as the initial value. +36. Improved - Prompt Editor supports dynamic height expansion. +37. Improved - Auto-complete tool descriptions. +38. Improved - Updated configuration.md documentation. +39. Improved - iOS Safari voice input accuracy. +40. Fixed - Knowledge Base selection permission issue. +41. Fixed - Starting a conversation with an empty chatId caused errors when the first message included user selections. +42. Fixed - `createDataset` API not assigning `intro`. +43. Fixed - Chat dialog rendering performance issue. +44. Fixed - Rerank documentation URL. +45. Fixed - In stream mode with toolChoice, the `function` and `type` fields of toolCall could be null. +46. Fixed - Site sync custom separators not syncing. +47. Fixed - Tool call history storage issue. +48. Fixed - Chat page could enter an infinite redirect loop. +49. Fixed - Global variables not persisting across tool calls. diff --git a/document/content/docs/upgrading/4-8/4812.en.mdx b/document/content/docs/upgrading/4-8/4812.en.mdx new file mode 100644 index 0000000000..0b759da487 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4812.en.mdx @@ -0,0 +1,64 @@ +--- +title: V4.8.12 (Includes Migration Script) +description: FastGPT V4.8.12 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your data + +### 2. Update images + +- Update the FastGPT image tag to v4.8.12-fix +- Update the FastGPT admin image tag to v4.8.12 (fastgpt-pro image) +- Sandbox image update is optional + + +### 3. Run initialization (Commercial Edition) + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/init/4812' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This initializes member group data for apps and Knowledge Bases. + +### 4. Rebuild Milvus data + +Due to JavaScript int64 precision loss, users who previously deployed with Milvus or Zilliz and experienced data precision loss need to rebuild their Milvus data. (Check the `dataset_datas` collection — if `dataId` values in the `indexes` field have trailing precision loss, a rebuild is needed.) PG users do not need to take action. + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/resetMilvus' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +## Release Notes + +1. New - Global variables support number type, with configurable default values and input field parameters. +2. New - Plugin custom inputs (text fields, number fields, select boxes, toggles) all support being referenced as variables by default. +3. New - `FE_DOMAIN` environment variable. When configured, uploaded files/images get a complete URL with the domain suffix (resolves the issue where models sometimes fabricate image domains for docx file image links). +4. New - Tool calls support using the interaction node. +5. New - Debug mode supports inputting global variables. +6. New - Chat OpenAPI documentation. +7. New - Wiki search plugin. +8. New - Google search plugin. +9. New - Database connection and operation plugin. +10. New - Cookie privacy policy prompt. +11. New - HTTP node supports JSONPath expressions. +12. New - Apps and Knowledge Bases support member group permission configuration. +13. Improved - Loop node supports selecting variables from external nodes. +14. Improved - Docx file reading: optimized HTML-to-Markdown conversion for better speed and significantly reduced memory consumption. +15. Fixed - File extension detection now ignores query string parameters. +16. Fixed - Empty AI responses causing LLM history record merging. +17. Fixed - User interaction node not blocking the workflow. +18. Fixed - Creating a new app sometimes causing a null pointer error. +19. Fixed - Incorrect execution when multiple loop nodes are present. +20. Fixed - Variable modifications inside loop nodes not propagating. +21. Fixed - In non-stream mode, nested child apps/plugins unable to receive child app responses. +22. Fixed - Data chunking strategy now chunks each Markdown section independently. diff --git a/document/content/docs/upgrading/4-8/4813.en.mdx b/document/content/docs/upgrading/4-8/4813.en.mdx new file mode 100644 index 0000000000..27b773c6b5 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4813.en.mdx @@ -0,0 +1,47 @@ +--- +title: V4.8.13 +description: FastGPT V4.8.13 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your data + +### 2. Update images + +- Update the FastGPT image tag to v4.8.13-fix +- Update the FastGPT commercial edition image tag to v4.8.13-fix (fastgpt-pro image) +- Sandbox image update is optional + +### 3. Add environment variables + +- Add the environment variable `FE_DOMAIN=http://xx.com` to both the fastgpt and fastgpt-pro images. Set the value to the FastGPT frontend access URL (do not include a trailing `/`). This automatically prepends the domain to relative file paths. + +### 4. Update file upload workflow configuration + +While the old file upload workflow configuration is still supported, backward compatibility will be removed within the next two versions. Please update your workflows to use the new file upload logic as soon as possible. In particular, file passing in nested apps will no longer be automatic — you must explicitly specify which files to pass. For details, see: [File Upload Changes](/docs/introduction/guide/course/fileinput/#4813%E7%89%88%E6%9C%AC%E8%B5%B7%E5%85%B3%E4%BA%8E%E6%96%87%E4%BB%B6%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%9B%B4%E6%96%B0) + +## Release Notes + +1. New - Array variable selection supports multi-select. You can select multiple arrays or their corresponding single data types, which are automatically merged in selection order. +2. New - Revamped file upload approach. AI chat and tool call nodes directly accept file URLs and enforce prompt injection without relying on model-driven decisions. Plugin custom variables support file upload types, replacing global files. +3. New - Chat history now displays timestamps. +4. New - Workflow validation errors now navigate to the error node. +5. New - Loop node adds an index value. +6. New - Added translations for some chat error messages. +7. New - Chat input box supports drag-and-drop file upload. +8. New - Chat logs now show the specific share link/API name as the source. +9. New - Share links support configuring whether to display real-time execution status. +10. Improved - Merged multiple system prompts into one to support models that don't accept multiple system prompts. +11. Improved - Better error messages for Knowledge Base file uploads. +12. Improved - Full-text search query optimization, eliminating one subquery. +13. Improved - Replaced `findLast` with `[...array].reverse().find` for older browser compatibility. +14. Improved - Markdown component auto-spacing to avoid splitting Chinese characters in URLs. +15. Improved - Workflow context splitting for better performance. +16. Improved - Text-to-speech: browsers that don't support `mediaSource` can now wait for full audio generation before playback. +17. Improved - Chat starter CSV reading with automatic encoding detection. +18. Improved - Fixed potential garbled text when importing chat starters via CSV. +19. Fixed - Dockerfile pnpm install now supports proxy. +20. Fixed - Dockerfile pnpm install now supports proxy. +21. Fixed - BI chart generation unable to write files. Also improved parsing to support numeric array types. +22. Fixed - Share link title displaying incorrectly on first load. diff --git a/document/content/docs/upgrading/4-8/4814.en.mdx b/document/content/docs/upgrading/4-8/4814.en.mdx new file mode 100644 index 0000000000..2b14e2c6f6 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4814.en.mdx @@ -0,0 +1,50 @@ +--- +title: V4.8.14 +description: FastGPT V4.8.14 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your data + +### 2. Update images + +- Update the FastGPT image tag to v4.8.14-fix +- Update the FastGPT commercial edition image tag to v4.8.14 (fastgpt-pro image) +- Sandbox image update is optional + +For Milvus users: use the v4.8.14-milvus-fix image. + +## New Feature Preview + +### Auto-trigger Workflow + +You can configure a workflow to automatically trigger once when a user loads a conversation. This is useful for CRM systems where you want to proactively guide users without waiting for them to initiate. + +| | | +| --- | --- | +| ![alt text](/imgs/image-8.png) | ![alt text](/imgs/image-9.png) | + + +## Full Release Notes + +1. New - Workflows support auto-triggering a conversation round when entering the chat or clicking "Start conversation". +2. New - Rewritten chatContext. Chat testing now generates logs, and conversations persist after page refresh. +3. New - Share links support configuring whether to allow viewing original source text. +4. New - New doc2x plugin. +5. New - Traditional Chinese language support. +6. New - Share links and chat API support passing a custom uid. +7. Commercial - Microsoft OAuth login. +8. Improved - Workflow UI details. +9. Improved - App edit history now uses diff-based storage to prevent browser overflow. +10. Improved - Code entry point adds a register entry, no longer requiring the first visit to execute. +11. Improved - Workflow validation with additional missing value checks. +12. Improved - Added maximum retry limit for Knowledge Base training. +13. Improved - Image path issues and diagram tasks. +14. Improved - Milvus description. +15. Fixed - Chunking strategy was dropping level-4 headings. Also added level-5 heading support. +16. Fixed - MongoDB Knowledge Base collection unique index. +17. Fixed - Deselecting Knowledge Base references could cause errors. +18. Fixed - Converting Simple Mode to workflow was not using the latest edit history. +19. Fixed - Form input description text not displaying. +20. Fixed - API unable to use Base64 images. diff --git a/document/content/docs/upgrading/4-8/4815.en.mdx b/document/content/docs/upgrading/4-8/4815.en.mdx new file mode 100644 index 0000000000..30f276265c --- /dev/null +++ b/document/content/docs/upgrading/4-8/4815.en.mdx @@ -0,0 +1,70 @@ +--- +title: V4.8.15 (Includes Migration Script) +description: FastGPT V4.8.15 Release Notes +--- + +## New Feature Preview + +### API Knowledge Base + +| | | +| ------------------------------- | ------------------------------- | +| ![alt text](/imgs/image-20.png) | ![alt text](/imgs/image-21.png) | + +### HTML Rendering + +| Source Mode | Preview Mode | Fullscreen Mode | +| ------------------------------- | ------------------------------- | ------------------------------- | +| ![alt text](/imgs/image-22.png) | ![alt text](/imgs/image-23.png) | ![alt text](/imgs/image-24.png) | + +## Upgrade Guide + +- Update the fastgpt image tag to v4.8.15-fix3 +- Update the fastgpt-pro commercial edition image tag to v4.8.15 +- Sandbox image update is optional + +## Run Migration Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4815' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This resets the scheduled execution fields for apps, removing null values to reduce index size. + +--- + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/init/refreshFreeUser' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This recalculates free-tier user durations. A previous version upgrade did not recalculate time properly, which caused incorrect notifications. + +## Full Release Notes + +1. New - API Knowledge Base. See [API Knowledge Base Introduction](/docs/introduction/guide/knowledge_base/api_dataset/). The external file library will be deprecated. +2. New - Toolbox page displaying all available system resources. The commercial edition admin panel now offers easier configuration of system plugins and custom categories. +3. New - HTML code in Markdown is now rendered separately. You can choose preview mode, which blocks all scripts and only displays content. +4. New - Custom system-level file parsing service. See [Integrating Marker PDF Document Parsing](/docs/introduction/development/custom-models/marker/). +5. New - Collections can be reconfigured directly without deleting and re-importing. +6. New - Commercial edition admin panel supports configuring sidebar navigation links. +7. Improved - Base64 image truncation detection. +8. Improved - i18n cookie detection. +9. Improved - Markdown text splitting now supports heading-only sections with no content. +10. Improved - String variable substitution: unassigned variables now resolve to `undefined` instead of preserving the raw ID string. +11. Improved - Global variable default values now take effect in API calls, and custom variables support default values. +12. Improved - Added JSON parsing for HTTP Body with regex conversion of `undefined` to `null`, reducing Body parsing errors. +13. Improved - Scheduled execution now includes run logs and retries to reduce error rates. +14. Fixed - Share link like/upvote authentication issue. +15. Fixed - Switching to an auto-execute app on the chat page could incorrectly trigger non-auto-execute apps. +16. Fixed - Audio playback authentication issue. +17. Fixed - Plugin app Knowledge Base reference limit was always capped at 3000. +18. Fixed - Workflow edit history storage limit. Removed local storage and added forced auto-save on abnormal exit. +19. Fixed - Workflow special variable substitution issue (strings starting with `$` could not be replaced). diff --git a/document/content/docs/upgrading/4-8/4816.en.mdx b/document/content/docs/upgrading/4-8/4816.en.mdx new file mode 100644 index 0000000000..d5483b94a4 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4816.en.mdx @@ -0,0 +1,67 @@ +--- +title: V4.8.16 (Configuration File Update) +description: FastGPT V4.8.16 Release Notes +--- + +## Upgrade Guide + +### 1. Update images: + +- Update the fastgpt image tag to v4.8.16 +- Update the fastgpt-pro commercial edition image tag to v4.8.16 +- Update the Sandbox image tag to v4.8.16 + +### 2. Update configuration file + +Refer to the latest [configuration file documentation](/docs/introduction/development/configuration/) and update your `config.json` or admin model configuration. Add the `provider` field to LLMModel and VectorModel for model categorization. For example: + +```json +{ + "provider": "OpenAI", // This is new + "model": "gpt-4o", + "name": "gpt-4o", + "maxContext": 125000, + "maxResponse": 4000, + "quoteMaxToken": 120000, + "maxTemperature": 1.2, + "charsPointsPrice": 0, + "censor": false, + "vision": true, + "datasetProcess": true, + "usedInClassify": true, + "usedInExtractFields": true, + "usedInToolCall": true, + "usedInQueryExtension": true, + "toolChoice": true, + "functionCall": false, + "customCQPrompt": "", + "customExtractPrompt": "", + "defaultSystemChatPrompt": "", + "defaultConfig": {}, + "fieldMap": {} +} +``` + +## Full Release Notes + +1. New - SearXNG search plugin. [View tutorial](/docs/introduction/guide/plugins/searxng_plugin_guide/) +2. New - Commercial edition supports scheduled sync for API Knowledge Bases and link collections. +3. New - "Suggested questions" supports model selection and custom prompts. +4. New - DingTalk and WeCom bot webhook plugins. +5. New - Commercial edition supports DingTalk SSO login configuration. [View tutorial](/docs/introduction/guide/admin/sso#钉钉) +6. New - Commercial edition supports Lark and Yuque Knowledge Base import. [View tutorial](/docs/introduction/guide/knowledge_base/lark_dataset/) +7. New - Sandbox adds `createHmac` encryption global method. +8. New - Right-click in workflow supports "Collapse all". +9. Improved - Model selector. +10. Improved - SSR rendering now pre-detects mobile vs. desktop to reduce page jitter. +11. Improved - Workflow/Simple Mode variable initialization code. Removed listener-based initialization to prevent failures from inconsistent render order. +12. Improved - Workflow now performs type conversion when receiving mismatched data types, preventing `undefined`. +13. Fixed - Unable to auto-switch default language. Share links now force a default language switch on load. +14. Fixed - Array selector auto-compatibility with pre-4.8.13 data. +15. Fixed - Site sync Knowledge Base not using the selector for link syncing. +16. Fixed - Converting Simple Mode to workflow did not convert system configuration items. +17. Fixed - Plugin standalone execution not applying initial variable values. +18. Fixed - Workflow modal components sometimes causing page offset after closing. +19. Fixed - Plugin debug logs not saving plugin input parameters. +20. Fixed - Some template marketplace templates. +21. Fixed - Incorrect image file URL when NEXT_PUBLIC_BASE_URL is set. diff --git a/document/content/docs/upgrading/4-8/4817.en.mdx b/document/content/docs/upgrading/4-8/4817.en.mdx new file mode 100644 index 0000000000..d043b3d9a7 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4817.en.mdx @@ -0,0 +1,48 @@ +--- +title: V4.8.17 (Includes Migration Script) +description: FastGPT V4.8.17 Release Notes +--- + +## Upgrade Guide + +### 1. Update images: + +- Update the fastgpt image tag to v4.8.17-fix-title +- Update the fastgpt-pro commercial edition image tag to v4.8.17 +- Sandbox image update is not required + + +### 2. Run migration script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4817' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This migrates user-bound OpenAI accounts to the team level. + + +## Completions API response changes + +The `/api/v1/chat/completions` endpoint response has been updated. Nodes that use models (chat nodes, tool nodes, etc.) will no longer return a `tokens` field. Instead, they return `inputTokens` and `outputTokens` fields representing the input and output token counts respectively. + +## Full Release Notes + +1. New - Simple Mode tool calls support array-type plugins. +2. New - Workflow adds auto-save on abnormal exit to prevent workflow loss. +3. New - LLM model parameters support disabling `max_tokens` and `temperature`. +4. New - Commercial edition supports configuring the template marketplace in the admin panel. +5. New - Commercial edition supports configuring custom workflow variables in the admin panel for business system authentication integration. +6. New - Search test API supports query optimization. +7. New - Input tokens and output tokens are now tracked and displayed separately in workflows. Also fixed billing not recording output tokens for some requests. +8. Improved - Markdown size check: content exceeding 200K characters no longer uses the Markdown component to prevent crashes. +9. Improved - Knowledge Base search parameters: sliders now support input mode for more precise control. +10. Improved - Available models display UI. +11. Improved - MongoDB queries with added virtual fields. +12. Fixed - File response API missing `Content-Length` header, causing Alibaba vision models to fail image recognition when uploading files from different origins. +13. Fixed - Removed hidden line breaks from both ends of condition node strings to prevent condition evaluation failures. +14. Fixed - Variable update node: non-string data types could not be auto-converted when manually entering update content. +15. Fixed - Doubao models unable to make tool calls. diff --git a/document/content/docs/upgrading/4-8/4818.en.mdx b/document/content/docs/upgrading/4-8/4818.en.mdx new file mode 100644 index 0000000000..73e7a63fc9 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4818.en.mdx @@ -0,0 +1,43 @@ +--- +title: V4.8.18 (Includes Migration Script) +description: FastGPT V4.8.18 Release Notes +--- + +## Upgrade Guide + +### 1. Update images: + +- Update the fastgpt image tag to v4.8.18-fix +- Update the fastgpt-pro commercial edition image tag to v4.8.18-fix +- Sandbox image update is not required + +### 2. Run migration script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4818' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This migrates the full-text search table. The migration takes a while — full-text search will be unavailable during the process. The log will print the amount of data already migrated. + + +## Full Release Notes + +1. New - Support creating apps directly via JSON configuration. +2. New - Support quickly creating HTTP plugins via CURL scripts. +3. New - Commercial edition supports department-based permission structure. +4. New - Support configuring custom CORS security policies (defaults to fully open). +5. New - Added model troubleshooting documentation for private deployments. +6. Improved - HTTP Body special handling to resolve parsing issues with newlines in string variables. +7. Improved - Share links generate random user avatars. +8. Improved - Image upload security validation. Added unique avatar image storage to prevent cumulative storage. +9. Improved - Separated MongoDB full-text index table. +10. Improved - Merged Knowledge Base search queries to reduce database calls. +11. Improved - File encoding detection to reduce CSV file garbled text. +12. Improved - Asynchronous file content reading to reduce process blocking. +13. Improved - File viewer: HTML files are now downloaded directly instead of being viewable online. +14. Fixed - HTML file upload: Base64 images not auto-converting to image URLs. +15. Fixed - Plugin billing errors. diff --git a/document/content/docs/upgrading/4-8/4819.en.mdx b/document/content/docs/upgrading/4-8/4819.en.mdx new file mode 100644 index 0000000000..ca628a29d1 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4819.en.mdx @@ -0,0 +1,42 @@ +--- +title: V4.8.19 (Includes Migration Script) +description: FastGPT V4.8.19 Release Notes +--- + +## Upgrade Guide + +### 1. Update images: + +- Update the fastgpt image tag to v4.8.19-beta +- Update the fastgpt-pro commercial edition image tag to v4.8.19-beta +- Sandbox image update is not required + +### 2. Run migration script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4819' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This migrates user avatars from the user table to the member table. + +## Full Release Notes + +1. New - Workflow Knowledge Base search supports filtering by Knowledge Base permissions. +2. New - Lark/Yuque Knowledge Base view original source. +3. New - Flow wait plugin that pauses execution for n milliseconds before continuing. +4. New - Lark bot integration supports configuring a private Lark server URL. +5. Improved - Member list pagination loading. +6. Improved - Unified pagination loading code. +7. Improved - Chat page loading now supports configuring whether it's a standalone page. +8. Improved - Member avatars migrated to the member table. +9. Fixed - Yuque file library import: nested file contents could not be expanded. +10. Fixed - Workflow editor: LLM parameters could not be disabled. +11. Fixed - Workflow editor: code execution node template restoration issue. +12. Fixed - HTTP interface object string parsing compatibility. +13. Fixed - API file upload (localFile) endpoint: image expiration flag not being cleared. +14. Fixed - Workflow import: number input types could not be overridden. +15. Fixed - Some model provider logos not displaying correctly. diff --git a/document/content/docs/upgrading/4-8/482.en.mdx b/document/content/docs/upgrading/4-8/482.en.mdx new file mode 100644 index 0000000000..1f5f4de5e8 --- /dev/null +++ b/document/content/docs/upgrading/4-8/482.en.mdx @@ -0,0 +1,30 @@ +--- +title: V4.8.2 +description: FastGPT V4.8.2 Release Notes +--- + +## Sealos Upgrade Instructions + +1. Create a new app in App Management with the image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sandbox:v4.8.1 +2. No external access URL is needed. Set the port to 3000. +3. After deployment, copy the app's internal network address. +4. Click "Update" on FastGPT, modify the environment variables, and add the following: + +``` +SANDBOX_URL=internal-network-address +``` + +## Docker Deployment + +You can pull the latest [docker-compose.yml](https://github.com/labring/FastGPT/blob/main/deploy/docker/docker-compose.yml) file for reference. + +1. Add a new `sandbox` container. +2. Add the `SANDBOX_URL` environment variable to the fastgpt and fastgpt-pro (commercial edition) containers. +3. It's recommended not to expose the sandbox to the public network, as it has no credential verification. + +## V4.8.2 Release Notes + +1. New - JavaScript code execution node (with improved type hints; more enhancements coming). +2. New - Content extraction node now supports data type selection. +3. Fixed - Newly added site sync not working. +4. Fixed - Scheduled tasks unable to accept input content. diff --git a/document/content/docs/upgrading/4-8/4820.en.mdx b/document/content/docs/upgrading/4-8/4820.en.mdx new file mode 100644 index 0000000000..420409808c --- /dev/null +++ b/document/content/docs/upgrading/4-8/4820.en.mdx @@ -0,0 +1,46 @@ +--- +title: V4.8.20 (Includes Migration Script) +description: FastGPT V4.8.20 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your database + +### 2. Update environment variables + +If you are an early adopter who configured `ONEAPI_URL`, you need to change it to `OPENAI_BASE_URL`. + +### 3. Update images: + +- Update the fastgpt image tag to v4.8.20-fix2 +- Update the fastgpt-pro commercial edition image tag to v4.8.20-fix2 +- Sandbox image update is not required + +### 4. Run migration script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4820' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +The script automatically loads models from the old configuration file into the new model configuration. + +## Full Release Notes + +1. New - Visual model parameter configuration, replacing the old config file approach. Over 100 model presets included, with one-click testing for all model types. (Full in-page channel configuration is planned for the next version.) [View model configuration guide](/docs/introduction/development/modelconfig/intro/) +2. New - DeepSeek Reasoner model supports outputting the thinking process. +3. New - Usage record export and dashboard. +4. New - Markdown syntax extension supporting audio and video (via `audio` and `video` code blocks). +5. New - Adjusted `max_tokens` calculation logic. `max_tokens` is now prioritized at the configured value; if it exceeds the maximum context, history is reduced instead. For example, requesting 8000 `max_tokens` reduces the context length by 8000. +6. Improved - Query optimization now includes context filtering to prevent exceeding context limits. +7. Improved - Page component extraction to reduce page component routing. +8. Improved - Full-text search is now case-insensitive. +9. Improved - QA generation and enhanced indexing switched to streaming output to prevent timeouts with some models. +10. Improved - Automatically adds `null` to empty assistant `content`, and merges consecutive text assistant messages to prevent errors from some models. +11. Improved - Adjusted image host: domain is no longer appended during upload but before sending a conversation, preventing broken images after domain changes. +12. Fixed - Member list not triggering bottom-loading in some scenarios. +13. Fixed - Workflow recursive execution failing under certain conditions. diff --git a/document/content/docs/upgrading/4-8/4821.en.mdx b/document/content/docs/upgrading/4-8/4821.en.mdx new file mode 100644 index 0000000000..05e228fdcd --- /dev/null +++ b/document/content/docs/upgrading/4-8/4821.en.mdx @@ -0,0 +1,35 @@ +--- +title: V4.8.21 +description: FastGPT V4.8.21 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your database + +### 2. Update images: + +- Update the fastgpt image tag to v4.8.21-fix +- Update the fastgpt-pro commercial edition image tag to v4.8.21-fix +- Sandbox image update is not required + +## Full Release Notes + +1. New - Deprecated/deleted plugin indicators. +2. New - Chat logs with source categorization, title search, and export. +3. New - Global variables support drag-and-drop reordering. +4. New - LLM models support `top_p`, `response_format`, and `json_schema` parameters. +5. New - Doubao 1.5 model preset. Alibaba Embedding v3 preset. +6. New - Vector models support normalization configuration to accommodate unnormalized vector models such as Doubao embedding models. +6. New - AI chat node supports outputting thinking process results, which can be referenced by other nodes. +7. Improved - Embedded chat widget with window position adaptation. +8. Improved - Better error messages when models are not configured. +9. Improved - Support for non-stream mode thinking output. +10. Improved - Added null pointer protection when TTS voice is not configured. +11. Improved - Markdown link parsing/splitting rules switched to strict matching mode, sacrificing compatibility for fewer false positives. +12. Improved - Reduced data fetching scope for unauthenticated users to improve system privacy. +13. Fixed - Simple Mode: switching to a non-vision model now correctly disables image recognition. +14. Fixed - o1/o3 models: field mapping not taking effect during testing, causing errors. +15. Fixed - WeChat Official Account chat null pointer exception. +16. Fixed - Multiple audio/video files displaying incorrectly. +17. Fixed - Share link authentication error causing infinite loop. diff --git a/document/content/docs/upgrading/4-8/4822.en.mdx b/document/content/docs/upgrading/4-8/4822.en.mdx new file mode 100644 index 0000000000..4868283fb6 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4822.en.mdx @@ -0,0 +1,57 @@ +--- +title: V4.8.22 (Includes Migration Script) +description: FastGPT V4.8.22 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your database + +### 2. Update images: + +- Update the fastgpt image tag to v4.8.22 +- Update the fastgpt-pro commercial edition image tag to v4.8.22 +- Sandbox image update is not required + +### 3. Run migration script + +Only required for commercial edition users providing SaaS services. + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4822' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This migrates contact information to the corresponding user table. + +## New Features + +1. AI chat node parses `` tag content as chain-of-thought, enabling thinking process output for various models. You need to manually enable model thinking output. +2. Chat API optimization: conversation logs are now saved regardless of whether a `chatId` is provided. If no `chatId` is passed, a random one is generated for storage. +3. PPIO model provider. + +## Improvements + +1. Better prompts when models are not configured, reducing conflicting messages. +2. Usage record code improvements. +3. Content extraction node: long field descriptions now wrap. Output names now use `key` instead of `description`. +4. Team management interaction improvements. +5. Chat API non-stream responses now include error fields. + +## Bug Fixes + +1. Thinking content not counted toward output tokens. +2. Thinking chain stream output sometimes out of order with main content. +3. API workflow calls: images that don't support HEAD detection were being filtered out. Added error detection to prevent incorrect filtering. +4. Some template marketplace templates had errors. +5. Guest window unable to correctly detect whether language recognition is enabled. +6. Chat log export not compatible with sub-path deployments. +7. Member list not refreshing when switching teams. +8. List API null pointer possibility when joining member data. +9. Workflow base nodes unable to upgrade. +10. Vector search results not deduplicated. +11. User selection node unable to connect properly. +12. Chat record source not being saved correctly. diff --git a/document/content/docs/upgrading/4-8/4823.en.mdx b/document/content/docs/upgrading/4-8/4823.en.mdx new file mode 100644 index 0000000000..84211bd768 --- /dev/null +++ b/document/content/docs/upgrading/4-8/4823.en.mdx @@ -0,0 +1,50 @@ +--- +title: V4.8.23 +description: FastGPT V4.8.23 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your database + +### 2. Update images: + +- Update the fastgpt image tag to v4.8.23-fix +- Update the fastgpt-pro commercial edition image tag to v4.8.23-fix +- Sandbox image update is not required + +### 3. Run migration script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4823' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +The script cleans up Knowledge Base dirty data, primarily redundant full-text indexes. + +## New Features + +1. Added default "Knowledge Base text understanding model" configuration. +2. AI Proxy V1, which can replace OneAPI and provides complete model call logs for easier troubleshooting. +3. Added support ticket entry point. + +## Improvements + +1. Model configuration form now includes required field validation. +2. Collection list data statistics method improved for better performance with large datasets. +3. Optimized math formulas: LaTeX format is now escaped to Markdown format. +4. Document image parsing: oversized images are now automatically skipped. +5. Time picker: start time defaults to 00:00:00 and end time to 23:59:59 for the selected day, preventing UI/logic discrepancies. +6. Upgraded mongoose library dependency. + +## Bug Fixes + +1. Tag filtering not working correctly for subfolders. +2. Temporarily removed Markdown reading optimization to prevent link splitting errors. +3. Member list not refreshing when leaving a team. +4. PPTX encoding error causing parsing failures. +5. Full-text index not deleted when removing a single Knowledge Base data entry. +6. Fixed Mongo Dataset text index not taking effect during data queries. diff --git a/document/content/docs/upgrading/4-8/483.en.mdx b/document/content/docs/upgrading/4-8/483.en.mdx new file mode 100644 index 0000000000..7d0d420108 --- /dev/null +++ b/document/content/docs/upgrading/4-8/483.en.mdx @@ -0,0 +1,18 @@ +--- +title: V4.8.3 +description: FastGPT V4.8.3 Release Notes +--- + +## Upgrade Guide + +- Update the fastgpt image tag to v4.8.3 +- Update the fastgpt-sandbox image tag to v4.8.3 +- Update the commercial edition image tag to v4.8.3 + +## V4.8.3 Release Notes + +1. New - Milvus database support. See the latest [docker-compose-milvus.yml](https://github.com/labring/FastGPT/blob/main/deploy/docker/docker-compose-milvus.yml) for reference. +2. New - Added logging for empty answers in the chat API to help troubleshoot model issues. +3. New - If/Else conditional node now supports regex for string matching. +4. New - Code execution node now supports console.log for debug output. +5. Fixed - Variable update failing in Debug mode. diff --git a/document/content/docs/upgrading/4-8/484.en.mdx b/document/content/docs/upgrading/4-8/484.en.mdx new file mode 100644 index 0000000000..6def818afd --- /dev/null +++ b/document/content/docs/upgrading/4-8/484.en.mdx @@ -0,0 +1,34 @@ +--- +title: V4.8.4 (Includes Upgrade Script) +description: FastGPT V4.8.4 Release Notes +--- + +## Upgrade Guide + +### 1. Update Images + +- Update the fastgpt image tag to v4.8.4 +- Update the fastgpt-sandbox image tag to v4.8.4 (optional, no changes) +- Update the commercial edition image tag to v4.8.4 + +### 2. Commercial Edition Initialization + +From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT commercial edition domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/init/484' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +## V4.8.4 Release Notes + +1. New - Apps now use the new permission system. +2. New - Apps now support folders. +3. Improved - Text splitting now removes consecutive line breaks and tabs to avoid performance issues with large text. +4. Critical Fix - Fixed system plugin runtime pool data pollution. Since data was loaded from memory, it caused global state contamination. +5. Fixed - Debug mode showing abnormal connections when source and target content are identical. +6. Fixed - Scheduled execution initialization error. +7. Fixed - App invocation parameter passing error. +8. Fixed - Incorrect nodeId when copying complex nodes with Ctrl+C/V. +9. Adjusted global theme for the component library. diff --git a/document/content/docs/upgrading/4-8/485.en.mdx b/document/content/docs/upgrading/4-8/485.en.mdx new file mode 100644 index 0000000000..5394aaa662 --- /dev/null +++ b/document/content/docs/upgrading/4-8/485.en.mdx @@ -0,0 +1,57 @@ +--- +title: V4.8.5 (Includes Upgrade Script) +description: FastGPT V4.8.5 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Database + +### 2. Update Images + +- Update the fastgpt image tag to v4.8.5 +- Update the commercial edition image tag to v4.8.5 + +### 3. Run Initialization + +From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv485' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will merge the plugin data table into the app table. The plugin table will not be deleted. + +------ + +**Commercial edition users: run the additional initialization below** + +From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/init/485' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will reset the Knowledge Base permission system. + +## V4.8.5 Release Notes + +1. New - Merged plugins and apps into a unified workspace. +2. New - App duplication feature. +3. New - App template creation. +4. New - Code execution results can now be used as tool output. +5. New - Markdown image output supports pinch-to-zoom on mobile. +6. Improved - Raw file encoding for storage and retrieval. +7. Improved - Simple mode now filters out deleted Knowledge Bases to avoid false error states. +8. Improved - Folder reading now supports more than 100 files per folder. +9. Improved - QA splitting / manual entry: when an `a` field is present, the `q` field is automatically used as a supplementary index. +10. Improved - Chat dialog page code. +11. Improved - New workflow nodes are now auto-numbered. +12. Fixed - Scheduled tasks could not actually be disabled. +13. Fixed - Input guide special characters causing regex errors. +14. Fixed - Files containing unescaped `%` characters causing page crashes. +15. Fixed - Page crash when selecting Knowledge Base references in custom input. diff --git a/document/content/docs/upgrading/4-8/486.en.mdx b/document/content/docs/upgrading/4-8/486.en.mdx new file mode 100644 index 0000000000..8ebe1918bf --- /dev/null +++ b/document/content/docs/upgrading/4-8/486.en.mdx @@ -0,0 +1,47 @@ +--- +title: V4.8.6 (Includes Upgrade Script) +description: FastGPT V4.8.6 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Database + +### 2. Update Images + +- Update the fastgpt image tag to v4.8.6 +- Update the fastgpt-sandbox image tag to v4.8.6 +- Update the commercial edition image tag to v4.8.6 + +### 3. Run Initialization + +From any terminal, send 1 HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv486' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will initialize inherited permissions for apps. + +------- + +## V4.8.6 Release Notes + +1. New - App permission inheritance. +2. New - Knowledge Base now supports disabling individual collections. +3. New - System plugin architecture change. Added link reader and math calculator plugins. The official release will include documentation on creating custom system plugins. +4. New - Code sandbox runtime parameters. +5. New - Option to hide the header during AI conversations, primarily for mobile optimization. +6. Improved - File reading now defaults to MongoDB secondary nodes to reduce primary node load. +7. Improved - Prompt templates. +8. Improved - Fixed duplicate Mongo model loading. +9. Fixed - Creating a link collection not returning the ID. +10. Fixed - API documentation descriptions. +11. Fixed - API system prompt merging. +12. Fixed - Content inside team plugin folders failing to load. +13. Fixed - Knowledge Base collection folder breadcrumbs failing to load. +14. Fixed - Markdown export conversation error. +15. Fixed - Prompt template closing tag error. +16. Fixed - Documentation descriptions. diff --git a/document/content/docs/upgrading/4-8/487.en.mdx b/document/content/docs/upgrading/4-8/487.en.mdx new file mode 100644 index 0000000000..b4f00c0071 --- /dev/null +++ b/document/content/docs/upgrading/4-8/487.en.mdx @@ -0,0 +1,24 @@ +--- +title: V4.8.7 +description: FastGPT V4.8.7 Release Notes +--- +## Upgrade Guide + +### 1. Back up your database + +### 2. Update images + +- Update the fastgpt image tag to v4.8.7 +- Update the commercial edition image tag to v4.8.7 + +------- + +## V4.8.7 Release Notes + +1. New - Plugins now support standalone execution, publishing, and log viewing. +2. New - App search. +3. Improved - Chat dialog code. +4. Improved - Upgraded Dockerfile Node and pnpm versions. +5. Improved - Vision mode now works properly with local domain deployments. +6. Fixed - Unable to modify global variables in Simple Mode. +7. Fixed - GPT-4o unable to use tools and images simultaneously. diff --git a/document/content/docs/upgrading/4-8/488.en.mdx b/document/content/docs/upgrading/4-8/488.en.mdx new file mode 100644 index 0000000000..d4473755a8 --- /dev/null +++ b/document/content/docs/upgrading/4-8/488.en.mdx @@ -0,0 +1,47 @@ +--- +title: V4.8.8 (Includes Migration Script) +description: FastGPT V4.8.8 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your database + +### 2. Update images + +- Update the fastgpt image tag to v4.8.8-fix2 +- Update the commercial edition image tag to v4.8.8 + +### 3. Run initialization + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv488' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This will initialize inherited permissions for Knowledge Bases. + +------- + +## V4.8.8 Release Notes + +[View full release notes](https://github.com/labring/FastGPT/releases/tag/v4.8.8) + +1. New - Restructured system plugin architecture. Community members can now submit system plugins via PR. See: [How to Submit System Plugins to the FastGPT Community](https://fael3z0zfze.feishu.cn/wiki/ERZnw9R26iRRG0kXZRec6WL9nwh). +2. New - DuckDuckGo system plugin. +3. New - Lark webhook system plugin. +4. New - Revamped variable input method. Prompt input fields and all Textarea inputs in workflows now support typing `/` to trigger variable selection, allowing you to directly pick any upstream output value without dynamic imports. +5. Commercial - Knowledge Base permission inheritance. +6. Improved - Mobile quick app switching interaction. +7. Improved - Node icons. +8. Improved - Added a dedicated copy button to chat references for easier copying. Added collapsible reference content. +9. Improved - Upgraded OpenAI SDK with a custom Whisper model interface (the SDK's built-in Whisper interface doesn't seem to work well with standard FastAPI endpoints). +10. Fixed - Permission table declaration issue. +11. Fixed - Parallel execution nodes not recording run time correctly. +12. Fixed - Run details not displaying nested node information correctly. +13. Fixed - Simple Mode failing to load Knowledge Base configuration on first entry. +14. Fixed - Log debug level configuration not taking effect. +15. Fixed - When running plugins standalone, plugin input values were being variable-substituted, potentially causing downstream node variable issues. diff --git a/document/content/docs/upgrading/4-8/489.en.mdx b/document/content/docs/upgrading/4-8/489.en.mdx new file mode 100644 index 0000000000..a440cc2391 --- /dev/null +++ b/document/content/docs/upgrading/4-8/489.en.mdx @@ -0,0 +1,51 @@ +--- +title: V4.8.9 (Requires Initialization) +description: FastGPT V4.8.9 Release Notes +--- + +## Upgrade Guide + +### 1. Back up your database + +### 2. Update images + +- Update the FastGPT image tag to v4.8.9 +- Update the FastGPT commercial edition image tag to v4.8.9 +- Sandbox image update is optional + +### 3. Run initialization (Commercial Edition) + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/init/489' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +This initializes notification methods for multi-tenancy (internal use only, no action needed). + +------- + +## V4.8.9 Release Notes + +1. New - File upload configuration. Image upload capability is now determined by system configuration rather than relying on vision model availability. +2. New - AI chat node and tool calls support toggling "Enable image recognition". When enabled, it automatically retrieves images uploaded in the chat and image URLs from "User question". +3. New - Document parsing node. +4. Commercial - Team notification account binding for receiving important messages. +5. Commercial - Knowledge Base collection tagging for tag-based management. +6. Commercial - Knowledge Base search node supports tag filtering and creation date filtering. +7. Commercial - Transfer app owner permissions. +8. New - Delete all conversation starters. +9. New - QA splitting supports custom chunk sizes, and optimized the issue where GPT-4o-mini produced very little content with large chunks. +10. Improved - Lazy loading for chat messages to reduce network transfer. +11. Improved - Clear file selection cache to allow re-selecting the same file. +12. Fixed - Knowledge Base file upload progress not reaching 100% under unstable network or with many files. +13. Fixed - After deleting an app, returning to chat and selecting the last conversation from the deleted app showed an error. +14. Fixed - Plugin dynamic variable default values not displaying correctly. +15. Fixed - Tool call temperature and max response values not taking effect. +16. Fixed - In function call mode, GPT models require the `content` parameter in assistant role messages (doesn't affect most models since nearly all have switched to ToolChoice mode; FC mode is deprecated). +17. Fixed - Knowledge Base file upload progress updates could be incorrect. +18. Fixed - Knowledge Base page always resetting to the first page during rebuilding. +19. Fixed - Knowledge Base list OpenAPI authentication issue. +20. Fixed - Unable to provide feedback on new conversations via share links. diff --git a/document/content/docs/upgrading/4-8/meta.en.json b/document/content/docs/upgrading/4-8/meta.en.json new file mode 100644 index 0000000000..02d7e3d224 --- /dev/null +++ b/document/content/docs/upgrading/4-8/meta.en.json @@ -0,0 +1,56 @@ +{ + "title": "<4.9.0", + "description": "", + "pages": [ + "4823", + "4822", + "4821", + "4820", + "4819", + "4818", + "4817", + "4816", + "4815", + "4814", + "4813", + "4812", + "4811", + "4810", + "489", + "488", + "487", + "486", + "485", + "484", + "483", + "482", + "481", + "48", + "471", + "47", + "469", + "468", + "467", + "466", + "465", + "464", + "463", + "462", + "461", + "46", + "452", + "451", + "45", + "447", + "446", + "445", + "442", + "441", + "44", + "43", + "421", + "42", + "41", + "40" + ] +} diff --git a/document/content/docs/upgrading/4-9/490.en.mdx b/document/content/docs/upgrading/4-9/490.en.mdx new file mode 100644 index 0000000000..8cf36113f0 --- /dev/null +++ b/document/content/docs/upgrading/4-9/490.en.mdx @@ -0,0 +1,186 @@ +--- +title: V4.9.0 (Includes Upgrade Script) +description: FastGPT V4.9.0 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Database + +### 2. Update Images and PG Container + +- Update FastGPT image tag: v4.9.0 +- Update FastGPT Pro image tag: v4.9.0 +- Sandbox image: no update required +- Update PG container to v0.8.0-pg15. See the [latest yml](https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-pgvector.yml) + +### 3. Replace OneAPI (Optional) + +Follow this step if you want to replace OneAPI with [AI Proxy](https://github.com/labring/aiproxy). + +#### 1. Modify the yml File + +Refer to the [latest yml](https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-pgvector.yml) file. OneAPI has been removed and AI Proxy configuration has been added, including one service and one PgSQL database. Append the `aiproxy` configuration after the OneAPI configuration (don't remove OneAPI yet — the initialization process will automatically sync OneAPI's configuration). + +
+AI Proxy Yml Configuration + +``` + # AI Proxy + aiproxy: + image: 'ghcr.io/labring/aiproxy:latest' + container_name: aiproxy + restart: unless-stopped + depends_on: + aiproxy_pg: + condition: service_healthy + networks: + - fastgpt + environment: + # Corresponds to AIPROXY_API_TOKEN in FastGPT + - ADMIN_KEY=aiproxy + # Error log detail retention time (hours) + - LOG_DETAIL_STORAGE_HOURS=1 + # Database connection URL + - SQL_DSN=postgres://postgres:aiproxy@aiproxy_pg:5432/aiproxy + # Maximum retry attempts + - RETRY_TIMES=3 + # Billing not required + - BILLING_ENABLED=false + # Strict model validation not required + - DISABLE_MODEL_CONFIG=true + healthcheck: + test: ['CMD', 'curl', '-f', 'http://localhost:3000/api/status'] + interval: 5s + timeout: 5s + retries: 10 + aiproxy_pg: + image: pgvector/pgvector:0.8.0-pg15 # docker hub + # image: registry.cn-hangzhou.aliyuncs.com/fastgpt/pgvector:v0.8.0-pg15 # Alibaba Cloud + restart: unless-stopped + container_name: aiproxy_pg + volumes: + - ./aiproxy_pg:/var/lib/postgresql/data + networks: + - fastgpt + environment: + TZ: Asia/Shanghai + POSTGRES_USER: postgres + POSTGRES_DB: aiproxy + POSTGRES_PASSWORD: aiproxy + healthcheck: + test: ['CMD', 'pg_isready', '-U', 'postgres', '-d', 'aiproxy'] + interval: 5s + timeout: 5s + retries: 10 +``` + +
+ +#### 2. Add FastGPT Environment Variables: + +Modify the environment variables for the FastGPT container in the yml file: + +``` +# AI Proxy address — takes priority if configured +- AIPROXY_API_ENDPOINT=http://aiproxy:3000 +# AI Proxy Admin Token, must match the ADMIN_KEY env var in AI Proxy +- AIPROXY_API_TOKEN=aiproxy +``` + +#### 3. Restart Services + +Run `docker-compose down` to stop services, then `docker-compose up -d` to start them. This will add the `aiproxy` service and update FastGPT's configuration. + +#### 4. Run the OneAPI to AI Proxy Migration Script + +- If the container has internet access: + +```bash +# Enter the aiproxy container +docker exec -it aiproxy sh +# Install curl +apk add curl +# Run the migration script +curl --location --request POST 'http://localhost:3000/api/channels/import/oneapi' \ +--header 'Authorization: Bearer aiproxy' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "dsn": "mysql://root:oneapimmysql@tcp(mysql:3306)/oneapi" +}' +# A response of {"data":[],"success":true} indicates success +``` + +- If the container has no internet access, expose the `aiproxy` external port and run the script locally. + +Expose the aiproxy port: 3003:3000, then run `docker-compose up -d` to restart services. + +```bash +# Run the script from your terminal +curl --location --request POST 'http://localhost:3003/api/channels/import/oneapi' \ +--header 'Authorization: Bearer aiproxy' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "dsn": "mysql://root:oneapimmysql@tcp(mysql:3306)/oneapi" +}' +# A response of {"data":[],"success":true} indicates success +``` + +- If you're not familiar with Docker operations, skip the migration script and manually re-add channels after removing all OneAPI content. + +#### 5. Verify AI Proxy is Running in FastGPT + +Log in with the root account. On the `Account - Model Providers` page, you should see two new options: `Model Channels` and `Call Logs`. Open Model Channels to verify that your previous OneAPI channels are listed, confirming the migration was successful. You can then manually check that each channel is working properly. + +#### 6. Remove the OneAPI Service + +```bash +# Stop services, or selectively stop OneAPI and its MySQL +docker-compose down +# Remove OneAPI and its MySQL dependency from the yml file +# Restart services +docker-compose up -d +``` + +### 4. Run the FastGPT Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv490' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +**Script Functions** + +1. Upgrades the PG Vector extension version. +2. Updates all knowledge base collection fields. +3. Updates the index `type` field across all knowledge base data. (This takes a while — you may see a timeout at the end, which can be ignored. The process will continue incrementally as long as the database is running.) + +## Compatibility & Deprecations + +1. Deprecated — The previous custom file parsing solution for private deployments. Please update to the latest configuration. [See PDF Enhanced Parsing Configuration](/docs/introduction/development/configuration/#使用-doc2x-解析-pdf-文件) +2. Deprecated — The legacy local file upload API: `/api/core/dataset/collection/create/file` (previously available only in the Pro edition). This endpoint has been replaced by: `/api/core/dataset/collection/create/localFile` +3. Maintenance ending, deprecation upcoming — External file library APIs. Use the API File Library as a replacement. +4. API Update — For endpoints that include a `trainingType` field (file upload to knowledge base, link collection creation, API file library, push chunk data, etc.), `trainingType` will only support `chunk` and `QA` modes going forward. Enhanced indexing mode will use a separate field: `autoIndexes`. Legacy `trainingType=auto` code is still supported for now, but please migrate to the new API format as soon as possible. See: [Knowledge Base OpenAPI Documentation](/docs/openapi/dataset.md) + +## New Features + +1. PDF enhanced parsing UI added to the page. Doc2x service is now built in, allowing direct PDF parsing via Doc2x. +2. Automatic image annotation, along with updated data logic and UI for knowledge base file uploads. +3. PG Vector extension upgraded to 0.8.0, introducing iterative search to reduce cases where data cannot be retrieved. +4. Added qwen-qwq series model configurations. + +## Improvements + +1. Knowledge base data no longer has a limit on the number of indexes — unlimited custom indexes are now supported. Input text indexes are automatically updated without affecting custom indexes. +2. Markdown parsing now detects Chinese punctuation after links and adds spacing. +3. Prompt-mode tool calls now support reasoning models, with improved format detection to reduce empty outputs. +4. Merged Mongo file read streams to reduce computation. Optimized storage chunks for significantly faster large file reads — 50MB PDF read time improved by 3x. +5. HTTP Body adaptation now supports string object types. + +## Bug Fixes + +1. Added security link validation for web scraping. +2. During batch runs, global variables were not passed to subsequent runs, causing incorrect final variable updates. diff --git a/document/content/docs/upgrading/4-9/491.en.mdx b/document/content/docs/upgrading/4-9/491.en.mdx new file mode 100644 index 0000000000..fe3aa1f8de --- /dev/null +++ b/document/content/docs/upgrading/4-9/491.en.mdx @@ -0,0 +1,61 @@ +--- +title: V4.9.1 +description: FastGPT V4.9.1 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Database + +### 2. Update Images + +- Update FastGPT image tag: v4.9.1-fix2 +- Update FastGPT Pro image tag: v4.9.1-fix2 +- Sandbox image: no update required +- AIProxy image changed to: registry.cn-hangzhou.aliyuncs.com/labring/aiproxy:v0.1.3 + +### 3. Run the Upgrade Script + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv491' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +**Script Functions** + +Re-processes tokenization using the latest jieba dictionary. This takes a while — you can monitor progress in the logs. + +## New Features + +1. Pro edition supports single-team mode for better internal member management. +2. Knowledge base chunk reader. +3. API knowledge base supports PDF enhanced parsing. +4. Team member invitations now use an invite link model. +5. Hybrid search weight configuration support. +6. Rerank model selection and weight configuration support. The knowledge base search weight calculation has been adjusted from `vector search weight + full-text search weight + rerank weight` to `search weight + rerank weight`. This may affect search results — you can adjust the relevant weights to adapt your data. + +## Improvements + +1. Knowledge base data input UI improvements. +2. App-bound knowledge base data fetching moved to backend processing. +3. Added dependency package security version checks and upgraded some dependencies. +4. Model testing code improvements. +5. Optimized reasoning output parsing: as long as a model is configured to support reasoning, `` tags will always be parsed, even when reasoning is disabled during a conversation. +6. Loaded the latest jieba dictionary for improved full-text search tokenization. + +## Bug Fixes + +1. Max response tokens tooltip showing incorrect values. +2. HTTP Node failing to parse strings containing newline characters. +3. Knowledge base question optimization not passing conversation history. +4. Missing error message translations. +5. Content extraction node: incorrect schema for array types. +6. Model channel testing not actually targeting the specified channel. +7. Adding a custom model would also save default model fields, causing incorrect default model detection. +8. Prompt-mode tool calls not null-checking the reasoning chain, causing UI rendering errors. +9. Editing app info causing avatar loss. +10. Share link titles being reset on refresh. +11. Authentication failure when calculating parentPath, causing it to be cleared. diff --git a/document/content/docs/upgrading/4-9/4910.en.mdx b/document/content/docs/upgrading/4-9/4910.en.mdx new file mode 100644 index 0000000000..afff9d7dc0 --- /dev/null +++ b/document/content/docs/upgrading/4-9/4910.en.mdx @@ -0,0 +1,46 @@ +--- +title: V4.9.10 +description: FastGPT V4.9.10 Release Notes +--- + +## Upgrade Guide + +Important: This update rebuilds the full-text index. During the rebuild, full-text search results will be empty. On a 4c16g instance, rebuilding approximately 7 million full-text indexes takes about 25 minutes. For a seamless upgrade, you'll need to handle table synchronization yourself. + +### 1. Back Up Your Data + +### 2. Update Image Tags + +- Update FastGPT image tag: v4.9.10-fix2 +- Update FastGPT Pro image tag: v4.9.10-fix2 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +## New Features + +1. Support for setting the `systemEnv.hnswMaxScanTuples` parameter in PG to increase the total data volume for iterative search. +2. Knowledge base preprocessing now includes a "Chunk Conditions" parameter to control when chunking should be skipped. +3. Knowledge base preprocessing now includes a "Paragraph Priority" mode with configurable maximum paragraph depth. The previous "Length Priority" mode no longer includes embedded paragraph priority logic. +4. Workflow adjusted to single-direction input/output connections, with quick "add next node" support. +5. Lark and Yuque knowledge bases are now available in the Community Edition. +6. Latest Gemini and Claude model presets. + +## Improvements + +1. Increased default timeout for LLM stream calls. +2. Various confirmation dialog UI improvements. +3. Renamed the knowledge base "Table Dataset" to "Backup Import". Also added support for exporting and importing knowledge base indexes. +4. Knowledge base citation limit in workflows: if no related AI nodes exist in the workflow, the interaction mode switches to manual input only, with a limit of 10 million. +5. Mobile voice input now accurately detects whether the device is a phone rather than just a small screen. +6. Optimized context truncation algorithm to always preserve at least one Human message. + +## Bug Fixes + +1. Incorrect score sorting during full-text search across multiple knowledge bases. +2. Stream response potentially capturing incorrect `finish_reason` values. +3. Tool call mode not saving reasoning output. +4. Knowledge base `indexSize` parameter not taking effect. +5. Incorrect preview citations and context after 2 levels of workflow nesting. +6. Extra leading space when converting xlsx to Markdown. +7. Base64 images in Markdown files not being extracted and saved during file reading. diff --git a/document/content/docs/upgrading/4-9/4911.en.mdx b/document/content/docs/upgrading/4-9/4911.en.mdx new file mode 100644 index 0000000000..da888b57cd --- /dev/null +++ b/document/content/docs/upgrading/4-9/4911.en.mdx @@ -0,0 +1,54 @@ +--- +title: V4.9.11 (Includes Upgrade Script) +description: FastGPT V4.9.11 Release Notes +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.9.11 +- Update FastGPT Pro image tag: v4.9.11 +- mcp_server: no update required +- Update Sandbox image tag: v4.9.11 +- AIProxy: no update required + +### 2. Run the Upgrade Script + +This script only needs to be run by Pro edition users. + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**. + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv4911' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +**Script Functions** + +1. Migrates third-party knowledge base API configurations. + +## New Features + +1. Pro edition supports image knowledge bases. +2. Added node search functionality in the workflow editor. +3. Sub-workflow version control in workflows now supports a "Keep Latest Version" option — no manual updates needed. +4. Additional audit operation logs. +5. Knowledge base now has an async document parsing queue — documents can be imported without waiting for parsing to complete. +6. Third-party knowledge base development documentation. [View here](/docs/introduction/guide/knowledge_base/third_dataset/) + +## Improvements + +1. Raw text cache now uses GridFS storage for higher capacity. +2. Added knowledge base template import option. + +## Bug Fixes + +1. Admin-declared global system tools in workflows unable to be version-managed. +2. Context errors when an interactive node precedes a tool call node. +3. Backup import failing to chunk content under 1,000 characters. +4. Custom PDF parsing unable to save Base64 images. +5. Non-stream requests not performing CITE marker replacement. +6. Hidden security vulnerability in the Python sandbox. +7. Missing confirm button when importing plugins via curl. diff --git a/document/content/docs/upgrading/4-9/4912.en.mdx b/document/content/docs/upgrading/4-9/4912.en.mdx new file mode 100644 index 0000000000..13e995048a --- /dev/null +++ b/document/content/docs/upgrading/4-9/4912.en.mdx @@ -0,0 +1,49 @@ +--- +title: V4.9.12 +description: FastGPT V4.9.12 Release Notes +--- + +## Upgrade Guide + +### 1. Update Environment Variables + +Add the following environment variable to both the `fastgpt` and `fastgpt-pro` image configurations: `AES256_SECRET_KEY=` — used for secret key encryption. + +### 2. Update Images: + +- Update FastGPT image tag: v4.9.12 +- Update FastGPT Pro image tag: v4.9.12 +- mcp_server: no update required +- Sandbox: no update required +- Update AIProxy image tag: v0.2.2 + +## New Features + +1. Enhanced AI Proxy monitoring with chart and table views for model call and performance metrics. +2. HTTP nodes and MCP now support separate "Auth Configuration" — plaintext credentials are never sent back to the client, ensuring data security. +3. Question classification and content extraction now automatically include the previous round's results in the prompt for additional guidance. +4. Conditional node now supports variable references. +5. Pro edition supports LLM-based automatic segment detection during knowledge base chunking. +6. Admin dashboard with data analytics. +7. Doubao 1.6 series models and updated Qwen model configurations. + +## Improvements + +1. Password validation now accepts more special characters. +2. Backend now fully computes knowledge base chunk parameters to prevent default values from being incorrectly applied in auto mode. +3. Text chunking moved to a worker thread to avoid blocking. +4. More subscription plan usage information displayed. +5. Input box styling improvements, with updated voice input UI for both desktop and mobile. +6. MCP tool calls now use raw schema for invocation to ensure completeness. +7. Deleting knowledge base files no longer fails if the file doesn't exist. +8. Upgraded MCP SDK with compatibility for the latest HTTP Streamable protocol. +9. Yuque document library now recursively fetches data from document-type directories. + +## Bug Fixes + +1. Custom QA extraction prompts being overwritten. +2. Template import failing when empty indexes exist in the data. +3. Potential XSS vulnerability on the login page. +4. Voice input in the text box causing the file list to be lost. +5. Image TTL field not being cleared in knowledge base documents, causing images to expire. +6. MCP tool storage not escaping integer type data. diff --git a/document/content/docs/upgrading/4-9/4913.en.mdx b/document/content/docs/upgrading/4-9/4913.en.mdx new file mode 100644 index 0000000000..83198272bb --- /dev/null +++ b/document/content/docs/upgrading/4-9/4913.en.mdx @@ -0,0 +1,31 @@ +--- +title: V4.9.13 +description: FastGPT V4.9.13 Release Notes +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.9.13 +- Update FastGPT Pro image tag: v4.9.13 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + + +## New Features + +1. Subscription plan caching to reduce MongoDB query frequency. + +## Improvements + +1. All NodeId random value generation adjusted to avoid starting with a digit. +2. Knowledge base collection search now supports nested search. + +## Bug Fixes + +1. Chat log date range selection issues. +2. System prompt potentially being duplicated when passed via API calls. +3. AI chat/tool calls reading files from history even when no file link was selected. +4. Manually updating knowledge base indexes incorrectly deleting old indexes, causing manual indexes to become ineffective. diff --git a/document/content/docs/upgrading/4-9/4914.en.mdx b/document/content/docs/upgrading/4-9/4914.en.mdx new file mode 100644 index 0000000000..58ba84b97d --- /dev/null +++ b/document/content/docs/upgrading/4-9/4914.en.mdx @@ -0,0 +1,38 @@ +--- +title: V4.9.14 +description: FastGPT V4.9.14 Release Notes +--- + +## Upgrade Guide + +### 1. Update Images: + +- Update FastGPT image tag: v4.9.14 +- Update FastGPT Pro image tag: v4.9.14 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +## New Features + +1. Knowledge base import now supports automatically adding the filename to the system index. +2. Admin-side audit logs. + +## Improvements + +1. Unified knowledge base training queue code logic. +2. Input box UX improvements. +3. Image knowledge base now automatically removes line breaks from descriptions to prevent model output line breaks from breaking image display. +4. Image indexing now generates separate image content descriptions, and attaches them to search results after retrieval — enabling LLMs to understand image content. +5. Auto-completion for MCP Schema entries missing the `properties` field to prevent errors with certain models. +6. Error handling for potential JSON import template failures. +7. Dangerous characters filtered during CSV export. +8. Added security request headers. +9. Changing password now invalidates all other active sessions. +10. Citation display optimization: detects preceding URLs and automatically adds spacing. + +## Bug Fixes + +1. Knowledge base data input incorrectly detecting QA mode. +2. Knowledge base tag condition conflicts. +3. Chat log like/dislike statistics. diff --git a/document/content/docs/upgrading/4-9/492.en.mdx b/document/content/docs/upgrading/4-9/492.en.mdx new file mode 100644 index 0000000000..df90680ef3 --- /dev/null +++ b/document/content/docs/upgrading/4-9/492.en.mdx @@ -0,0 +1,73 @@ +--- +title: V4.9.2 +description: FastGPT V4.9.2 Release Notes +--- + +## Upgrade Guide + +You can skip directly to v4.9.3 — v4.9.2 has a workflow data type conversion bug. + +### 1. Back Up Your Database + +### 2. SSO Migration + +Pro edition users using SSO or member sync with DingTalk or WeCom need to migrate their existing SSO configuration: + +Refer to [SSO & External Member Sync](/docs/introduction/guide/admin/sso) for deploying and configuring the `sso-service`. + +1. Before upgrading images, copy and back up the existing configuration from the Pro admin panel (e.g., for WeCom, copy the AppId, Secret, etc.). +2. Follow the documentation above to deploy the SSO service and configure the relevant environment variables. +3. If you were previously using WeCom org structure sync, after upgrading, switch the team mode to "Sync Mode" in the Pro admin panel. + +### 3. Configuration Parameter Changes + +Rename the `systemEnv.pgHNSWEfSearch` parameter in your `config.json` file to `hnswEfSearch`. +Pro edition users can make this change in the admin panel under `System Configuration - Basic Settings` after upgrading. + +### 4. Update Images + +- Update FastGPT image tag: v4.9.2 +- Update FastGPT Pro image tag: v4.9.2 +- Sandbox image: no update required +- AIProxy image changed to: registry.cn-hangzhou.aliyuncs.com/labring/aiproxy:v0.1.4 + +## Important Updates + +- Knowledge base data import API changes: added optional parameters `chunkSettingMode`, `chunkSplitMode`, and `indexSize`. See the [Knowledge Base Data Import API](/docs/openapi/dataset) documentation for details. + +## New Features + +1. Knowledge base chunking optimization: supports separate configuration for chunk size and index size, allowing extra-large chunks that trade higher input tokens for complete chunks. +2. Knowledge base chunking now includes custom separator presets and supports custom newline-based splitting. +3. External variables renamed to Custom Variables. Now supports debugging during testing, and the variable is hidden in share links. +4. Collection sync now supports syncing title changes. +5. Team member management overhaul: extracted mainstream IM SSO (WeCom, Lark, DingTalk) and added support for connecting to FastGPT via custom SSO. Also improved member sync with external systems. +6. Support for `oceanbase` vector database. Set the `OCEANBASE_URL` environment variable to enable. +7. PDF parsing example based on mistral-ocr. +8. PDF parsing example based on miner-u. + +## Improvements + +1. Chat log export now includes member names. +2. Invite link UI improvements. +3. When SSL certificate is unavailable and copy fails, a dialog is shown for manual copying. +4. FastGPT now properly displays AI Proxy channel names even when channels are not built in. +5. Upgraded Next.js to version 14.2.25. +6. Workflow node array-string type now auto-adapts to string input. +7. Workflow node array type now automatically JSON-parses string input. +8. AI Proxy log optimization: removed retry failure logs, keeping only the final error log. +9. Personal info and notification display improvements. +10. Model testing loading animation improvements. +11. Minor chunking algorithm adjustments: + +- Stronger continuity between cross-processing symbols. +- Code blocks now use the LLM model context as chunk size to better preserve code block integrity. +- Tables now use the LLM model context as chunk size to better preserve table integrity. + +## Bug Fixes + +1. Lark and Yuque knowledge bases unable to sync. +2. Channel testing using the custom request URL instead of the channel request URL when a custom URL was configured. +3. Speech recognition model testing unable to test disabled models. +4. Admin-configured system plugins failing authentication when the plugin contains other system apps. +5. Removing TTS custom request URL requiring the requestAuth field to be filled. diff --git a/document/content/docs/upgrading/4-9/493.en.mdx b/document/content/docs/upgrading/4-9/493.en.mdx new file mode 100644 index 0000000000..5cb7740c60 --- /dev/null +++ b/document/content/docs/upgrading/4-9/493.en.mdx @@ -0,0 +1,25 @@ +--- +title: V4.9.3 +description: FastGPT V4.9.3 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Database + +### 2. Update Images + +- Update FastGPT image tag: v4.9.3 +- Update FastGPT Pro image tag: v4.9.3 +- Sandbox image tag: v4.9.3 +- AIProxy image tag: v0.1.5 + + +## New Features + +1. Workflow debug mode now supports interactive nodes. +2. Code execution now supports Python 3. + +## Bug Fixes + +1. Workflow format conversion errors. diff --git a/document/content/docs/upgrading/4-9/494.en.mdx b/document/content/docs/upgrading/4-9/494.en.mdx new file mode 100644 index 0000000000..fe4878ebbe --- /dev/null +++ b/document/content/docs/upgrading/4-9/494.en.mdx @@ -0,0 +1,62 @@ +--- +title: V4.9.4 +description: FastGPT V4.9.4 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Data + +### 2. Install Redis + +* For Docker deployments, refer to the latest `docker-compose.yml` file to add Redis configuration. Add a Redis container and configure the `REDIS_URL` environment variable for both `fastgpt` and `fastgpt-pro`. +* For Sealos deployments, create a new `redis` database in the Database section, copy the `internal connection` URL as the Redis connection string, then configure the `REDIS_URL` environment variable for both `fastgpt` and `fastgpt-pro`. + +| | | | +| --- | --- | --- | +| ![](/imgs/sealos-redis1.png) | ![](/imgs/sealos-redis2.png) | ![](/imgs/sealos-redis3.png) | + +### 3. Update Image Tags + +- Update FastGPT image tag: v4.9.4 +- Update FastGPT Pro image tag: v4.9.4 +- Sandbox: no update required +- AIProxy: no update required + +### 4. Run the Upgrade Script + +This script only needs to be run by Pro edition users. + +From any terminal, send an HTTP request. Replace `{{rootkey}}` with the `rootkey` from your environment variables, and `{{host}}` with your **FastGPT domain**: + +```bash +curl --location --request POST 'https://{{host}}/api/admin/initv494' \ +--header 'rootkey: {{rootkey}}' \ +--header 'Content-Type: application/json' +``` + +**Script Functions** + +1. Updates the site sync scheduler. + +## New Features + +1. Collection data training status display. +2. SMTP email sending plugin. +3. BullMQ message queue. +4. Partial data caching via Redis. +5. Site sync now supports configuring training parameters and incremental sync. +6. AI chat/tool calls now return the model's `finish_reason` field for easier tracking of output interruption causes. +7. Mobile voice input UI adjustments. + +## Improvements + +1. Admin template rendering adjustments. +2. Chat file expiration time now configurable via environment variable. +3. MongoDB log database can now be deployed independently. + +## Bug Fixes + +1. Unable to click into subdirectories when searching apps/knowledge bases. +2. Retraining parameters not properly initialized. +3. Inconsistent requests in package/service across multiple apps. diff --git a/document/content/docs/upgrading/4-9/495.en.mdx b/document/content/docs/upgrading/4-9/495.en.mdx new file mode 100644 index 0000000000..6c832bad55 --- /dev/null +++ b/document/content/docs/upgrading/4-9/495.en.mdx @@ -0,0 +1,35 @@ +--- +title: V4.9.5 +description: FastGPT V4.9.5 Release Notes +--- + +## Upgrade Guide +### 1. Back Up Your Data + +### 2. Update Image Tags + +- Update FastGPT image tag: v4.9.5 +- Update FastGPT Pro image tag: v4.9.5 +- Sandbox: no update required +- AIProxy: no update required + +## New Features + +1. Granular team member permissions: separately control whether members can create root-level apps/knowledge bases and API keys. +2. Interactive nodes now work inside nested workflows. +3. Team member operation audit logs. +4. User input node now supports checkboxes. + +## Improvements + +1. Traditional Chinese translation updates. +2. ARM image builds. + + +## Bug Fixes + +1. Incorrect password validation rules. +2. Share links unable to hide knowledge base search results. +3. Regex compatibility issues on older iOS versions. +4. QA extraction queue counter not resetting after errors, causing the queue to stop working. +5. Debug mode interactive nodes potentially causing infinite loops on next step. diff --git a/document/content/docs/upgrading/4-9/496.en.mdx b/document/content/docs/upgrading/4-9/496.en.mdx new file mode 100644 index 0000000000..d8c806c924 --- /dev/null +++ b/document/content/docs/upgrading/4-9/496.en.mdx @@ -0,0 +1,83 @@ +--- +title: V4.9.6 +description: FastGPT V4.9.6 Release Notes +--- + +## New Features + +1. Apps can now be called externally via MCP. +2. Support for creating tools using the MCP SSE protocol. +3. Batch execution node now supports interactive nodes, enabling human participation in each loop iteration. +4. Added workspace secondary menu with merged toolbox. +5. Added system configurations for grok3, GPT4.1, o-series, and Gemini 2.5 models. + +## Improvements + +1. Enhanced workflow data type conversion robustness and compatibility. +2. Python sandbox code now supports large data inputs. +3. Breadcrumb component now supports configuring whether the last step is clickable. +4. Knowledge base tool call results now automatically prepend image domain names. +5. GitHub Action runner upgraded to Ubuntu 24. +6. Removed extra leading/trailing newlines when replying via Lark, WeChat Official Account, and other third-party channels. +7. Adjusted chunking strategy: large tables are now split into independent chunks instead of being merged into oversized blocks. +8. Iframe embed component now includes built-in microphone permission declaration. + +## Bug Fixes + +1. Sub-workflows with interactive nodes not fully restoring all sub-workflow data. +2. Completion v1 API not accepting the `interactive` parameter, causing API call failures. +3. Consecutive tool calls causing abnormal context truncation. + +## Upgrade Guide + +### 1. Back Up Your Data + +### 2. Deploy the MCP Server Service + +#### Docker Deployment + +Add the `fastgpt-mcp-server` service to your `docker-compose.yml` file: + +```yml +fastgpt-mcp-server: + container_name: fastgpt-mcp-server + image: ghcr.io/labring/fastgpt-mcp_server:v4.9.6 + ports: + - 3005:3000 + networks: + - fastgpt + restart: always + environment: + - FASTGPT_ENDPOINT=http://fastgpt:3000 +``` + +#### Sealos Deployment + +In `App Management`, add a new `fastgpt-mcp-server` app with the image `ghcr.io/labring/fastgpt-mcp_server:v4.9.6` and set the environment variable `FASTGPT_ENDPOINT=`. + +### 3. Update FastGPT Container Environment Variables + +#### Community Edition + +Add the following to your `config.json` configuration file: `"feconfigs.mcpServerProxyEndpoint": ""` (no trailing slash). For example: + +```json +{ + "feConfigs": { + "lafEnv": "https://laf.dev", + "mcpServerProxyEndpoint": "https://mcp.fastgpt.cn" + } +} +``` + +#### Pro Edition + +In the Admin panel, go to `System Configuration - Basic Settings - System Parameters` and set the `MCP Proxy Server URL` to the public access URL of your `fastgpt-mcp-server`. + +### 4. Update Image Tags + +- Update FastGPT image tag: v4.9.6 +- Update FastGPT Pro image tag: v4.9.6 +- Update Sandbox image tag: v4.9.6 +- Add FastGPT MCP Server image tag: v4.9.6 +- AIProxy: no update required diff --git a/document/content/docs/upgrading/4-9/497.en.mdx b/document/content/docs/upgrading/4-9/497.en.mdx new file mode 100644 index 0000000000..4622a1d1e5 --- /dev/null +++ b/document/content/docs/upgrading/4-9/497.en.mdx @@ -0,0 +1,54 @@ +--- +title: V4.9.7 +description: FastGPT V4.9.7 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Data + +### 2. Update Image Tags + +- Update FastGPT image tag: v4.9.7-fix2 +- Update FastGPT Pro image tag: v4.9.7 +- mcp_server: no update required +- Sandbox: no update required +- Update AIProxy image tag: v0.1.8 + +## New Features + +1. Knowledge base answers now include citations at the end of each referenced paragraph. +2. MCP tools support the HTTP Streamable protocol. +3. MCP Server supports editing tool names to accommodate clients that don't support Chinese characters. +4. Right-click in the workflow editor to auto-align nodes. +5. Support for custom `config.json` path in production environments. +6. API calls support passing a special chatId (`NO_RECORD_HISTORIES`) to prevent the system from storing conversation history. +7. Rerank model usage-based billing support. +8. Subscription plan redemption codes. +9. Alipay payment support. +10. Short link analytics tracking. +11. Added Jina AI model system configuration. + +## Improvements + +1. Doc2x document parsing: added error message capture and increased timeout duration. +2. Adjusted PG vector query to force vector index usage. +3. Conversation time statistics now accurately return the overall workflow execution time. +4. Audio parsing duration now retrieved from ai_proxy. +5. AI model token counts now prioritize the API usage values for accuracy. If unavailable, falls back to GPT-3.5 estimation. +6. Optimized the chat log list API to handle scenarios with large numbers of messages in a single conversation. + +## Bug Fixes + +1. File upload chunk size limit to prevent exceeding MongoDB limits. +2. Usage dashboard unable to retrieve statistics for specific members. +3. Dashboard API returning incorrect statistics due to timezone handling issues. +4. LLM model test API unable to test disabled models. Also fixed the issue where model testing would strip custom request URLs. +5. Copy app permission issues. +6. Chat record export now limits individual conversations to 1,000 message pairs to prevent export failures. +7. Workflow variables followed by another workflow variable not triggering rendering. +8. Debugging the knowledge base search module showing "no permission" errors. +9. Text content extraction node default value assignment logic. +10. Share links forcibly returning citation content from nested apps. +11. Knowledge base collection metadata filtering: same-named tags across different knowledge bases returning no results when using `$and` filters. +12. App list permission configuration potentially causing index refresh issues. diff --git a/document/content/docs/upgrading/4-9/498.en.mdx b/document/content/docs/upgrading/4-9/498.en.mdx new file mode 100644 index 0000000000..a0893bc476 --- /dev/null +++ b/document/content/docs/upgrading/4-9/498.en.mdx @@ -0,0 +1,44 @@ +--- +title: V4.9.8 +description: FastGPT V4.9.8 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Data + +### 2. Update Image Tags + +- Update FastGPT image tag: v4.9.8 +- Update FastGPT Pro image tag: v4.9.8 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +## New Features + +1. Support for parallel tool call execution. +2. All built-in tasks switched from non-stream mode to stream mode to avoid compatibility issues with models that don't support non-stream mode. To override, you can force `stream=false` in the model's `Extra Body` parameters. +3. Qwen3 model presets. +4. Yuque knowledge base now supports setting a root directory. +5. Configurable password expiration — users will be forced to change their password on next login after expiration. +6. Password login now includes preLogin temporary key verification. +7. Admin panel now supports configuring visibility of publishing channels and third-party knowledge bases. + +## Improvements + +1. Chat log list optimization to prevent memory overflow with large datasets. +2. Token calculation worker is now preloaded to prevent thread blocking from concurrent creation during main tasks. +3. Workflow node version control UI improvements. +4. Web fetch and html2md optimization: now supports video and audio tag conversion. + +## Bug Fixes + +1. App list / knowledge base list: incorrect permission display for delete row actions. +2. Opening knowledge base search parameters automatically enabling the rerank option. +3. Incorrect API request format for LLM json_schema mode. +4. Expired image indexes not properly cleared during retraining, causing image loss. +5. Retraining permission issues. +6. Documentation link URLs. +7. Claude tool calls failing due to empty index values. +8. Nested workflows with interactive nodes inside tool calls causing abnormal flow behavior. diff --git a/document/content/docs/upgrading/4-9/499.en.mdx b/document/content/docs/upgrading/4-9/499.en.mdx new file mode 100644 index 0000000000..158d9cbd7f --- /dev/null +++ b/document/content/docs/upgrading/4-9/499.en.mdx @@ -0,0 +1,39 @@ +--- +title: V4.9.9 +description: FastGPT V4.9.9 Release Notes +--- + +## Upgrade Guide + +### 1. Back Up Your Data + +### 2. Pro Edition Users: Replace Your License + +Pro edition users can contact the FastGPT team for a license replacement plan. After replacement, you can upgrade the system directly — the admin panel will prompt you to enter the new license. + +### 3. Update Image Tags + +- Update FastGPT image tag: v4.9.9 +- Update FastGPT Pro image tag: v4.9.9 +- mcp_server: no update required +- Sandbox: no update required +- AIProxy: no update required + +## New Features + +1. Switched from JWT to SessionId-based login authentication, with configurable maximum concurrent client sessions. +2. New Pro edition license management model. +3. WeChat Official Account calls now display and log chat conversation errors for easier troubleshooting. +4. API knowledge base now supports BasePath selection. Requires an additional API endpoint — see [API Knowledge Base Introduction](/docs/introduction/guide/knowledge_base/api_dataset/#4-获取文件详细信息用于获取文件信息) for details. + +## Improvements + +1. Optimized tool call logic for new tool detection. +2. Adjusted citation prompt text. + +## Bug Fixes + +1. Unable to retrieve app history save/publish records. +2. Member MCP tool creation permission issues. +3. Source citation display passing incorrect IDs, causing "no permission to access this file" errors. +4. Answer annotation frontend data errors. diff --git a/document/content/docs/upgrading/4-9/meta.en.json b/document/content/docs/upgrading/4-9/meta.en.json new file mode 100644 index 0000000000..b246675b99 --- /dev/null +++ b/document/content/docs/upgrading/4-9/meta.en.json @@ -0,0 +1,21 @@ +{ + "title": "4.9.x", + "description": "", + "pages": [ + "4914", + "4913", + "4912", + "4911", + "4910", + "499", + "498", + "497", + "496", + "495", + "494", + "493", + "492", + "491", + "490" + ] +} diff --git a/document/content/docs/upgrading/index.en.mdx b/document/content/docs/upgrading/index.en.mdx new file mode 100644 index 0000000000..f6f7620e46 --- /dev/null +++ b/document/content/docs/upgrading/index.en.mdx @@ -0,0 +1,93 @@ +--- +title: Version Upgrade Guide +description: FastGPT version upgrade guide +--- + +Upgrading FastGPT involves two steps: + +1. Update the image +2. Run the upgrade initialization script + +## Image Names + +**GitHub Container Registry** + +- FastGPT main image: ghcr.io/labring/fastgpt:latest +- Plugin image: ghcr.io/labring/fastgpt-plugin +- Code sandbox image: ghcr.io/labring/fastgpt-sandbox +- MCP SSE server image: ghcr.io/labring/fastgpt-mcp_server +- Commercial edition image: ghcr.io/c121914yu/fastgpt-pro:latest + +**Alibaba Cloud** + +- FastGPT main image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt +- Plugin image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-plugin +- Code sandbox image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sandbox +- MCP SSE server image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-mcp_server +- Commercial edition image: ghcr:registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-pro + +An image consists of the image name and a `Tag`. For example, registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.6.1 refers to the `4.6.3` version image. Check Docker Hub or the GitHub repository for details. + +## Updating Images on Sealos + +1. Open [Sealos Cloud](https://cloud.sealos.io?uid=fnWRt09fZP) and find App Management on the desktop. + +![](/imgs/updateImageSealos1.jpg) + +2. Select the corresponding app - click the three dots on the right - Update. + +![](/imgs/updateImageSealos2.png) + +3. Update the image - Confirm changes. + + If you need to modify the configuration file, scroll down to the `Configuration File` section to make changes. + +![](/imgs/updateImageSealos3.png) + +## Updating Images with Docker Compose + +Simply modify the `image:` field in the `yml` file, then run: + +```bash +docker-compose pull +docker-compose up -d +``` + +## Running the Upgrade Initialization Script + +After updating the images, check the version notes in the documentation. Versions that require an upgrade script are typically labeled with "includes upgrade script". Open the corresponding documentation and follow the instructions to run the **upgrade script** -- in most cases, you just need to send a `POST` request. + +## FAQ + +### Why do I need to run an upgrade script? + +When there are significant changes to the database schema that cannot be handled through default values, or when the migration logic is complex, an upgrade script is used to update certain database fields. +Following the initialization steps carefully will not cause any data loss. However, if the data volume is large, the initialization may take a while, during which the service may be temporarily unavailable. + +### What is `{{host}}`? + +`{{}}` denotes a variable. `{{host}}` refers to a variable named "host", which is your server's domain name or IP address. + +On Sealos, you can find your domain name as shown below: + +![](/imgs/updateImageSealos4.png) + +### How to get the rootkey + +You can find it in the `environment` section of your `docker-compose.yml` file -- it's the value of `ROOT_KEY`. + +On Sealos, you can find it in the environment variables panel shown in the image above. + +### How to upgrade across multiple versions + +Back up your data first! + +You can upgrade to the latest version and then run all the upgrade scripts in order. However, for stability, we recommend upgrading one version at a time. For example, if your current version is 4.4.7 and you need to upgrade to 4.6: + +1. Update the image to 4.5, run the upgrade script +2. Update the image to 4.5.1, run the upgrade script +3. Update the image to 4.5.2, run the upgrade script +4. Update the image to 4.6, run the upgrade script +5. ..... + +Upgrade one version at a time. diff --git a/document/content/docs/upgrading/meta.en.json b/document/content/docs/upgrading/meta.en.json new file mode 100644 index 0000000000..beb662846f --- /dev/null +++ b/document/content/docs/upgrading/meta.en.json @@ -0,0 +1,22 @@ +{ + "root": true, + "title": "Version Updates & Upgrades", + "description": "FastGPT version updates and upgrade operations", + "pages": [ + "index", + "---4.14.x---", + "...4-14", + "---4.13.x---", + "...4-13", + "---4.12.x---", + "...4-12", + "---4.11.x---", + "...4-11", + "---4.10.x---", + "...4-10", + "---4.9.x---", + "...4-9", + "---<4.9.0---", + "...4-8" + ] +} diff --git a/document/content/docs/use-cases/app-cases/dalle3.en.mdx b/document/content/docs/use-cases/app-cases/dalle3.en.mdx new file mode 100644 index 0000000000..2982bbc95a --- /dev/null +++ b/document/content/docs/use-cases/app-cases/dalle3.en.mdx @@ -0,0 +1,467 @@ +--- +title: DALL-E 3 Image Generation +description: Generate images using the HTTP Request module with DALL-E 3 +--- + +| | | +| --------------------- | --------------------- | +| ![](/imgs/demo-dalle1.webp) | ![](/imgs/demo-dalle2.webp) | + +## OpenAI DALL-E 3 API + +Here are the official API parameters and response format: + +Body + +```json +{ + "model": "dall-e-3", + "prompt": "A cute baby sea otter", + "n": 1, + "size": "1024x1024" +} +``` + +Response + +```json +{ + "created": 1589478378, + "data": [ + { + "url": "https://..." + }, + { + "url": "https://..." + } + ] +} +``` + +## Workflow Design + +1. Use AI to optimize the image generation prompt (skipped here — use your own prompt). +2. Use the `HTTP Request` module to call the DALL-E 3 API and retrieve the image URL. +3. Use the `Text Editor` module to construct a `Markdown` image tag. +4. Use the `Specified Reply` module to output the image link directly. + +### 1. Build the HTTP Module + +Copy the DALL-E 3 API request parameters and replace `prompt` with a variable. You also need to add a `Headers.Authorization` header. + +Body: + +```json +{ + "model": "dall-e-3", + "prompt": "{{prompt}}", + "n": 1, + "size": "1024x1024" +} +``` + +Headers: + +`Authorization: Bearer sk-xxx` + +Response: + +Extract the response value based on the DALL-E 3 API return format. Since we only generate one image, we just need the first image's URL. Add a custom output `data[0].url` to the HTTP module. + +### 2. Text Editor — Build Image Link + +In `Markdown` syntax, `![image description](image URL)` inserts an image, where the image URL comes from the `HTTP Request` module output. + +Add an input to receive the image URL from the `HTTP Request` module, then reference it as a variable in the `Text Editor` module to produce a complete `Markdown` image tag. + +### 3. Specified Reply + +The Specified Reply module outputs incoming content directly to the client, so it can render the processed `Markdown` image format as-is. + +## Workflow Configuration +
+Workflow Configuration + +```json +{ + "nodes": [ + { + "nodeId": "userGuide", + "name": "System Config", + "intro": "Configure system parameters for the application", + "avatar": "/imgs/workflow/userGuide.png", + "flowNodeType": "userGuide", + "position": { + "x": 531.2422736065552, + "y": -486.7611729549753 + }, + "inputs": [ + { + "key": "welcomeText", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "core.app.Welcome Text", + "value": "" + }, + { + "key": "variables", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "core.app.Chat Variable", + "value": [] + }, + { + "key": "questionGuide", + "valueType": "boolean", + "renderTypeList": [ + "hidden" + ], + "label": "core.app.Question Guide", + "value": false + }, + { + "key": "tts", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": { + "type": "web" + } + }, + { + "key": "whisper", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": { + "open": false, + "autoSend": false, + "autoTTSResponse": false + } + }, + { + "key": "scheduleTrigger", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": null + } + ], + "outputs": [] + }, + { + "nodeId": "448745", + "name": "Workflow Start", + "intro": "", + "avatar": "/imgs/workflow/userChatInput.svg", + "flowNodeType": "workflowStart", + "position": { + "x": 532.1275542407774, + "y": 46.03775600322817 + }, + "inputs": [ + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "User Question", + "required": true, + "toolDescription": "User Question" + } + ], + "outputs": [ + { + "id": "userChatInput", + "key": "userChatInput", + "label": "core.module.input.label.user question", + "valueType": "string", + "type": "static" + } + ] + }, + { + "nodeId": "tMyUnRL5jIrC", + "name": "HTTP Request", + "intro": "Send an HTTP request for advanced operations (web search, database queries, etc.)", + "avatar": "/imgs/workflow/http.png", + "flowNodeType": "httpRequest468", + "showStatus": true, + "position": { + "x": 921.2377506442713, + "y": -483.94114977914256 + }, + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "core.module.input.description.HTTP Dynamic Input", + "editField": { + "key": true, + "valueType": true + } + }, + { + "key": "prompt", + "valueType": "string", + "label": "prompt", + "renderTypeList": [ + "reference" + ], + "description": "", + "canEdit": true, + "editField": { + "key": true, + "valueType": true + }, + "value": [ + "448745", + "userChatInput" + ] + }, + { + "key": "system_httpMethod", + "renderTypeList": [ + "custom" + ], + "valueType": "string", + "label": "", + "value": "POST", + "required": true + }, + { + "key": "system_httpReqUrl", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "", + "description": "core.module.input.description.Http Request Url", + "placeholder": "https://api.ai.com/getInventory", + "required": false, + "value": "https://api.openai.com/v1/images/generations" + }, + { + "key": "system_httpHeader", + "renderTypeList": [ + "custom" + ], + "valueType": "any", + "value": [ + { + "key": "Authorization", + "type": "string", + "value": "Bearer " + } + ], + "label": "", + "description": "core.module.input.description.Http Request Header", + "placeholder": "core.module.input.description.Http Request Header", + "required": false + }, + { + "key": "system_httpParams", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "value": [], + "label": "", + "required": false + }, + { + "key": "system_httpJsonBody", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "value": "{\n \"model\": \"dall-e-3\",\n \"prompt\": \"{{prompt}}\",\n \"n\": 1,\n \"size\": \"1024x1024\"\n}", + "label": "", + "required": false + } + ], + "outputs": [ + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "editField": { + "key": true, + "valueType": true + } + }, + { + "id": "httpRawResponse", + "key": "httpRawResponse", + "label": "Raw Response", + "description": "The raw HTTP response. Only accepts string or JSON response data.", + "valueType": "any", + "type": "static" + }, + { + "id": "DeKGGioBwaMf", + "type": "dynamic", + "key": "data[0].url", + "valueType": "string", + "label": "data[0].url" + } + ] + }, + { + "nodeId": "CO3POL8svbbi", + "name": "Text Editor", + "intro": "Process fixed or incoming text and output the result. Non-string data is converted to string.", + "avatar": "/imgs/workflow/textEditor.svg", + "flowNodeType": "pluginModule", + "showStatus": false, + "position": { + "x": 1417.5940290051137, + "y": -478.81889618104356 + }, + "inputs": [ + { + "key": "system_addInputParam", + "valueType": "dynamic", + "label": "Dynamic External Data", + "renderTypeList": [ + "addInputParam" + ], + "required": false, + "description": "", + "canEdit": false, + "value": "", + "editField": { + "key": true + }, + "dynamicParamDefaultValue": { + "inputType": "reference", + "valueType": "string", + "required": true + } + }, + { + "key": "url", + "valueType": "string", + "label": "url", + "renderTypeList": [ + "reference" + ], + "required": true, + "description": "", + "canEdit": true, + "editField": { + "key": true + }, + "value": [ + "tMyUnRL5jIrC", + "DeKGGioBwaMf" + ] + }, + { + "key": "文本", + "valueType": "string", + "label": "文本", + "renderTypeList": [ + "textarea" + ], + "required": true, + "description": "", + "canEdit": false, + "value": "![]({{url}})", + "editField": { + "key": true + }, + "maxLength": "", + "dynamicParamDefaultValue": { + "inputType": "reference", + "valueType": "string", + "required": true + } + } + ], + "outputs": [ + { + "id": "text", + "type": "static", + "key": "text", + "valueType": "string", + "label": "text", + "description": "" + } + ], + "pluginId": "community-textEditor" + }, + { + "nodeId": "7mapnCgHfKW6", + "name": "Specified Reply", + "intro": "Directly replies with specified content. Commonly used for guidance and prompts. Non-string input is converted to string for output.", + "avatar": "/imgs/workflow/reply.png", + "flowNodeType": "answerNode", + "position": { + "x": 1922.5628399315042, + "y": -471.67391598231796 + }, + "inputs": [ + { + "key": "text", + "renderTypeList": [ + "textarea", + "reference" + ], + "valueType": "string", + "label": "core.module.input.label.Response content", + "description": "core.module.input.description.Response content", + "placeholder": "core.module.input.description.Response content", + "selectedTypeIndex": 1, + "value": [ + "CO3POL8svbbi", + "text" + ] + } + ], + "outputs": [] + } + ], + "edges": [ + { + "source": "448745", + "target": "tMyUnRL5jIrC", + "sourceHandle": "448745-source-right", + "targetHandle": "tMyUnRL5jIrC-target-left" + }, + { + "source": "tMyUnRL5jIrC", + "target": "CO3POL8svbbi", + "sourceHandle": "tMyUnRL5jIrC-source-right", + "targetHandle": "CO3POL8svbbi-target-left" + }, + { + "source": "CO3POL8svbbi", + "target": "7mapnCgHfKW6", + "sourceHandle": "CO3POL8svbbi-source-right", + "targetHandle": "7mapnCgHfKW6-target-left" + } + ] +} +``` + +
diff --git a/document/content/docs/use-cases/app-cases/english_essay_correction_bot.en.mdx b/document/content/docs/use-cases/app-cases/english_essay_correction_bot.en.mdx new file mode 100644 index 0000000000..5494148d26 --- /dev/null +++ b/document/content/docs/use-cases/app-cases/english_essay_correction_bot.en.mdx @@ -0,0 +1,92 @@ +--- +title: English Essay Correction Bot +description: Build an English essay correction bot with FastGPT to detect and fix language errors +--- + +FastGPT provides a straightforward way to build applications powered by LLM models. + +This article demonstrates how to use **Workflows** by building an English essay correction bot. + +## Building Process + +### 1. Create a Workflow + +![](/imgs/spellcheck1.png) + +You can start from the *Multi-turn Translation Bot* template. + +> The Multi-turn Translation Bot was created by @米开朗基杨 — also a great workflow worth studying. + +### 2. Get Input and Analyze with LLM + +We want the LLM to process text and return structured data that we handle ourselves. + +![](/imgs/spellcheck2.png) + +The **System Prompt** is the most critical parameter. Here is a reference prompt: + +~~~markdown +## Role +Senior English Writing Expert + +## Task +Analyze the input text. Find all types of errors, including but not limited to spelling mistakes and grammar errors. +Note: Ignore spacing issues around punctuation. +Note: For sentences with errors, the suggestion should identify the specific part of the sentence and propose what to replace it with. + +## Output Format +Do not use Markdown syntax. Output in JSON format. +Output the "reason" field in Chinese. +Directly output a list whose members are objects of the same type, defined as follows: +``` +{ +"raw": string; // the original text +"reason": string; // the reason +"suggestion": string; // suggested correction +} +``` +~~~ + +You can disable AI reply in the model selection window. + +This hides the raw JSON output from the user. + +![](/imgs/spellcheck3.png) + +### 3. Data Processing + +The LLM outputs JSON, which needs further processing. Use the Code Execution module for this. + +![](/imgs/spellcheck4.png) + +```javascript +function main({data}){ + const array = JSON.parse(data) + return { + content: array.map( + (item, index) => { + return ` +## Analysis ${index+1} +- **Error**: ${item.raw} +- **Analysis**: ${item.reason} +- **Suggestion**: ${item.suggestion} +` + } + ).join('') + } +} +``` + +The code parses the JSON into an object, then concatenates it into a Markdown-formatted string. + +FastGPT's Specified Reply module renders Markdown as HTML in the response. + +## Publishing + +Publish through the available publishing channels. + +![](/imgs/spellcheck5.png) + +You can access it via URL or embed it directly into your webpage. + +> [Click to try it](https://share.fastgpt.in/chat/share?shareId=b4r173wkcjae7wpnexcvmyc3) diff --git a/document/content/docs/use-cases/app-cases/feishu_webhook.en.mdx b/document/content/docs/use-cases/app-cases/feishu_webhook.en.mdx new file mode 100644 index 0000000000..816a7dc2f5 --- /dev/null +++ b/document/content/docs/use-cases/app-cases/feishu_webhook.en.mdx @@ -0,0 +1,408 @@ +--- +title: Send Lark Webhook Notifications +description: Use the Tool Call module to send Lark webhook notifications +--- + +This article shows how to send a simple Lark webhook notification. The same approach applies to other types of notifications. + +| | | +| --------------------- | --------------------- | +| ![](/imgs/feishuwebhook1.webp) | ![](/imgs/feishuwebhook2.webp) | + +## 1. Set Up the Lark Bot + +| | | | +| --------------------- | --------------------- |--------------------- | +| ![](/imgs/feishuwebhook3.png) | ![](/imgs/feishuwebhook4.webp) |![](/imgs/feishuwebhook5.png) | + +## 2. Import Workflow Configuration + +Copy the configuration below, click the import button in the top-right corner of "Advanced Orchestration", and import it. After importing, paste the webhook URL provided by Lark into the "HTTP Request" module. + +
+Workflow Configuration + +```json +{ + "nodes": [ + { + "nodeId": "userGuide", + "name": "系统配置", + "intro": "可以配置应用的系统参数", + "avatar": "/imgs/workflow/userGuide.png", + "flowNodeType": "userGuide", + "position": { + "x": 303.41163758039283, + "y": -552.297639861266 + }, + "version": "481", + "inputs": [], + "outputs": [] + }, + { + "nodeId": "workflowStartNodeId", + "name": "流程开始", + "intro": "", + "avatar": "/imgs/workflow/userChatInput.svg", + "flowNodeType": "workflowStart", + "position": { + "x": 529.3935295017156, + "y": 197.114018410347 + }, + "version": "481", + "inputs": [ + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "用户问题", + "required": true, + "toolDescription": "用户问题" + } + ], + "outputs": [ + { + "id": "userChatInput", + "key": "userChatInput", + "label": "core.module.input.label.user question", + "valueType": "string", + "type": "static" + } + ] + }, + { + "nodeId": "u6IAOEssxoZT", + "name": "工具调用", + "intro": "通过AI模型自动选择一个或多个功能块进行调用，也可以对插件进行调用。", + "avatar": "/imgs/workflow/tool.svg", + "flowNodeType": "tools", + "showStatus": true, + "position": { + "x": 1003.146243538873, + "y": 48.52327869406625 + }, + "version": "481", + "inputs": [ + { + "key": "model", + "renderTypeList": [ + "settingLLMModel", + "reference" + ], + "label": "core.module.input.label.aiModel", + "valueType": "string", + "llmModelType": "all", + "value": "gpt-3.5-turbo" + }, + { + "key": "temperature", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 0, + "valueType": "number", + "min": 0, + "max": 10, + "step": 1 + }, + { + "key": "maxToken", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 2000, + "valueType": "number", + "min": 100, + "max": 4000, + "step": 50 + }, + { + "key": "systemPrompt", + "renderTypeList": [ + "textarea", + "reference" + ], + "max": 3000, + "valueType": "string", + "label": "core.ai.Prompt", + "description": "core.app.tip.chatNodeSystemPromptTip", + "placeholder": "core.app.tip.chatNodeSystemPromptTip" + }, + { + "key": "history", + "renderTypeList": [ + "numberInput", + "reference" + ], + "valueType": "chatHistory", + "label": "core.module.input.label.chat history", + "description": "最多携带多少轮对话记录", + "required": true, + "min": 0, + "max": 50, + "value": 6 + }, + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "用户问题", + "required": true, + "value": [ + "workflowStartNodeId", + "userChatInput" + ] + } + ], + "outputs": [ + { + "id": "answerText", + "key": "answerText", + "label": "core.module.output.label.Ai response content", + "description": "core.module.output.description.Ai response content", + "valueType": "string", + "type": "static" + } + ] + }, + { + "nodeId": "fvY5hb0K646V", + "name": "工具调用终止", + "intro": "该模块需配置工具调用使用。当该模块被执行时，本次工具调用将会强制结束，并且不再调用AI针对工具调用结果回答问题。", + "avatar": "/imgs/workflow/toolStop.svg", + "flowNodeType": "stopTool", + "position": { + "x": 2367.838362362707, + "y": 732.355988936165 + }, + "version": "481", + "inputs": [], + "outputs": [] + }, + { + "nodeId": "x9rN2a4WnZmt", + "name": "HTTP 请求", + "intro": "向飞书发送一个webhooks通知信息。", + "avatar": "/imgs/workflow/http.png", + "flowNodeType": "httpRequest468", + "showStatus": true, + "position": { + "x": 1623.9214305901633, + "y": 22.777089001645862 + }, + "version": "486", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "core.module.input.description.HTTP Dynamic Input", + "editField": { + "key": true, + "valueType": true + } + }, + { + "valueType": "string", + "renderTypeList": [ + "reference" + ], + "key": "text", + "label": "text", + "toolDescription": "发送的消息", + "required": true, + "canEdit": true, + "editField": { + "key": true, + "description": true + } + }, + { + "key": "system_httpMethod", + "renderTypeList": [ + "custom" + ], + "valueType": "string", + "label": "", + "value": "POST", + "required": true + }, + { + "key": "system_httpReqUrl", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "", + "description": "core.module.input.description.Http Request Url", + "placeholder": "https://api.ai.com/getInventory", + "required": false, + "value": "" + }, + { + "key": "system_httpHeader", + "renderTypeList": [ + "custom" + ], + "valueType": "any", + "value": [], + "label": "", + "description": "core.module.input.description.Http Request Header", + "placeholder": "core.module.input.description.Http Request Header", + "required": false + }, + { + "key": "system_httpParams", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "value": [], + "label": "", + "required": false + }, + { + "key": "system_httpJsonBody", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "value": "{\r\n \"msg_type\": \"text\",\r\n \"content\": {\r\n \"text\": \"{{text}}\"\r\n }\r\n}", + "label": "", + "required": false + } + ], + "outputs": [ + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "editField": { + "key": true, + "valueType": true + } + }, + { + "id": "error", + "key": "error", + "label": "请求错误", + "description": "HTTP请求错误信息，成功时返回空", + "valueType": "object", + "type": "static" + }, + { + "id": "httpRawResponse", + "key": "httpRawResponse", + "label": "原始响应", + "required": true, + "description": "HTTP请求的原始响应。只能接受字符串或JSON类型响应数据。", + "valueType": "any", + "type": "static" + } + ] + }, + { + "nodeId": "aGHGqH2oUupj", + "name": "指定回复", + "intro": "该模块可以直接回复一段指定的内容。常用于引导、提示。非字符串内容传入时，会转成字符串进行输出。", + "avatar": "/imgs/workflow/reply.png", + "flowNodeType": "answerNode", + "position": { + "x": 2350.7077940158674, + "y": 107.32448732713493 + }, + "version": "481", + "inputs": [ + { + "key": "text", + "renderTypeList": [ + "textarea", + "reference" + ], + "valueType": "any", + "required": true, + "label": "core.module.input.label.Response content", + "description": "core.module.input.description.Response content", + "placeholder": "core.module.input.description.Response content", + "value": "嘻嘻，发送成功" + } + ], + "outputs": [] + } + ], + "edges": [ + { + "source": "workflowStartNodeId", + "target": "u6IAOEssxoZT", + "sourceHandle": "workflowStartNodeId-source-right", + "targetHandle": "u6IAOEssxoZT-target-left" + }, + { + "source": "u6IAOEssxoZT", + "target": "x9rN2a4WnZmt", + "sourceHandle": "selectedTools", + "targetHandle": "selectedTools" + }, + { + "source": "x9rN2a4WnZmt", + "target": "fvY5hb0K646V", + "sourceHandle": "x9rN2a4WnZmt-source-right", + "targetHandle": "fvY5hb0K646V-target-left" + }, + { + "source": "x9rN2a4WnZmt", + "target": "aGHGqH2oUupj", + "sourceHandle": "x9rN2a4WnZmt-source-right", + "targetHandle": "aGHGqH2oUupj-target-left" + } + ], + "chatConfig": { + "variables": [ + { + "id": "txq1ca", + "key": "test", + "label": "测试", + "type": "custom", + "required": true, + "maxLen": 50, + "enums": [ + { + "value": "" + } + ] + } + ], + "questionGuide": false, + "scheduledTriggerConfig": { + "cronString": "", + "timezone": "Asia/Shanghai", + "defaultPrompt": "" + }, + "_id": "66715d4bf577287d39e35ecf" + } +} +``` + +
+ + +## 3. How It Works + +1. Attach an HTTP module to the Tool Call with the description: "Call Lark webhook to send a notification." +2. In the HTTP module's input parameters, fill in the Lark bot's webhook URL and the notification content. +3. Connect the HTTP module's output to a Tool Call Terminator to force-end the tool call. Without this, the result would be sent back to the model, which would generate another response — wasting tokens. +4. Also connect the HTTP module's output to a Specified Reply to directly return a success message, replacing the AI's response. diff --git a/document/content/docs/use-cases/app-cases/fixingEvidence.en.mdx b/document/content/docs/use-cases/app-cases/fixingEvidence.en.mdx new file mode 100644 index 0000000000..63d8de6266 --- /dev/null +++ b/document/content/docs/use-cases/app-cases/fixingEvidence.en.mdx @@ -0,0 +1,428 @@ +--- +title: Add Fixed Opening and Closing Content +description: Use Specified Reply modules to add fixed opening and closing messages to responses +--- + +![](/imgs/demo-fix-evidence1.jpg) + +![](/imgs/demo-fix-evidence2.jpg) + + +As shown above, you can use Specified Reply modules to add fixed opening and closing content to your responses. + +## Module Configuration + +Copy the configuration below, click the import button in the top-right corner of "Advanced Orchestration", and paste it in. + +
+Workflow Configuration + +```json +{ + "nodes": [ + { + "nodeId": "7z5g5h", + "name": "流程开始", + "intro": "", + "avatar": "/imgs/workflow/userChatInput.svg", + "flowNodeType": "workflowStart", + "position": { + "x": -269.50851681351924, + "y": 1657.6123698022448 + }, + "inputs": [ + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "问题输入", + "required": true, + "toolDescription": "用户问题", + "type": "systemInput", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0, + "value": [ + "7z5g5h", + "userChatInput" + ] + } + ], + "outputs": [ + { + "id": "userChatInput", + "type": "static", + "key": "userChatInput", + "valueType": "string", + "label": "core.module.input.label.user question" + } + ] + }, + { + "nodeId": "nlfwkc", + "name": "AI 对话", + "intro": "AI 大模型对话", + "avatar": "/imgs/workflow/AI.png", + "flowNodeType": "chatNode", + "showStatus": true, + "position": { + "x": 907.2058332478431, + "y": 1348.9992737142143 + }, + "inputs": [ + { + "key": "model", + "renderTypeList": [ + "settingLLMModel", + "reference" + ], + "label": "core.module.input.label.aiModel", + "valueType": "string", + "type": "selectLLMModel", + "required": true, + "showTargetInApp": false, + "showTargetInPlugin": false, + "value": "gpt-3.5-turbo", + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "temperature", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 0, + "valueType": "number", + "min": 0, + "max": 10, + "step": 1, + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "maxToken", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 2000, + "valueType": "number", + "min": 100, + "max": 4000, + "step": 50, + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "isResponseAnswerText", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": true, + "valueType": "boolean", + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "quoteTemplate", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "string", + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "quotePrompt", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "string", + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "systemPrompt", + "renderTypeList": [ + "textarea", + "reference" + ], + "max": 300, + "valueType": "string", + "label": "core.ai.Prompt", + "description": "core.app.tip.chatNodeSystemPromptTip", + "placeholder": "core.app.tip.chatNodeSystemPromptTip", + "type": "textarea", + "showTargetInApp": true, + "showTargetInPlugin": true, + "value": "", + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "history", + "renderTypeList": [ + "numberInput", + "reference" + ], + "valueType": "chatHistory", + "label": "core.module.input.label.chat history", + "required": true, + "min": 0, + "max": 30, + "value": 6, + "type": "numberInput", + "showTargetInApp": true, + "showTargetInPlugin": true, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "问题输入", + "required": true, + "toolDescription": "用户问题", + "type": "custom", + "showTargetInApp": true, + "showTargetInPlugin": true, + "connected": true, + "selectedTypeIndex": 0, + "value": [ + "7z5g5h", + "userChatInput" + ] + }, + { + "key": "quoteQA", + "renderTypeList": [ + "settingDatasetQuotePrompt" + ], + "label": "", + "debugLabel": "知识库引用", + "description": "core.module.Dataset quote.Input description", + "valueType": "datasetQuote", + "type": "target", + "showTargetInApp": true, + "showTargetInPlugin": true, + "connected": true, + "selectedTypeIndex": 0, + "value": [ + "fljhzy", + "quoteQA" + ] + } + ], + "outputs": [ + { + "id": "answerText", + "type": "static", + "key": "answerText", + "valueType": "string", + "label": "core.module.output.label.Ai response content", + "description": "core.module.output.description.Ai response content" + }, + { + "id": "history", + "type": "static", + "key": "history", + "valueType": "chatHistory", + "label": "core.module.output.label.New context", + "description": "core.module.output.description.New context" + } + ] + }, + { + "nodeId": "q9equb", + "name": "core.module.template.App system setting", + "intro": "可以配置应用的系统参数。", + "avatar": "/imgs/workflow/userGuide.png", + "flowNodeType": "userGuide", + "position": { + "x": -275.92529567956024, + "y": 1094.1001488133452 + }, + "inputs": [ + { + "key": "welcomeText", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "core.app.Welcome Text", + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "value": "你好，我是电影《星际穿越》 AI 助手，有什么可以帮助你的？\\n[导演是谁]\\n[剧情介绍]\\n[票房分析]", + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "variables", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "core.module.Variable", + "value": [], + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "questionGuide", + "valueType": "boolean", + "renderTypeList": [ + "hidden" + ], + "label": "", + "type": "switch", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "tts", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "whisper", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "" + }, + { + "key": "scheduleTrigger", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": null + } + ], + "outputs": [] + }, + { + "nodeId": "tc90wz", + "name": "指定回复", + "intro": "该模块可以直接回复一段指定的内容。常用于引导、提示。非字符串内容传入时，会转成字符串进行输出。", + "avatar": "/imgs/workflow/reply.png", + "flowNodeType": "answerNode", + "position": { + "x": 159.49274056478237, + "y": 1621.4635230667668 + }, + "inputs": [ + { + "key": "text", + "renderTypeList": [ + "textarea", + "reference" + ], + "valueType": "any", + "label": "core.module.input.label.Response content", + "description": "core.module.input.description.Response content", + "placeholder": "core.module.input.description.Response content", + "type": "textarea", + "showTargetInApp": true, + "showTargetInPlugin": true, + "value": "这是开头\\\\n", + "connected": false, + "selectedTypeIndex": 0 + } + ], + "outputs": [] + }, + { + "nodeId": "U5T3dMVY4wj7", + "name": "指定回复", + "intro": "该模块可以直接回复一段指定的内容。常用于引导、提示。非字符串内容传入时，会转成字符串进行输出。", + "avatar": "/imgs/workflow/reply.png", + "flowNodeType": "answerNode", + "position": { + "x": 1467.0625486167608, + "y": 1597.346243737531 + }, + "inputs": [ + { + "key": "text", + "renderTypeList": [ + "textarea", + "reference" + ], + "valueType": "string", + "label": "core.module.input.label.Response content", + "description": "core.module.input.description.Response content", + "placeholder": "core.module.input.description.Response content", + "value": "这是结尾" + } + ], + "outputs": [] + } + ], + "edges": [ + { + "source": "7z5g5h", + "target": "tc90wz", + "sourceHandle": "7z5g5h-source-right", + "targetHandle": "tc90wz-target-left" + }, + { + "source": "tc90wz", + "target": "nlfwkc", + "sourceHandle": "tc90wz-source-right", + "targetHandle": "nlfwkc-target-left" + }, + { + "source": "nlfwkc", + "target": "U5T3dMVY4wj7", + "sourceHandle": "nlfwkc-source-right", + "targetHandle": "U5T3dMVY4wj7-target-left" + } + ] +} +``` + +
diff --git a/document/content/docs/use-cases/app-cases/google_search.en.mdx b/document/content/docs/use-cases/app-cases/google_search.en.mdx new file mode 100644 index 0000000000..135931a3a8 --- /dev/null +++ b/document/content/docs/use-cases/app-cases/google_search.en.mdx @@ -0,0 +1,445 @@ +--- +title: Google Search Integration +description: Integrate FastGPT with Google Search +--- + +| | | +| --------------------- | --------------------- | +| Tool Call Mode ![](/imgs/google_search_3.webp) | Tool Call Mode ![](/imgs/google_search_4.webp) | +| Non-Tool Call Mode ![](/imgs/google_search_1.webp) | Non-Tool Call Mode ![](/imgs/google_search_2.webp) | + + +As shown above, using the「HTTP Request」module, you can connect an external search engine as reference material for AI responses. This example uses the Google Search API. Note: This article mainly introduces the「HTTP Request」module. The actual search effectiveness depends on prompts and the search engine, especially the【search engine】—simple search engines cannot retrieve detailed content, which may require more debugging. + +## Register Google Search API + +[Refer to this article](https://zhuanlan.zhihu.com/p/174666017), which allows 100 free uses per day. + +## Write a Google Search Interface + +Use [Laf](https://laf.dev/) to quickly implement an interface—write and publish instantly without deployment. Make sure to enable POST request method. + +
+Laf Google Search Demo + +```typescript +import cloud from '@lafjs/cloud' + +const googleSearchKey = "xxx" +const googleCxId = "3740cxxx" +const baseurl = "https://www.googleapis.com/customsearch/v1" + +type RequestType = { + searchKey: string +} + +export default async function (ctx: FunctionContext) { + const { searchKey } = ctx.body as RequestType + console.log(ctx.body) + if (!searchKey) { + return { + prompt: "" + } + } + + try { + const { data } = await cloud.fetch.get(baseurl, { + params: { + q: searchKey, + cx: googleCxId, + key: googleSearchKey, + c2coff: 1, + start: 1, + end: 20, + dateRestrict: 'm[1]', + } + }) + const result = data.items.map((item) => item.snippet).join('\n'); + + return { prompt: result } + } catch (err) { + console.log(err) + ctx.response.status(500) + return { + message: "Error" + } + } +} +``` + +
+ +## Workflow Design - Tool Call Mode + +Using the tool module, no extra operations are needed—the model decides whether to call Google Search and generates search terms automatically. + +Copy the configuration below, enter「Advanced Workflow」, select「Import Configuration」from the "..." in the top right corner, then modify the「HTTP Request」module - Request URL value after importing. + +
+Workflow Configuration + +```json +{ + "nodes": [ + { + "nodeId": "userGuide", + "name": "System Configuration", + "intro": "Configure application system parameters", + "avatar": "/imgs/workflow/userGuide.png", + "flowNodeType": "userGuide", + "position": { + "x": 262.2732338817093, + "y": -476.00241136598146 + }, + "inputs": [ + { + "key": "welcomeText", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "core.app.Welcome Text", + "value": "" + }, + { + "key": "variables", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "core.app.Chat Variable", + "value": [] + }, + { + "key": "questionGuide", + "valueType": "boolean", + "renderTypeList": [ + "hidden" + ], + "label": "core.app.Question Guide", + "value": false + }, + { + "key": "tts", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": { + "type": "web" + } + }, + { + "key": "whisper", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": { + "open": false, + "autoSend": false, + "autoTTSResponse": false + } + }, + { + "key": "scheduleTrigger", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": null + } + ], + "outputs": [] + }, + { + "nodeId": "448745", + "name": "Workflow Start", + "intro": "", + "avatar": "/imgs/workflow/userChatInput.svg", + "flowNodeType": "workflowStart", + "position": { + "x": 295.8944548701009, + "y": 110.81336038514848 + }, + "inputs": [ + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "User Question", + "required": true, + "toolDescription": "User Question" + } + ], + "outputs": [ + { + "id": "userChatInput", + "key": "userChatInput", + "label": "core.module.input.label.user question", + "valueType": "string", + "type": "static" + } + ] + }, + { + "nodeId": "NOgbnBzUwDgT", + "name": "Tool Call", + "intro": "Automatically select one or more function blocks to call through AI model, can also call plugins.", + "avatar": "/imgs/workflow/tool.svg", + "flowNodeType": "tools", + "showStatus": true, + "position": { + "x": 1028.8358722416106, + "y": -500.8755882990822 + }, + "inputs": [ + { + "key": "model", + "renderTypeList": [ + "settingLLMModel", + "reference" + ], + "label": "core.module.input.label.aiModel", + "valueType": "string", + "llmModelType": "all", + "value": "FastAI-plus" + }, + { + "key": "temperature", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 0, + "valueType": "number", + "min": 0, + "max": 10, + "step": 1 + }, + { + "key": "maxToken", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 2000, + "valueType": "number", + "min": 100, + "max": 4000, + "step": 50 + }, + { + "key": "systemPrompt", + "renderTypeList": [ + "textarea", + "reference" + ], + "max": 3000, + "valueType": "string", + "label": "core.ai.Prompt", + "description": "core.app.tip.chatNodeSystemPromptTip", + "placeholder": "core.app.tip.chatNodeSystemPromptTip", + "value": "You are a Google search bot. Generate search terms based on the current question and conversation history. You need to determine whether real-time web queries are needed:\n- If a query is needed, generate search terms.\n- If no query is needed, don't return the field." + }, + { + "key": "history", + "renderTypeList": [ + "numberInput", + "reference" + ], + "valueType": "chatHistory", + "label": "core.module.input.label.chat history", + "required": true, + "min": 0, + "max": 30, + "value": 6 + }, + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "User Question", + "required": true, + "value": [ + "448745", + "userChatInput" + ] + } + ], + "outputs": [] + }, + { + "nodeId": "GMELVPxHfpg5", + "name": "HTTP Request", + "intro": "Call Google Search to query relevant content", + "avatar": "/imgs/workflow/http.png", + "flowNodeType": "httpRequest468", + "showStatus": true, + "position": { + "x": 1013.2159795348916, + "y": 210.8685573380423 + }, + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "core.module.input.description.HTTP Dynamic Input", + "editField": { + "key": true, + "valueType": true + } + }, + { + "valueType": "string", + "renderTypeList": [ + "reference" + ], + "key": "query", + "label": "query", + "toolDescription": "Google search query term", + "required": true, + "canEdit": true, + "editField": { + "key": true, + "description": true + } + }, + { + "key": "system_httpMethod", + "renderTypeList": [ + "custom" + ], + "valueType": "string", + "label": "", + "value": "POST", + "required": true + }, + { + "key": "system_httpReqUrl", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "", + "description": "core.module.input.description.Http Request Url", + "placeholder": "https://api.ai.com/getInventory", + "required": false, + "value": "https://xxxxxx.laf.dev/google_search" + }, + { + "key": "system_httpHeader", + "renderTypeList": [ + "custom" + ], + "valueType": "any", + "value": [], + "label": "", + "description": "core.module.input.description.Http Request Header", + "placeholder": "core.module.input.description.Http Request Header", + "required": false + }, + { + "key": "system_httpParams", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "value": [], + "label": "", + "required": false + }, + { + "key": "system_httpJsonBody", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "value": "{\n \"searchKey\": \"{{query}}\"\n}", + "label": "", + "required": false + } + ], + "outputs": [ + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "editField": { + "key": true, + "valueType": true + } + }, + { + "id": "httpRawResponse", + "key": "httpRawResponse", + "label": "Raw Response", + "description": "Raw response from HTTP request. Only accepts string or JSON type response data.", + "valueType": "any", + "type": "static" + }, + { + "id": "M5YmxaYe8em1", + "type": "dynamic", + "key": "prompt", + "valueType": "string", + "label": "prompt" + } + ] + } + ], + "edges": [ + { + "source": "448745", + "target": "NOgbnBzUwDgT", + "sourceHandle": "448745-source-right", + "targetHandle": "NOgbnBzUwDgT-target-left" + }, + { + "source": "NOgbnBzUwDgT", + "target": "GMELVPxHfpg5", + "sourceHandle": "selectedTools", + "targetHandle": "selectedTools" + } + ] +} +``` + +
+ +## Workflow Design - Non-Tool Call Mode + +Copy the configuration below, enter「Advanced Workflow」, select「Import Configuration」from the "..." in the top right corner, then modify the「HTTP Request」module - Request URL value after importing. + +
+Workflow Configuration + +```json +[Configuration JSON omitted for brevity - same structure as Chinese version with translated labels] +``` + +
+ + +### Workflow Explanation + +1. Use the【Content Extraction】module to extract search keywords from the user's question. +2. Pass the search keywords to the【HTTP Request】module to execute Google Search. +3. Use the【Text Processing】module to combine search results and the question, generating a question suitable for the model to answer. +4. Send the new question to the【AI Chat】module to answer based on search results. diff --git a/document/content/docs/use-cases/app-cases/lab_appointment.en.mdx b/document/content/docs/use-cases/app-cases/lab_appointment.en.mdx new file mode 100644 index 0000000000..27cfbded6f --- /dev/null +++ b/document/content/docs/use-cases/app-cases/lab_appointment.en.mdx @@ -0,0 +1,853 @@ +--- +title: Lab Appointment System +description: Demonstrates advanced workflow capabilities for database operations +--- + +import { Alert } from '@/components/docs/Alert'; + +| | | +| --------------------- | --------------------- | +| ![](/imgs/demo-appointment1.webp) | ![](/imgs/demo-appointment2.webp) | +| ![](/imgs/demo-appointment3.webp) | ![](/imgs/demo-appointment4.webp) | + + + +This example demonstrates using tool calls to automatically choose between searching the knowledge base for lab information or calling HTTP modules to perform database CRUD operations. + +Using a lab appointment system as an example, users can book, cancel, modify, and query appointments through a conversational interface. + +## 1. Using Global Variables + +Design a global variable for users to input their name, simulating user identity. In production, you'd typically use embedded tokens to identify users. + +## 2. Tool Calling + +![](/imgs/demo-appointment5.png) + +In the background knowledge, guide the model to call tools for different operations. + + +**Tips:** Add appropriate context here so the model can make decisions based on conversation history. + + +## 3. HTTP Module + +![](/imgs/demo-appointment6.jpg) + +The HTTP module requires 3 tool parameters: + +- Appointment action: Can be get, put, post, or delete, corresponding to query, modify, create, and delete operations. You could also create 4 separate HTTP modules to handle each action. +- labname: Lab name. Optional, since it's not needed for queries and deletions. +- time: Appointment time. + + +# Summary + +1. The tool calling module is incredibly powerful and can largely replace question classification and content extraction. +2. By dynamically calling different tools through the tool module, you can decouple complex business logic. + + +# Attachments + +## Workflow Configuration + +Copy and import directly into FastGPT. + +
+Workflow Configuration + +```json +{ + "nodes": [ + { + "nodeId": "userChatInput", + "name": "流程开始", + "intro": "当用户发送一个内容后,流程将会从这个模块开始执行。", + "avatar": "/imgs/workflow/userChatInput.svg", + "flowNodeType": "workflowStart", + "position": { + "x": 309.7143912167367, + "y": 1501.2761754220846 + }, + "inputs": [ + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "问题输入", + "required": true, + "toolDescription": "用户问题", + "type": "systemInput", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0, + "value": [ + "userChatInput", + "userChatInput" + ] + } + ], + "outputs": [ + { + "id": "userChatInput", + "type": "static", + "key": "userChatInput", + "valueType": "string", + "label": "core.module.input.label.user question" + } + ] + }, + { + "nodeId": "eg5upi", + "name": "指定回复", + "intro": "该模块可以直接回复一段指定的内容。常用于引导、提示。非字符串内容传入时,会转成字符串进行输出。", + "avatar": "/imgs/workflow/reply.png", + "flowNodeType": "answerNode", + "position": { + "x": 1962.729630445213, + "y": 2295.9791334948304 + }, + "inputs": [ + { + "key": "text", + "renderTypeList": [ + "textarea", + "reference" + ], + "valueType": "any", + "label": "core.module.input.label.Response content", + "description": "core.module.input.description.Response content", + "placeholder": "core.module.input.description.Response content", + "type": "textarea", + "showTargetInApp": true, + "showTargetInPlugin": true, + "connected": true, + "selectedTypeIndex": 1, + "value": [ + "40clf3", + "result" + ] + } + ], + "outputs": [] + }, + { + "nodeId": "kge59i", + "name": "用户引导", + "intro": "可以配置应用的系统参数。", + "avatar": "/imgs/workflow/userGuide.png", + "flowNodeType": "userGuide", + "position": { + "x": -327.218389965887, + "y": 1504.8056414948464 + }, + "inputs": [ + { + "key": "welcomeText", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "core.app.Welcome Text", + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "value": "你好,我是实验室助手,请问有什么可以帮助你的么?如需预约或修改预约实验室,请提供姓名、时间和实验室名称。\\n[实验室介绍]\\n[开放时间]\\n[预约]", + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "variables", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "core.module.Variable", + "value": [ + { + "id": "gt9b23", + "key": "name", + "label": "name", + "type": "input", + "required": true, + "maxLen": 50, + "enums": [ + { + "value": "" + } + ] + } + ], + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "questionGuide", + "valueType": "boolean", + "renderTypeList": [ + "hidden" + ], + "label": "", + "type": "switch", + "showTargetInApp": false, + "showTargetInPlugin": false, + "value": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "tts", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "value": { + "type": "model", + "model": "tts-1", + "voice": "alloy" + }, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "whisper", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "scheduleTrigger", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": null + } + ], + "outputs": [] + }, + { + "nodeId": "40clf3", + "name": "HTTP请求", + "intro": "可以发出一个 HTTP 请求,实现更为复杂的操作(联网搜索、数据库查询等)", + "avatar": "/imgs/workflow/http.png", + "flowNodeType": "httpRequest468", + "showStatus": true, + "position": { + "x": 1118.6532653446993, + "y": 1955.886106913907 + }, + "inputs": [ + { + "key": "system_httpMethod", + "renderTypeList": [ + "custom" + ], + "valueType": "string", + "label": "", + "value": "POST", + "required": true, + "type": "custom", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "valueType": "string", + "renderTypeList": [ + "reference" + ], + "key": "action", + "label": "action", + "toolDescription": "预约行为,一共四种:\\nget - 查询预约情况\\nput - 更新预约\\npost - 新增预约\\ndelete - 删除预约", + "required": true, + "canEdit": true, + "editField": { + "key": true, + "description": true + } + }, + { + "valueType": "string", + "renderTypeList": [ + "reference" + ], + "key": "labname", + "label": "labname", + "toolDescription": "实验室名称", + "required": false, + "canEdit": true, + "editField": { + "key": true, + "description": true + } + }, + { + "valueType": "string", + "renderTypeList": [ + "reference" + ], + "key": "time", + "label": "time", + "toolDescription": "预约时间,按 YYYY/MM/DD HH:mm 格式返回", + "required": false, + "canEdit": true, + "editField": { + "key": true, + "description": true + } + }, + { + "key": "system_httpReqUrl", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "", + "description": "core.module.input.description.Http Request Url", + "placeholder": "https://api.ai.com/getInventory", + "required": false, + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "value": "https://d8dns0.laf.dev/appointment-lab", + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "system_httpHeader", + "renderTypeList": [ + "custom" + ], + "valueType": "any", + "value": [], + "label": "", + "description": "core.module.input.description.Http Request Header", + "placeholder": "core.module.input.description.Http Request Header", + "required": false, + "type": "custom", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "system_httpParams", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "value": [], + "label": "", + "required": false, + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "system_httpJsonBody", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "value": "{\\r\\n \\\"name\\\": \\\"{{name}}\\\",\\r\\n \\\"time\\\": \\\"{{time}}\\\",\\r\\n \\\"labname\\\": \\\"{{labname}}\\\",\\r\\n \\\"action\\\": \\\"{{action}}\\\"\\r\\n}", + "label": "", + "required": false, + "type": "hidden", + "showTargetInApp": false, + "showTargetInPlugin": false, + "connected": false, + "selectedTypeIndex": 0 + }, + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "core.module.input.description.HTTP Dynamic Input", + "editField": { + "key": true, + "valueType": true + } + } + ], + "outputs": [ + { + "id": "system_addOutputParam", + "type": "dynamic", + "key": "system_addOutputParam", + "valueType": "dynamic", + "label": "", + "editField": { + "key": true, + "valueType": true + } + }, + { + "id": "result", + "type": "static", + "key": "result", + "valueType": "string", + "label": "result", + "description": "result", + "canEdit": true, + "editField": { + "key": true, + "name": true, + "description": true, + "dataType": true + } + }, + { + "id": "httpRawResponse", + "type": "static", + "key": "httpRawResponse", + "valueType": "any", + "label": "原始响应", + "description": "HTTP请求的原始响应。只能接受字符串或JSON类型响应数据。" + } + ] + }, + { + "nodeId": "fYxwWym8flYL", + "name": "工具调用", + "intro": "通过AI模型自动选择一个或多个功能块进行调用,也可以对插件进行调用。", + "avatar": "/imgs/workflow/tool.svg", + "flowNodeType": "tools", + "showStatus": true, + "position": { + "x": 933.9342354248961, + "y": 1229.3563445150553 + }, + "inputs": [ + { + "key": "model", + "renderTypeList": [ + "settingLLMModel", + "reference" + ], + "label": "core.module.input.label.aiModel", + "valueType": "string", + "llmModelType": "all", + "value": "gpt-3.5-turbo" + }, + { + "key": "temperature", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 0, + "valueType": "number", + "min": 0, + "max": 10, + "step": 1 + }, + { + "key": "maxToken", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 2000, + "valueType": "number", + "min": 100, + "max": 4000, + "step": 50 + }, + { + "key": "systemPrompt", + "renderTypeList": [ + "textarea", + "reference" + ], + "max": 3000, + "valueType": "string", + "label": "core.ai.Prompt", + "description": "core.app.tip.chatNodeSystemPromptTip", + "placeholder": "core.app.tip.chatNodeSystemPromptTip", + "value": "当前时间为: {{cTime}}\\n你是实验室助手,用户可能会询问实验室相关介绍或预约实验室。\\n请选择合适的工具去帮助他们。" + }, + { + "key": "history", + "renderTypeList": [ + "numberInput", + "reference" + ], + "valueType": "chatHistory", + "label": "core.module.input.label.chat history", + "required": true, + "min": 0, + "max": 30, + "value": 6 + }, + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "用户问题", + "required": true, + "value": [ + "userChatInput", + "userChatInput" + ] + } + ], + "outputs": [] + }, + { + "nodeId": "JSSQtDgwmmbE", + "name": "知识库搜索", + "intro": "调用"语义检索"和"全文检索"能力,从"知识库"中查找实验室介绍和使用规则等信息。", + "avatar": "/imgs/workflow/db.png", + "flowNodeType": "datasetSearchNode", + "showStatus": true, + "position": { + "x": 447.0795498711184, + "y": 1971.5311041711186 + }, + "inputs": [ + { + "key": "datasets", + "renderTypeList": [ + "selectDataset", + "reference" + ], + "label": "core.module.input.label.Select dataset", + "value": [], + "valueType": "selectDataset", + "list": [], + "required": true + }, + { + "key": "similarity", + "renderTypeList": [ + "selectDatasetParamsModal" + ], + "label": "", + "value": 0.4, + "valueType": "number" + }, + { + "key": "limit", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 1500, + "valueType": "number" + }, + { + "key": "searchMode", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "string", + "value": "embedding" + }, + { + "key": "usingReRank", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "boolean", + "value": false + }, + { + "key": "datasetSearchUsingExtensionQuery", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "boolean", + "value": false + }, + { + "key": "datasetSearchExtensionModel", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "string", + "value": "gpt-3.5-turbo" + }, + { + "key": "datasetSearchExtensionBg", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "string", + "value": "" + }, + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "用户问题", + "required": true, + "toolDescription": "需要检索的内容" + } + ], + "outputs": [ + { + "id": "quoteQA", + "key": "quoteQA", + "label": "core.module.Dataset quote.label", + "description": "特殊数组格式,搜索结果为空时,返回空数组。", + "type": "static", + "valueType": "datasetQuote" + } + ] + }, + { + "nodeId": "IdntVQiTopHT", + "name": "工具调用终止", + "intro": "该模块需配置工具调用使用。当该模块被执行时,本次工具调用将会强制结束,并且不再调用AI针对工具调用结果回答问题。", + "avatar": "/imgs/workflow/toolStop.svg", + "flowNodeType": "stopTool", + "position": { + "x": 1969.73331750207, + "y": 2650.0258908119413 + }, + "inputs": [], + "outputs": [] + } + ], + "edges": [ + { + "source": "40clf3", + "target": "eg5upi", + "sourceHandle": "40clf3-source-right", + "targetHandle": "eg5upi-target-left" + }, + { + "source": "userChatInput", + "target": "fYxwWym8flYL", + "sourceHandle": "userChatInput-source-right", + "targetHandle": "fYxwWym8flYL-target-left" + }, + { + "source": "fYxwWym8flYL", + "target": "40clf3", + "sourceHandle": "selectedTools", + "targetHandle": "selectedTools" + }, + { + "source": "fYxwWym8flYL", + "target": "JSSQtDgwmmbE", + "sourceHandle": "selectedTools", + "targetHandle": "selectedTools" + }, + { + "source": "40clf3", + "target": "IdntVQiTopHT", + "sourceHandle": "40clf3-source-right", + "targetHandle": "IdntVQiTopHT-target-left" + } + ] +} +``` + +
+ +## Laf Cloud Function Code + +You can quickly build HTTP endpoints in [Laf](https://laf.dev/). +
+Function Code + + +```ts +import cloud from '@lafjs/cloud' +const db = cloud.database() + +type RequestType = { + name: string; + time?: string; + labname?: string; + action: 'post' | 'delete' | 'put' | 'get' +} + +export default async function (ctx: FunctionContext) { + try { + const { action,...body } = ctx.body as RequestType + + if (action === 'get') { + return await getRecord(ctx.body) + } + if (action === 'post') { + return await createRecord(ctx.body) + } + if (action === 'put') { + return await putRecord(ctx.body) + } + if (action === 'delete') { + return await removeRecord(ctx.body) + } + + + return { + result: "异常" + } + } catch (err) { + return { + result: "异常" + } + } +} + +async function putRecord({ name, time, labname }: RequestType) { + const missData = [] + if (!name) missData.push("你的姓名") + + if (missData.length > 0) { + return { + result: `请提供: ${missData.join("、")}` + } + } + + const { data: record } = await db.collection("LabAppointment").where({ + name, status: "unStart" + }).getOne() + + if (!record) { + return { + result: `${name} 还没有预约记录` + } + } + + const updateWhere = { + name, + time: time || record.time, + labname: labname || record.labname + } + + await db.collection("LabAppointment").where({ + name, status: "unStart" + }).update(updateWhere) + + return { + result: `修改预约成功。 + 姓名:${name}· + 时间: ${updateWhere.time} + 实验室名: ${updateWhere.labname} + ` } +} + + +async function getRecord({ name }: RequestType) { + if (!name) { + return { + result: "请提供你的姓名" + } + } + const { data } = await db.collection('LabAppointment').where({ name, status: "unStart" }).getOne() + + if (!data) { + return { + result: `${name} 没有预约中的记录` + } + } + return { + result: `${name} 有一条预约记录: +姓名:${data.name} +时间: ${data.time} +实验室名: ${data.labname} + ` + } +} + +async function removeRecord({ name }: RequestType) { + if (!name) { + return { + result: "请提供你的姓名" + } + } + const { deleted } = await db.collection('LabAppointment').where({ name, status: "unStart" }).remove() + + if (deleted > 0) { + return { + result: `取消预约记录成功: ${name}` + } + } + return { + result: ` ${name} 没有预约中的记录` + } +} + +async function createRecord({ name, time, labname }: RequestType) { + const missData = [] + if (!name) missData.push("你的姓名") + if (!time) missData.push("需要预约的时间") + if (!labname) missData.push("实验室名名称") + + if (missData.length > 0) { + return { + result: `请提供: ${missData.join("、")}` + } + } + + const { data: record } = await db.collection("LabAppointment").where({ + name, status: "unStart" + }).getOne() + + if (record) { + return { + result: `您已经有一个预约记录了: +姓名:${record.name} +时间: ${record.time} +实验室名: ${record.labname} + +每人仅能同时预约一个实验室名。 + ` + } + } + + await db.collection("LabAppointment").add({ + name, time, labname, status: "unStart" + }) + + return { + result: `预约成功。 + 姓名:${name} + 时间: ${time} + 实验室名: ${labname} + ` } +} +``` + +
diff --git a/document/content/docs/use-cases/app-cases/meta.en.json b/document/content/docs/use-cases/app-cases/meta.en.json new file mode 100644 index 0000000000..0191647dff --- /dev/null +++ b/document/content/docs/use-cases/app-cases/meta.en.json @@ -0,0 +1,15 @@ +{ + "title": "Application Building Cases", + "description": "FastGPT application scenarios and feature implementation building cases", + "pages": [ + "submit_application_template", + "translate-subtitle-using-gpt", + "multi_turn_translation_bot", + "english_essay_correction_bot", + "fixingEvidence", + "lab_appointment", + "dalle3", + "google_search", + "feishu_webhook" + ] +} diff --git a/document/content/docs/use-cases/app-cases/multi_turn_translation_bot.en.mdx b/document/content/docs/use-cases/app-cases/multi_turn_translation_bot.en.mdx new file mode 100644 index 0000000000..b1cb3c69f2 --- /dev/null +++ b/document/content/docs/use-cases/app-cases/multi_turn_translation_bot.en.mdx @@ -0,0 +1,312 @@ +--- +title: Multi-turn Translation Bot +description: How to use FastGPT to build a multi-turn translation bot with continuous conversation translation functionality +--- + +Professor Andrew Ng proposed a reflective translation workflow for large language models (LLM)—[GitHub - andrewyng/translation-agent](https://github.com/andrewyng/translation-agent). The workflow is as follows: + +1. Prompt an LLM to translate text from `source_language` to `target_language`; +2. Have the LLM reflect on the translation and provide constructive improvement suggestions; +3. Use these suggestions to improve the translation. + +This translation process is a relatively new approach that uses LLM self-reflection to achieve better translation results. + +The project demonstrates how to chunk long texts and process each chunk with reflective translation, breaking through LLM token limits to achieve efficient, high-quality translation of long texts. + +The project also achieves more precise translation by specifying regions (e.g., American English vs. British English) and proposes optimizations like creating glossaries for terms the LLM hasn't trained on, further improving translation accuracy. + +All of this can be easily implemented through Fastgpt workflows. This article will guide you step-by-step on how to replicate Professor Andrew Ng's translation-agent. + +# Single Text Block Reflective Translation + +Let's start simple—translating a single text block that doesn't exceed LLM token limits. + +## Initial Translation + +First, have the LLM perform an initial translation of the source text block (translation prompts are available in the source project). + +![](/imgs/translate1.png) + +Use the `Text Concatenation` module to reference three parameters: source language, target language, and source text. Generate a prompt and pass it to the LLM for the first translation version. + +## Reflection + +Then have the LLM provide modification suggestions for the initial translation—this is called reflection. + +![](/imgs/translate2.png) + +The prompt now receives 5 parameters: source text, initial translation, source language, target language, and regional constraints. The LLM will provide numerous modification suggestions to prepare for translation improvement. + +## Improved Translation + +![](/imgs/translate3.png) + +After generating the initial translation and reflection, input both into a third LLM translation to get a high-quality translation result. + +The complete workflow is as follows: + +![](/imgs/translate4.png) + +## Results + +Considering future reuse of this reflective translation, I created a plugin. Below, I directly call this plugin to use reflective translation. Results: + +Randomly selected a Harry Potter passage: + +![](/imgs/translate5.png) + +![](/imgs/translate61.png) + +The reflective translation shows significant improvement. The reflection output: + +![](/imgs/translate7.png) + +# Long Text Reflective Translation + +After mastering short text block reflective translation, we can easily implement long text (multiple text blocks) reflective translation through chunking and looping. + +The overall logic: First, check the token count of the input text. If it doesn't exceed the token limit, directly call single text block reflective translation. If it exceeds the limit, split it into reasonable sizes and process each with reflective translation. + +## Calculate Tokens + +![](/imgs/translate8.png) + +First, I used the Laf function module to calculate tokens for the input text. + +Laf functions are simple to use—just create an application in laf, install the tiktoken dependency, and import this code: + +```typescript +const { Tiktoken } = require("tiktoken/lite"); +const cl100k_base = require("tiktoken/encoders/cl100k_base.json"); + +interface IRequestBody { + str: string +} + +interface RequestProps extends IRequestBody { + systemParams: { + appId: string, + variables: string, + histories: string, + cTime: string, + chatId: string, + responseChatItemId: string + } +} + +interface IResponse { + message: string; + tokens: number; +} + +export default async function (ctx: FunctionContext): Promise { + const { str = "" }: RequestProps = ctx.body + + const encoding = new Tiktoken( + cl100k_base.bpe_ranks, + cl100k_base.special_tokens, + cl100k_base.pat_str + ); + const tokens = encoding.encode(str); + encoding.free(); + + return { + message: 'ok', + tokens: tokens.length + }; +} +``` + +Back in Fastgpt, click "Sync Parameters", connect the source text, and you can calculate token count. + +## Calculate Single Text Block Size + +![](/imgs/translate9.png) + +Since no third-party packages are involved—just data processing—use the Code Execution module directly: + +```typescript +function main({tokenCount, tokenLimit}){ + const numChunks = Math.ceil(tokenCount / tokenLimit); + let chunkSize = Math.floor(tokenCount / numChunks); + + const remainingTokens = tokenCount % tokenLimit; + if (remainingTokens > 0) { + chunkSize += Math.floor(remainingTokens / numChunks); + } + + return {chunkSize}; +} +``` + +This code calculates a reasonable single text block size that doesn't exceed the token limit. + +## Get Split Source Text Blocks + +![](/imgs/translate10.png) + +Using the single text block size and source text, write a function calling langchain's textsplitters package to implement text chunking: + +```typescript +import cloud from '@lafjs/cloud' +import { TokenTextSplitter } from "@langchain/textsplitters"; + +interface IRequestBody { + text: string + chunkSize: number +} + +interface RequestProps extends IRequestBody { + systemParams: { + appId: string, + variables: string, + histories: string, + cTime: string, + chatId: string, + responseChatItemId: string + } +} + +interface IResponse { + output: string[]; +} + +export default async function (ctx: FunctionContext): Promise{ + const { text = '', chunkSize=1000 }: RequestProps = ctx.body; + + const splitter = new TokenTextSplitter({ + encodingName:"gpt2", + chunkSize: Number(chunkSize), + chunkOverlap: 0, + }); + + const output = await splitter.splitText(text); + + return { + output + } +} +``` + +Now we have the split text. The next operations are similar to single text block reflective translation. + +## Multiple Text Block Translation + +You can't directly call the previous single text block reflective translation here because the prompts involve context handling (or you can modify the plugin to pass more parameters). + +The details are similar to before—just replace some prompts and do simple data processing. Overall effect: + +### Multiple Text Block Initial Translation + +![](/imgs/translate11.png) + +### Multiple Text Block Reflection + +![](/imgs/translate12.png) + +### Multiple Text Block Improved Translation + +![](/imgs/translate13.png) + +## Batch Execution + +A key part of long text reflective translation is looping through multiple text blocks for reflective translation. + +Fastgpt provides workflow loop functionality, so we can write a simple judgment function to determine whether to end or continue: + +![](/imgs/translate14.png) + +By checking if the current text block is the last one, we determine whether to continue execution. This achieves long text reflective translation. + +Complete workflow: + +![](/imgs/translate15.png) + +## Results + +First, input global settings: + +![](/imgs/translate16.png) + +Then input the text to translate. I chose a Harry Potter chapter in English. OpenAI's token count: + +![](/imgs/translate17.png) + +Actual results: + +![](/imgs/translate18.png) + +It meets reading requirements well. + +# Further Optimization + +## Prompt Optimization + +In the source project, the system prompts for AI are relatively brief. We can use more comprehensive prompts to encourage the LLM to return better translations, further improving quality. + +For example, in initial translation: + +```typescript +# Role: Senior Translation Expert + +## Background: +You are an experienced translation expert, proficient in {{source_lang}} and {{target_lang}} translation, especially skilled at translating {{source_lang}} articles into fluent, understandable {{target_lang}}. You've led teams to complete large translation projects with widely acclaimed results. + +## Attention: +- Always adhere to the principles of "faithfulness, expressiveness, and elegance" during translation, with "expressiveness" being especially important +- Translations should conform to {{target_lang}} expression habits, be easy to understand, coherent and fluent +- Avoid overly formal expressions and obscure allusions + +## Constraints: +- Must strictly follow the four-round translation process: literal translation, free translation, proofreading, finalization +- Translations must be faithful to the original, accurate, without omissions or misinterpretations + +## Goals: +- Through the four-round translation process, translate {{source_lang}} original text into high-quality {{target_lang}} translation +- Translations should accurately convey the original meaning, with language expression that's easy to understand and flows naturally +- Moderately use idioms, colloquialisms, popular internet terms, etc., to enhance translation appeal +- Based on literal translation, provide at least 2 different style free translation versions for selection + +## Skills: +- Proficient in both {{source_lang}} and {{target_lang}}, with solid language foundation and rich translation experience +- Skilled at converting {{source_lang}} expression habits into natural {{target_lang}} +- Keen insight into contemporary {{target_lang}} language development, good at grasping language trends + +## Workflow: +1. First round literal translation: Faithfully translate word by word, sentence by sentence, without omitting any information +2. Second round free translation: Based on literal translation, use fluent {{target_lang}} to freely translate the original, providing at least 2 different style versions +3. Third round proofreading: Carefully review the translation, eliminate deviations and deficiencies, making the translation more natural and understandable +4. Fourth round finalization: Select the best, repeatedly revise and polish, finally producing a concise, smooth translation that conforms to public reading habits + +## OutputFormat: +- Only output the fourth round finalization answer + +## Suggestions: +- In literal translation, strive to be faithful to the original, but don't be too rigid word by word +- In free translation, express the original meaning accurately using the most plain {{target_lang}} +- In proofreading, focus on whether the translation conforms to {{target_lang}} expression habits and is easy to understand +- In finalization, moderately use idioms, proverbs, internet slang, etc., to make the translation more down-to-earth +- Leverage {{target_lang}}'s flexibility, use different expressions to present the same content, improving translation readability +``` + +This returns more accurate, higher-quality initial translations. Subsequent reflection and improved translation can also use more accurate prompts: + +![](/imgs/translate19.png) + +Let's look at the results: + +![](/imgs/translate20.png) + +Testing with the same passage as before shows significant improvement. For example, the red box section—the previous translation: + +![](/imgs/translate21.png) + +Changed from the biased "让你的猫头鹰给我写信" (have your owl write to me) to the more accurate "给我写信，你的猫头鹰会知道怎么找到我" (write to me, your owl will know how to find me). + +## Other Optimizations + +For example, constraint optimization—the source project demonstrates adding regional constraints, which testing shows provides significant improvement. + +Thanks to LLM's excellent capabilities, we can obtain different translation results by setting different prompts—easily achieving specific, more precise translations through special constraints. + +For terms beyond LLM understanding, you can also use Fastgpt's knowledge base functionality for expansion, further improving the translation bot's capabilities. diff --git a/document/content/docs/use-cases/app-cases/submit_application_template.en.mdx b/document/content/docs/use-cases/app-cases/submit_application_template.en.mdx new file mode 100644 index 0000000000..313b58772a --- /dev/null +++ b/document/content/docs/use-cases/app-cases/submit_application_template.en.mdx @@ -0,0 +1,82 @@ +--- +title: How to Submit Application Templates +description: "Guide: How to submit application templates to FastGPT" +--- + +## Which Templates Can Be Merged + +Currently, application templates merged into the repository are displayed to all users in the "Template Market". + +To maintain template quality and avoid clutter from too many options, not all templates will be merged into the open-source repository. You can submit a PR in advance to discuss the template content with us. + +We estimate the final total will be around 50 templates — half from the FastGPT Team and half from community contributors. + +## How to Write an Application Template + +### 1. Set Up FastGPT and FastGPT-plugin Development Environments + +The following operations need to be performed in a dev environment. + +Refer to these two guides to run the FastGPT and FastGPT-plugin development environments locally: +- [FastGPT | Quick Start Local Development](/docs/introduction/development/intro/) +- [How to Develop System Plugins](/docs/introduction/guide/plugins/dev_system_tool/) + +### 2. Create an Application Template + +In the FastGPT-plugin project, application templates are located in the `modules/workflow/templates` directory. +1. Create a new `.json` file +2. Copy the following content and paste it into the newly created `.json` file + +```json +{ + "name": "Template Name", + "intro": "Template description, displayed on the template market page", + "author": "Your name", + "avatar": "Template avatar — place the image file in the same folder and fill in the corresponding path", + + "tags": ["Template tags"], // writing (text creation), image-generation (image generation), web-search (web search), + // roleplay (role-playing), office-services (office services) — currently 5 categories, choose the appropriate tag + + "type": "Template category", // simple (simple app), advanced (workflow), plugin (plugin) + + "workflow": { + // Leave this object empty for now — we'll paste the exported workflow later + "nodes": [], + "edges": [], + "chatConfig": {} + } +} +``` + + +### 3. Complete Template Orchestration and Testing + +1. Build the workflow in FastGPT (either in the cloud service version or a locally deployed version). + +### 4. Copy Configuration to template.json + +Hover your mouse over the application avatar and name in the top-left corner. A dropdown menu will appear with an option to export the workflow configuration. + +The exported configuration is automatically copied to the clipboard. Paste it directly into the template.json file, replacing the **workflow** value from step 2. + +![](/imgs/template_submission3.png) + +### 5. Verify the Template Loads Successfully + +Refresh the page, open the Template Market, check if it loads successfully, and click "Use" to test its functionality. + +![](/imgs/template_submission4.png) + +### 6. Deploy and Use + +After completing the above steps, you can package the fastgpt-plugin image for deployment. Currently, templates do not support hot updates — all templates are packaged within the image. + +If you prefer not to repackage the fastgpt-plugin image every time you update templates, you can mount the `.json` file to the `/app/workflows/` directory inside the container using Docker volume mounting. + +### 7. Submit a PR + +If you believe your template should be included in the open-source repository, you can submit it via a PR. + +- Clearly describe the template's purpose and functionality +- Include screenshots showing the template in action +- Explain template parameter configuration in the PR. For example, if the template requires applying for a key from a provider, include the corresponding URL and tutorial — we will add it to the documentation later. diff --git a/document/content/docs/use-cases/app-cases/translate-subtitle-using-gpt.en.mdx b/document/content/docs/use-cases/app-cases/translate-subtitle-using-gpt.en.mdx new file mode 100644 index 0000000000..9a85c74282 --- /dev/null +++ b/document/content/docs/use-cases/app-cases/translate-subtitle-using-gpt.en.mdx @@ -0,0 +1,2214 @@ +--- +title: Long Subtitle Translation +description: Use AI self-reflection to improve translation quality while leveraging iterative workflow execution to overcome LLM token limits, creating an efficient long subtitle translation bot. +--- + +Using LLMs directly to translate long subtitles presents several challenges that AI alone can't effectively handle: + +1. **Token Limits**: This is the most obvious obstacle. Large language models (LLMs) typically have output token limits, meaning **for long texts, without special workflows, you'd need to manually segment the text, translate each segment separately, and then manually stitch the results together**. This process is not only tedious but also error-prone. + +2. **Preserving Subtitle Format**: For subtitles, timeline information is crucial. However, AI models sometimes "hallucinate," generating or modifying information that doesn't exist. In subtitle translation, this can cause the AI to incorrectly modify timelines, making subtitles out of sync with audio. + +3. **Translation Quality**: Simple machine translation often fails to meet audience needs. Even with large language models, single-pass translation quality is frequently unsatisfactory. For subtitles, translation quality directly impacts viewing experience—poor translation severely disrupts audience immersion. + +This case study demonstrates how to effectively solve these problems by combining FastGPT workflow code with LLMs. Our approach not only overcomes technical limitations but also significantly improves translation quality. + +## Extract Subtitle Information + +A major advantage of workflows is the ability to combine additional operations, enabling AI to process information more precisely. In subtitle translation, we can **first separate the components of an SRT subtitle file, then have the LLM translate only the text portion**. This approach saves tokens and ensures timeline information isn't mistakenly altered. + +Implementation: + +1. Use a code execution module to parse the input raw subtitle text. +2. Classify subtitle information into three parts: time information, sequence numbers, and text information. +3. Keep only the text information for subsequent AI translation. + +![](/imgs/extract-subtitle.png) + +This preprocessing step greatly improves the efficiency and accuracy of the entire translation process. + +## Split Text + +To further optimize the translation process, we need to reorganize the extracted text information. The goal of this step is to **split the text into sizes suitable for LLM processing while maintaining contextual coherence**. + +In this example, we use the following strategy: + +1. Split the text into groups of 40 sentences each. This number is a balance point determined through multiple tests—it ensures translation quality without exceeding the LLM's processing capacity. +2. Use `` tags to separate each sentence. This marking method facilitates subsequent reassembly while providing clear sentence boundaries for the AI model. + +![](/imgs/cut-text.png) + +This splitting method considers both the AI model's capability limits and ensures translation coherence. By maintaining appropriate context, we can achieve more accurate and natural translation results. + +## Format Original Text + +In this step, we construct the final source text to input to the LLM. The key is how to provide sufficient context information while controlling token count. We use the following strategy: + +1. **Pass in all text as background context. This ensures the AI understands the context of the entire conversation**. +2. Use `` tags to clearly indicate the segment that currently needs translation. This method controls the AI's output scope without losing overall context. + +![](/imgs/format-original-text.png) + +This formatting method enables the AI to focus on translating specific parts while understanding the global context, thereby improving translation accuracy and coherence. + +## LLM Translation + +This is the most critical step in the entire process. We leverage the LLM's powerful capabilities to achieve high-quality translation. In this step, we integrate the previously mentioned "initial translation → reflection → improved translation" process into a single prompt. + +This process includes the following stages: + +1. First round literal translation: Require the AI to strictly translate sentence by sentence according to `` tags, ensuring accuracy. + + ![](/imgs/ai-translate-1.png) + +2. Second round free translation: Allow the AI to freely modify and optimize the first round results. + +3. Third round reflection: The AI evaluates its own translation and proposes improvement suggestions from multiple angles. + + ![](/imgs/ai-translate-2.png) + +4. Final round modification: Based on suggestions from the reflection stage, the AI makes final adjustments and optimizations to the translation. + + ![](/imgs/ai-translate-3.png) + +This multi-round translation and reflection method significantly improves translation quality. It not only captures the accurate meaning of the original text but also makes the translation more fluent and natural. + +It's worth noting that this method's effectiveness is comparable to direct step-by-step execution, but the workflow is more concise and efficient. + +## Combine Subtitles + +After completing the translation, we need to recombine all information into a complete subtitle file. This step includes: + +1. Integrate the previously separated sequence number and time information. +2. Match the translated text with the original text. +3. Use a code execution module to automatically complete the assembly process. + +![](/imgs/combine-subtitle.png) + +This process not only improves efficiency but also minimizes the possibility of human error. + +## Batch Execution + +To process the entire long subtitle file, we need a batch execution mechanism. This is implemented through a simple but effective judgment module: + +1. Check if the currently translated text block is the last one. +2. If not, redirect the workflow to the format original text block node. +3. Extract the next segment of text that needs translation and restart the translation and stitching process. + +![](/imgs/loop-execution.png) + +This loop mechanism ensures the entire long subtitle file can be fully processed, regardless of how long the subtitles are. + +## Practical Application Example + +To verify the effectiveness of this method, we selected an English subtitle segment from "Game of Thrones" and translated it into Simplified Chinese. You can see that our method not only accurately translates the content but also preserves the subtitle format and timeline information. + +![](/imgs/gpt-translate-example.png) + + +## Attachments + +The complete workflow configuration is below. Copy and import directly into FastGPT. + +
+Workflow Configuration + +```json +{ + "nodes": [ + { + "nodeId": "userGuide", + "name": "系统配置", + "intro": "可以配置应用的系统参数", + "avatar": "core/workflow/template/systemConfig", + "flowNodeType": "userGuide", + "position": { + "x": -1453.0815298642474, + "y": 269.10239463914263 + }, + "version": "481", + "inputs": [ + { + "key": "welcomeText", + "renderTypeList": [ + "hidden" + ], + "valueType": "string", + "label": "core.app.Welcome Text", + "value": "" + }, + { + "key": "variables", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "core.app.Chat Variable", + "value": [] + }, + { + "key": "questionGuide", + "valueType": "boolean", + "renderTypeList": [ + "hidden" + ], + "label": "core.app.Question Guide", + "value": false + }, + { + "key": "tts", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": { + "type": "web" + } + }, + { + "key": "whisper", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": { + "open": false, + "autoSend": false, + "autoTTSResponse": false + } + }, + { + "key": "scheduleTrigger", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": null + } + ], + "outputs": [] + }, + { + "nodeId": "448745", + "name": "流程开始", + "intro": "", + "avatar": "core/workflow/template/workflowStart", + "flowNodeType": "workflowStart", + "position": { + "x": -1458.2511936623089, + "y": 1218.2790943636066 + }, + "version": "481", + "inputs": [ + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "用户问题", + "required": true, + "toolDescription": "用户问题" + } + ], + "outputs": [ + { + "id": "userChatInput", + "key": "userChatInput", + "label": "core.module.input.label.user question", + "type": "static", + "valueType": "string" + } + ] + }, + { + "nodeId": "yjFO3YcM7KG2", + "name": "LLM 翻译", + "intro": "AI 大模型对话", + "avatar": "core/workflow/template/aiChat", + "flowNodeType": "chatNode", + "showStatus": true, + "position": { + "x": 2569.420973631976, + "y": 909.4127366971411 + }, + "version": "481", + "inputs": [ + { + "key": "model", + "renderTypeList": [ + "settingLLMModel", + "reference" + ], + "label": "core.module.input.label.aiModel", + "valueType": "string", + "selectedTypeIndex": 0, + "value": "claude-3-5-sonnet-20240620" + }, + { + "key": "temperature", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 3, + "valueType": "number", + "min": 0, + "max": 10, + "step": 1 + }, + { + "key": "maxToken", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": 4000, + "valueType": "number", + "min": 100, + "max": 4000, + "step": 50 + }, + { + "key": "isResponseAnswerText", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": false, + "valueType": "boolean" + }, + { + "key": "quoteTemplate", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "string" + }, + { + "key": "quotePrompt", + "renderTypeList": [ + "hidden" + ], + "label": "", + "valueType": "string" + }, + { + "key": "systemPrompt", + "renderTypeList": [ + "textarea", + "reference" + ], + "max": 3000, + "valueType": "string", + "label": "core.ai.Prompt", + "description": "core.app.tip.chatNodeSystemPromptTip", + "placeholder": "core.app.tip.chatNodeSystemPromptTip", + "value": "# Role: 资深字幕翻译专家\n\n## Background:\n你是一位经验丰富的{{source_lang}}和{{target_lang}}字幕翻译专家,精通{{source_lang}}和{{target_lang}}互译,尤其擅长将{{source_lang}}字幕译成流畅易懂的{{target_lang}}字幕。你曾多次带领团队完成大型商业电影的字幕翻译项目,所翻译的字幕广受好评。\n\n## Attention:\n- 翻译过程中要始终坚持\"信、达、雅\"的原则,但\"达\"尤为重要\n- 翻译的字幕要符合{{target_lang}}的表达习惯,通俗易懂,连贯流畅\n- 避免使用过于文绉绉的表达和晦涩难懂的典故引用 \n- 诗词歌词等内容需按原文换行和节奏分行,不破坏原排列格式 \n- 翻译对象是字幕，请进入整段文本的语境中对需要翻译的文本段进行翻译\n- 是标识每一帧字幕的标签,请严格按照对文本的分割逐帧翻译，每一帧字幕末尾不要加 \\n 回车标识，且第一帧字幕开头不需要加标识\n\n## Constraints:\n- 必须严格遵循四轮翻译流程:直译、意译、反思、提升\n- 译文要忠实原文,准确无误,不能遗漏或曲解原意\n- 最终译文使用Markdown的代码块呈现,但是不用输出markdown这个单词\n- 是标识每一帧字幕的标签,请严格按照对文本的分割逐帧翻译，每一帧字幕末尾不要加 \\n 回车标识，且第一帧字幕开头不需要加标识\n\n## Goals:\n- 通过四轮翻译流程,将{{source_lang}}字幕译成高质量的{{target_lang}}字幕\n- 翻译的字幕要准确传达原字幕意思,语言表达力求浅显易懂,朗朗上口 \n\n## Workflow:\n1. 第一轮直译:严格按照逐句翻译,不遗漏任何信息\n2. 第二轮意译:在直译的基础上用通俗流畅的{{target_lang}}意译原文,逐句翻译,保留标识标签\n3. 第三轮反思:仔细审视译文,分点列出一份建设性的批评和有用的建议清单以改进翻译，对每一句话提出建议，从以下四个角度展开\n (i) 准确性（纠正添加、误译、遗漏或未翻译的文本错误），\n (ii) 流畅性（应用{{target_lang}}的语法、拼写和标点规则，并确保没有不必要的重复），\n (iii) 风格（确保翻译反映源文本的风格并考虑其文化背景），\n (iv) 术语（确保术语使用一致且反映源文本所在领域，注意确保使用{{target_lang}}中的等效习语）\n4. 第四轮提升:严格遵循第三轮提出的建议对翻译修改,定稿出一个简洁畅达、符合大众观影习惯的字幕译文,保留标识标签\n\n## OutputFormat:\n- 每一轮前用【思考】说明该轮要点\n- 第一轮和第二轮翻译后用【翻译】呈现译文\n- 第三轮输出建议清单，分点列出，在每一点前用*xxx*标识这条建议对应的要点，如*风格*;建议前用【思考】说明该轮要点，建议后用【建议】呈现建议\n- 第四轮在\\`\\`\\`代码块中展示最终{{target_lang}}字幕文件内容，如\\`\\`\\`xxx\\`\\`\\`\n\n## Suggestions:\n- 直译时力求忠实原文,但注意控制每帧字幕的字数,必要时进行精简压缩\n- 意译时在准确表达原意的基础上,用最朴实无华的{{target_lang}}来表达\n- 反思环节重点关注译文是否符合{{target_lang}}表达习惯,是否通俗易懂,是否准确流畅,是否术语一致\n- 提升环节采用反思环节的建议对意译环节的翻译进行修改，适度采用一些口语化的表达、网络流行语等,增强字幕的亲和力\n- 注意是很重要的标识标签，请确保标签能在正确位置输出" + }, + { + "key": "history", + "renderTypeList": [ + "numberInput", + "reference" + ], + "valueType": "chatHistory", + "label": "core.module.input.label.chat history", + "description": "最多携带多少轮对话记录", + "required": true, + "min": 0, + "max": 50, + "value": 6 + }, + { + "key": "userChatInput", + "renderTypeList": [ + "reference", + "textarea" + ], + "valueType": "string", + "label": "用户问题", + "required": true, + "toolDescription": "用户问题", + "value": [ + "bxz97Vg4Omux", + "system_text" + ] + }, + { + "key": "quoteQA", + "renderTypeList": [ + "settingDatasetQuotePrompt" + ], + "label": "", + "debugLabel": "知识库引用", + "description": "", + "valueType": "datasetQuote" + } + ], + "outputs": [ + { + "id": "history", + "key": "history", + "required": true, + "label": "core.module.output.label.New context", + "description": "core.module.output.description.New context", + "valueType": "chatHistory", + "type": "static" + }, + { + "id": "answerText", + "key": "answerText", + "required": true, + "label": "core.module.output.label.Ai response content", + "description": "core.module.output.description.Ai response content", + "valueType": "string", + "type": "static" + } + ] + }, + { + "nodeId": "bxz97Vg4Omux", + "name": "LLM 翻译提示词", + "intro": "可对固定或传入的文本进行加工后输出，非字符串类型数据最终会转成字符串类型。", + "avatar": "core/workflow/template/textConcat", + "flowNodeType": "textEditor", + "position": { + "x": 1893.11421220213, + "y": 1065.1299598362698 + }, + "version": "486", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "可以引用其他节点的输出，作为文本拼接的变量，通过 {{字段名}} 来引用变量", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + } + }, + { + "key": "system_textareaInput", + "renderTypeList": [ + "textarea" + ], + "valueType": "string", + "required": true, + "label": "拼接文本", + "placeholder": "可通过 {{字段名}} 来引用变量", + "value": "你的任务是将文本从{{source_lang}}翻译成{{target_lang}}\n\n源文本如下,由XML标签和分隔:\n\n\n\n{{tagged_text}}\n\n\n\n仅翻译源文本中由和分隔的部分,将其余的源文本作为上下文\n\n重申一下,你应该只翻译文本的这一部分,这里再次显示在和之间:\n\n\n\n{{chunk_to_translate}}\n\n" + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "string", + "canEdit": true, + "key": "tagged_text", + "label": "tagged_text", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "required": true, + "value": [ + "quYZgsW32ApA", + "xhXu6sdEWBnF" + ] + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "string", + "canEdit": true, + "key": "chunk_to_translate", + "label": "chunk_to_translate", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "required": true, + "value": [ + "quYZgsW32ApA", + "eCp73lztAEGK" + ] + } + ], + "outputs": [ + { + "id": "system_text", + "key": "system_text", + "label": "拼接结果", + "type": "static", + "valueType": "string" + } + ] + }, + { + "nodeId": "w4heEpNflz59", + "name": "判断是否执行结束", + "intro": "根据一定的条件，执行不同的分支。", + "avatar": "core/workflow/template/ifelse", + "flowNodeType": "ifElseNode", + "showStatus": true, + "position": { + "x": 5625.495682697096, + "y": 1199.9313115831496 + }, + "version": "481", + "inputs": [ + { + "key": "ifElseList", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": [ + { + "condition": "AND", + "list": [ + { + "variable": [ + "a2lqxASWi1vb", + "nmBmGaARbKkl" + ], + "condition": "equalTo", + "value": "true" + } + ] + } + ] + } + ], + "outputs": [ + { + "id": "ifElseResult", + "key": "ifElseResult", + "label": "判断结果", + "valueType": "string", + "type": "static" + } + ] + }, + { + "nodeId": "a2lqxASWi1vb", + "name": "判断是否执行结束", + "intro": "执行一段简单的脚本代码，通常用于进行复杂的数据处理。", + "avatar": "core/workflow/template/codeRun", + "flowNodeType": "code", + "showStatus": true, + "position": { + "x": 5099.256084679105, + "y": 1102.1518590433243 + }, + "version": "482", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "这些变量会作为代码的运行的输入参数", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + } + }, + { + "key": "codeType", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": "js" + }, + { + "key": "code", + "renderTypeList": [ + "custom" + ], + "label": "", + "value": "function main({chunks, currentChunk}){\n const findIndex = chunks.findIndex((item) => item === currentChunk)\n\n return {\n isEnd: chunks.length-1 === findIndex,\n i: findIndex + 1,\n }\n}" + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "arrayString", + "canEdit": true, + "key": "chunks", + "label": "chunks", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "y3WEYOQ09CGC", + "qLUQfhG0ILRX" + ] + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "string", + "canEdit": true, + "key": "currentChunk", + "label": "currentChunk", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "quYZgsW32ApA", + "eCp73lztAEGK" + ] + } + ], + "outputs": [ + { + "id": "system_rawResponse", + "key": "system_rawResponse", + "label": "完整响应数据", + "valueType": "object", + "type": "static" + }, + { + "id": "error", + "key": "error", + "label": "运行错误", + "description": "代码运行错误信息，成功时返回空", + "valueType": "object", + "type": "static" + }, + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "customFieldConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "description": "将代码中 return 的对象作为输出，传递给后续的节点。变量名需要对应 return 的 key" + }, + { + "id": "nmBmGaARbKkl", + "valueType": "boolean", + "type": "dynamic", + "key": "isEnd", + "label": "isEnd" + }, + { + "id": "nqB98uKpq6Ig", + "valueType": "number", + "type": "dynamic", + "key": "i", + "label": "i" + } + ] + }, + { + "nodeId": "quYZgsW32ApA", + "name": "格式化源文本块", + "intro": "执行一段简单的脚本代码，通常用于进行复杂的数据处理。", + "avatar": "core/workflow/template/codeRun", + "flowNodeType": "code", + "showStatus": true, + "position": { + "x": 1251.2839737092052, + "y": 991.619268503857 + }, + "version": "482", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "这些变量会作为代码的运行的输入参数", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + } + }, + { + "key": "codeType", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": "js" + }, + { + "key": "code", + "renderTypeList": [ + "custom" + ], + "label": "", + "value": "function main({source_text_chunks, i=0}){\n let before = source_text_chunks.slice(0, i).join(\"\");\n let current = \" \" + source_text_chunks[i] + \"\";\n let after = source_text_chunks.slice(i + 1).join(\"\");\n let tagged_text = before + current + after;\n\n return {\n tagged_text,\n chunk_to_translate: source_text_chunks[i],\n }\n}" + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "number", + "canEdit": true, + "key": "i", + "label": "i", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "a2lqxASWi1vb", + "nqB98uKpq6Ig" + ] + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "arrayString", + "canEdit": true, + "key": "source_text_chunks", + "label": "source_text_chunks", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "y3WEYOQ09CGC", + "qLUQfhG0ILRX" + ] + } + ], + "outputs": [ + { + "id": "system_rawResponse", + "key": "system_rawResponse", + "label": "完整响应数据", + "valueType": "object", + "type": "static" + }, + { + "id": "error", + "key": "error", + "label": "运行错误", + "description": "代码运行错误信息，成功时返回空", + "valueType": "object", + "type": "static" + }, + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "customFieldConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "description": "将代码中 return 的对象作为输出，传递给后续的节点。变量名需要对应 return 的 key" + }, + { + "id": "xhXu6sdEWBnF", + "valueType": "string", + "type": "dynamic", + "key": "tagged_text", + "label": "tagged_text" + }, + { + "id": "eCp73lztAEGK", + "valueType": "string", + "type": "dynamic", + "key": "chunk_to_translate", + "label": "chunk_to_translate" + } + ] + }, + { + "nodeId": "izsNX8FXGD1t", + "name": "指定回复", + "intro": "该模块可以直接回复一段指定的内容。常用于引导、提示。非字符串内容传入时，会转成字符串进行输出。", + "avatar": "core/workflow/template/reply", + "flowNodeType": "answerNode", + "position": { + "x": 6399.439691374053, + "y": 1204.4024103331792 + }, + "version": "481", + "inputs": [ + { + "key": "text", + "renderTypeList": [ + "textarea", + "reference" + ], + "valueType": "any", + "required": true, + "label": "core.module.input.label.Response content", + "description": "core.module.input.description.Response content", + "placeholder": "core.module.input.description.Response content", + "value": "\n\n*** 字幕反思翻译完成！***" + } + ], + "outputs": [] + }, + { + "nodeId": "vlNHndpNuFXB", + "name": "取出 LLM 翻译第四轮文本", + "intro": "执行一段简单的脚本代码，通常用于进行复杂的数据处理。", + "avatar": "core/workflow/template/codeRun", + "flowNodeType": "code", + "showStatus": true, + "position": { + "x": 3284.6375352131763, + "y": 950.1100995985583 + }, + "version": "482", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "这些变量会作为代码的运行的输入参数", + "editField": { + "key": true, + "valueType": true + }, + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + } + }, + { + "key": "codeType", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": "js" + }, + { + "key": "code", + "renderTypeList": [ + "custom" + ], + "label": "", + "value": "function main({data1}){\n const result = data1.split(\"```\").filter(item => !!item.trim())\n\n if(result[result.length-1]) {\n return {\n result: result[result.length-1].trim() \n }\n }\n\n return {\n result: '未截取到翻译内容'\n }\n}" + }, + { + "key": "data1", + "valueType": "string", + "label": "data1", + "renderTypeList": [ + "reference" + ], + "description": "", + "canEdit": true, + "editField": { + "key": true, + "valueType": true + }, + "value": [ + "yjFO3YcM7KG2", + "answerText" + ], + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + } + } + ], + "outputs": [ + { + "id": "system_rawResponse", + "key": "system_rawResponse", + "label": "完整响应数据", + "valueType": "object", + "type": "static" + }, + { + "id": "error", + "key": "error", + "label": "运行错误", + "description": "代码运行错误信息，成功时返回空", + "valueType": "object", + "type": "static" + }, + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "customFieldConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "description": "将代码中 return 的对象作为输出，传递给后续的节点。变量名需要对应 return 的 key" + }, + { + "id": "qLUQfhG0ILRX", + "type": "dynamic", + "key": "result", + "valueType": "string", + "label": "result" + }, + { + "id": "gR0mkQpJ4Og8", + "type": "dynamic", + "key": "data2", + "valueType": "string", + "label": "data2" + } + ] + }, + { + "nodeId": "qlt9KJbbS9yJ", + "name": "判断源语言和目标语言是否相同", + "intro": "根据一定的条件，执行不同的分支。", + "avatar": "core/workflow/template/ifelse", + "flowNodeType": "ifElseNode", + "showStatus": true, + "position": { + "x": -648.2730659546055, + "y": 1295.3336516652123 + }, + "version": "481", + "inputs": [ + { + "key": "ifElseList", + "renderTypeList": [ + "hidden" + ], + "valueType": "any", + "label": "", + "value": [ + { + "condition": "AND", + "list": [ + { + "variable": [ + "frjbsrlnJJsR", + "qLUQfhG0ILRX" + ], + "condition": "equalTo", + "value": "false" + } + ] + } + ] + } + ], + "outputs": [ + { + "id": "ifElseResult", + "key": "ifElseResult", + "label": "判断结果", + "valueType": "string", + "type": "static" + } + ] + }, + { + "nodeId": "frjbsrlnJJsR", + "name": "判断源语言和目标语言是否相同", + "intro": "执行一段简单的脚本代码，通常用于进行复杂的数据处理。", + "avatar": "core/workflow/template/codeRun", + "flowNodeType": "code", + "showStatus": true, + "position": { + "x": -1142.9562352499165, + "y": 1031.4486788585432 + }, + "version": "482", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "这些变量会作为代码的运行的输入参数", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + } + }, + { + "key": "codeType", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": "js" + }, + { + "key": "code", + "renderTypeList": [ + "custom" + ], + "label": "", + "value": "function main({source_lang, target_lang}){\n \n return {\n result: source_lang === target_lang\n }\n}" + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "string", + "canEdit": true, + "key": "source_lang", + "label": "source_lang", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "VARIABLE_NODE_ID", + "source_lang" + ] + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "string", + "canEdit": true, + "key": "target_lang", + "label": "target_lang", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "VARIABLE_NODE_ID", + "target_lang" + ] + } + ], + "outputs": [ + { + "id": "system_rawResponse", + "key": "system_rawResponse", + "label": "完整响应数据", + "valueType": "object", + "type": "static" + }, + { + "id": "error", + "key": "error", + "label": "运行错误", + "description": "代码运行错误信息，成功时返回空", + "valueType": "object", + "type": "static" + }, + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "customFieldConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "description": "将代码中 return 的对象作为输出，传递给后续的节点。变量名需要对应 return 的 key" + }, + { + "id": "qLUQfhG0ILRX", + "type": "dynamic", + "key": "result", + "valueType": "boolean", + "label": "result" + } + ] + }, + { + "nodeId": "dFxrGZS3Wmnz", + "name": "提示源语言与目标语言相同", + "intro": "该模块可以直接回复一段指定的内容。常用于引导、提示。非字符串内容传入时，会转成字符串进行输出。", + "avatar": "core/workflow/template/reply", + "flowNodeType": "answerNode", + "position": { + "x": -554.7555863373991, + "y": 1727.175384457058 + }, + "version": "481", + "inputs": [ + { + "key": "text", + "renderTypeList": [ + "textarea", + "reference" + ], + "valueType": "any", + "required": true, + "label": "core.module.input.label.Response content", + "description": "core.module.input.description.Response content", + "placeholder": "core.module.input.description.Response content", + "selectedTypeIndex": 0, + "value": "{{source_lang}} 无需再次翻译为 {{target_lang}} ~" + } + ], + "outputs": [] + }, + { + "nodeId": "tqzmK5oPR9BA", + "name": "输出翻译", + "intro": "该模块可以直接回复一段指定的内容。常用于引导、提示。非字符串内容传入时，会转成字符串进行输出。", + "avatar": "core/workflow/template/reply", + "flowNodeType": "answerNode", + "position": { + "x": 4378.294585712487, + "y": 1268.975092230105 + }, + "version": "481", + "inputs": [ + { + "key": "text", + "renderTypeList": [ + "textarea", + "reference" + ], + "valueType": "any", + "required": true, + "label": "core.module.input.label.Response content", + "description": "core.module.input.description.Response content", + "placeholder": "core.module.input.description.Response content", + "selectedTypeIndex": 1, + "value": [ + "ppPP6o7YYSTJ", + "dYalXmYJ60bj" + ] + } + ], + "outputs": [] + }, + { + "nodeId": "kbr342XlxSZR", + "name": "提取字幕信息", + "intro": "执行一段简单的脚本代码，通常用于进行复杂的数据处理。", + "avatar": "core/workflow/template/codeRun", + "flowNodeType": "code", + "showStatus": true, + "position": { + "x": 185.35869756392378, + "y": 1004.6884026918935 + }, + "version": "482", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "这些变量会作为代码的运行的输入参数", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + } + }, + { + "key": "codeType", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": "js" + }, + { + "key": "code", + "renderTypeList": [ + "custom" + ], + "label": "", + "value": "function main({text}){\n const lines = text.split('\\n');\n const timePattern = /\\d{2}:\\d{2}:\\d{2},\\d{3} --> \\d{2}:\\d{2}:\\d{2},\\d{3}/;\n const numberInfo = [];\n const timeInfo = [];\n const textInfo = [];\n let currentText = [];\n\n // 提取序号、时间戳和文本信息\n lines.forEach(line => {\n if (/^\\d+$/.test(line.trim())) {\n numberInfo.push(line.trim());\n } else if (timePattern.test(line)) {\n timeInfo.push(line);\n if (currentText.length > 0) {\n textInfo.push(currentText.join(' '));\n currentText = [];\n }\n } else if (line.trim() === '') {\n // Skip empty lines\n } else {\n currentText.push(line.trim());\n }\n });\n\n if (currentText.length > 0) {\n textInfo.push(currentText.join(' '));\n }\n\n return { numberInfo, timeInfo, textInfo };\n}" + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "string", + "canEdit": true, + "key": "text", + "label": "text", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "448745", + "userChatInput" + ] + } + ], + "outputs": [ + { + "id": "system_rawResponse", + "key": "system_rawResponse", + "label": "完整响应数据", + "valueType": "object", + "type": "static" + }, + { + "id": "error", + "key": "error", + "label": "运行错误", + "description": "代码运行错误信息，成功时返回空", + "valueType": "object", + "type": "static" + }, + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "customFieldConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "description": "将代码中 return 的对象作为输出，传递给后续的节点。变量名需要对应 return 的 key" + }, + { + "id": "h3qVuGhV9HNm", + "valueType": "arrayString", + "type": "dynamic", + "key": "timeInfo", + "label": "timeInfo" + }, + { + "id": "zGYRMNA9xGuI", + "valueType": "arrayString", + "type": "dynamic", + "key": "textInfo", + "label": "textInfo" + }, + { + "id": "dhzTt6Riz8Dp", + "valueType": "arrayString", + "type": "dynamic", + "key": "numberInfo", + "label": "numberInfo" + } + ] + }, + { + "nodeId": "ppPP6o7YYSTJ", + "name": "格式化字幕文件", + "intro": "执行一段简单的脚本代码，通常用于进行复杂的数据处理。", + "avatar": "core/workflow/template/codeRun", + "flowNodeType": "code", + "showStatus": true, + "position": { + "x": 3825.553384884565, + "y": 956.4575651844932 + }, + "version": "482", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "这些变量会作为代码的运行的输入参数", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + } + }, + { + "key": "codeType", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": "js" + }, + { + "key": "code", + "renderTypeList": [ + "custom" + ], + "label": "", + "value": "function main({combinedText, transedText, timeInfo, currentIndex=0,numberInfo}){\n const textLines = combinedText.split('');\n const resultLines = transedText.split('');\n const combinedLines = [];\n\n resultLines.forEach((line, index) => {\n combinedLines.push(numberInfo[currentIndex+index]);\n combinedLines.push(timeInfo[currentIndex+index]);\n combinedLines.push(line)\n combinedLines.push(textLines[index]);\n combinedLines.push('');\n });\n\n const srtContent = combinedLines.join('\\n');\n \n\n return {\n srtContent,\n currentIndex: currentIndex+textLines.length\n }\n}" + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "string", + "canEdit": true, + "key": "combinedText", + "label": "combinedText", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "quYZgsW32ApA", + "eCp73lztAEGK" + ] + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "string", + "canEdit": true, + "key": "transedText", + "label": "transedText", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "vlNHndpNuFXB", + "qLUQfhG0ILRX" + ] + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "arrayString", + "canEdit": true, + "key": "timeInfo", + "label": "timeInfo", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "kbr342XlxSZR", + "h3qVuGhV9HNm" + ] + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "number", + "canEdit": true, + "key": "currentIndex", + "label": "currentIndex", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "ppPP6o7YYSTJ", + "u6eqeC0pEPe0" + ] + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "arrayString", + "canEdit": true, + "key": "numberInfo", + "label": "numberInfo", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "kbr342XlxSZR", + "dhzTt6Riz8Dp" + ] + } + ], + "outputs": [ + { + "id": "system_rawResponse", + "key": "system_rawResponse", + "label": "完整响应数据", + "valueType": "object", + "type": "static" + }, + { + "id": "error", + "key": "error", + "label": "运行错误", + "description": "代码运行错误信息，成功时返回空", + "valueType": "object", + "type": "static" + }, + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "customFieldConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "description": "将代码中 return 的对象作为输出，传递给后续的节点。变量名需要对应 return 的 key" + }, + { + "id": "dYalXmYJ60bj", + "valueType": "string", + "type": "dynamic", + "key": "srtContent", + "label": "srtContent" + }, + { + "id": "u6eqeC0pEPe0", + "valueType": "number", + "type": "dynamic", + "key": "currentIndex", + "label": "currentIndex" + } + ] + }, + { + "nodeId": "y3WEYOQ09CGC", + "name": "切分文本", + "intro": "执行一段简单的脚本代码，通常用于进行复杂的数据处理。", + "avatar": "core/workflow/template/codeRun", + "flowNodeType": "code", + "showStatus": true, + "position": { + "x": 742.138506499589, + "y": 1011.2409789066801 + }, + "version": "482", + "inputs": [ + { + "key": "system_addInputParam", + "renderTypeList": [ + "addInputParam" + ], + "valueType": "dynamic", + "label": "", + "required": false, + "description": "这些变量会作为代码的运行的输入参数", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + } + }, + { + "key": "codeType", + "renderTypeList": [ + "hidden" + ], + "label": "", + "value": "js" + }, + { + "key": "code", + "renderTypeList": [ + "custom" + ], + "label": "", + "value": "function main({textArray}){\n const groupSize = 20\n const delimiter = ''\n\n const result = [];\n\n for (let i = 0; i < textArray.length; i += groupSize) {\n result.push(textArray.slice(i, i + groupSize).join(delimiter));\n }\n\n return {result};\n}" + }, + { + "renderTypeList": [ + "reference" + ], + "valueType": "arrayString", + "canEdit": true, + "key": "textArray", + "label": "textArray", + "customInputConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": true + }, + "required": true, + "value": [ + "kbr342XlxSZR", + "zGYRMNA9xGuI" + ] + } + ], + "outputs": [ + { + "id": "system_rawResponse", + "key": "system_rawResponse", + "label": "完整响应数据", + "valueType": "object", + "type": "static" + }, + { + "id": "error", + "key": "error", + "label": "运行错误", + "description": "代码运行错误信息，成功时返回空", + "valueType": "object", + "type": "static" + }, + { + "id": "system_addOutputParam", + "key": "system_addOutputParam", + "type": "dynamic", + "valueType": "dynamic", + "label": "", + "customFieldConfig": { + "selectValueTypeList": [ + "string", + "number", + "boolean", + "object", + "arrayString", + "arrayNumber", + "arrayBoolean", + "arrayObject", + "any", + "chatHistory", + "datasetQuote", + "dynamic", + "selectApp", + "selectDataset" + ], + "showDescription": false, + "showDefaultValue": false + }, + "description": "将代码中 return 的对象作为输出，传递给后续的节点。变量名需要对应 return 的 key" + }, + { + "id": "qLUQfhG0ILRX", + "type": "dynamic", + "key": "result", + "valueType": "arrayString", + "label": "result" + } + ] + } + ], + "edges": [ + { + "source": "bxz97Vg4Omux", + "target": "yjFO3YcM7KG2", + "sourceHandle": "bxz97Vg4Omux-source-right", + "targetHandle": "yjFO3YcM7KG2-target-left" + }, + { + "source": "a2lqxASWi1vb", + "target": "w4heEpNflz59", + "sourceHandle": "a2lqxASWi1vb-source-right", + "targetHandle": "w4heEpNflz59-target-left" + }, + { + "source": "w4heEpNflz59", + "target": "izsNX8FXGD1t", + "sourceHandle": "w4heEpNflz59-source-IF", + "targetHandle": "izsNX8FXGD1t-target-left" + }, + { + "source": "448745", + "target": "frjbsrlnJJsR", + "sourceHandle": "448745-source-right", + "targetHandle": "frjbsrlnJJsR-target-left" + }, + { + "source": "frjbsrlnJJsR", + "target": "qlt9KJbbS9yJ", + "sourceHandle": "frjbsrlnJJsR-source-right", + "targetHandle": "qlt9KJbbS9yJ-target-left" + }, + { + "source": "tqzmK5oPR9BA", + "target": "a2lqxASWi1vb", + "sourceHandle": "tqzmK5oPR9BA-source-right", + "targetHandle": "a2lqxASWi1vb-target-left" + }, + { + "source": "yjFO3YcM7KG2", + "target": "vlNHndpNuFXB", + "sourceHandle": "yjFO3YcM7KG2-source-right", + "targetHandle": "vlNHndpNuFXB-target-left" + }, + { + "source": "ppPP6o7YYSTJ", + "target": "tqzmK5oPR9BA", + "sourceHandle": "ppPP6o7YYSTJ-source-right", + "targetHandle": "tqzmK5oPR9BA-target-left" + }, + { + "source": "kbr342XlxSZR", + "target": "y3WEYOQ09CGC", + "sourceHandle": "kbr342XlxSZR-source-right", + "targetHandle": "y3WEYOQ09CGC-target-left" + }, + { + "source": "y3WEYOQ09CGC", + "target": "quYZgsW32ApA", + "sourceHandle": "y3WEYOQ09CGC-source-right", + "targetHandle": "quYZgsW32ApA-target-left" + }, + { + "source": "quYZgsW32ApA", + "target": "bxz97Vg4Omux", + "sourceHandle": "quYZgsW32ApA-source-right", + "targetHandle": "bxz97Vg4Omux-target-left" + }, + { + "source": "w4heEpNflz59", + "target": "quYZgsW32ApA", + "sourceHandle": "w4heEpNflz59-source-ELSE", + "targetHandle": "quYZgsW32ApA-target-left" + }, + { + "source": "qlt9KJbbS9yJ", + "target": "kbr342XlxSZR", + "sourceHandle": "qlt9KJbbS9yJ-source-IF", + "targetHandle": "kbr342XlxSZR-target-left" + }, + { + "source": "qlt9KJbbS9yJ", + "target": "dFxrGZS3Wmnz", + "sourceHandle": "qlt9KJbbS9yJ-source-ELSE", + "targetHandle": "dFxrGZS3Wmnz-target-right" + }, + { + "source": "vlNHndpNuFXB", + "target": "ppPP6o7YYSTJ", + "sourceHandle": "vlNHndpNuFXB-source-right", + "targetHandle": "ppPP6o7YYSTJ-target-left" + } + ], + "chatConfig": { + "welcomeText": "你好，欢迎使用长字幕反思翻译机器人。\n\n在完成下方设置后，可以直接输入需要翻译的文本", + "variables": [ + { + "id": "v98n5b", + "key": "source_lang", + "label": "源语言", + "type": "select", + "required": true, + "maxLen": 50, + "enums": [ + { + "value": "简体中文" + }, + { + "value": "繁體中文" + }, + { + "value": "English" + }, + { + "value": "Español" + }, + { + "value": "Français" + }, + { + "value": "Deutsch" + }, + { + "value": "Italiano" + }, + { + "value": "日本語" + }, + { + "value": "한국어" + }, + { + "value": "Русский" + }, + { + "value": "العربية" + }, + { + "value": "Bahasa Indonesia" + }, + { + "value": "Polski" + } + ], + "icon": "core/app/variable/select" + }, + { + "id": "c3tvge", + "key": "target_lang", + "label": "目标语言", + "type": "select", + "required": true, + "maxLen": 50, + "enums": [ + { + "value": "简体中文" + }, + { + "value": "繁體中文" + }, + { + "value": "English" + }, + { + "value": "Español" + }, + { + "value": "Français" + }, + { + "value": "Deutsch" + }, + { + "value": "Italiano" + }, + { + "value": "日本語" + }, + { + "value": "한국어" + }, + { + "value": "Русский" + }, + { + "value": "العربية" + }, + { + "value": "Bahasa Indonesia" + }, + { + "value": "Polski" + } + ], + "icon": "core/app/variable/select" + } + ], + "scheduledTriggerConfig": { + "cronString": "", + "timezone": "Asia/Shanghai", + "defaultPrompt": "" + }, + "_id": "6688b45317c65410d61d58aa" + } +} +``` + +
diff --git a/document/content/docs/use-cases/external-integration/dingtalk.en.mdx b/document/content/docs/use-cases/external-integration/dingtalk.en.mdx new file mode 100644 index 0000000000..1240057a50 --- /dev/null +++ b/document/content/docs/use-cases/external-integration/dingtalk.en.mdx @@ -0,0 +1,61 @@ +--- +title: DingTalk Bot Integration +description: FastGPT DingTalk Bot Integration Tutorial +--- + +Starting from version 4.8.16, FastGPT commercial edition supports direct DingTalk bot integration without additional APIs. + +## 1. Create a DingTalk Internal Enterprise App + +1. Create an internal enterprise app in the [DingTalk Developer Console](https://open-dev.dingtalk.com/fe/app). + +![Image 1](/imgs/dingtalk-bot-1.png) + +2. Obtain the **Client ID** and **Client Secret**. + +![Image 2](/imgs/dingtalk-bot-2.png) + +## 2. Add a Publishing Channel in FastGPT + +In FastGPT, select the app you want to integrate. On the **Publishing Channels** page, create a new DingTalk bot publishing channel. + +Enter the **Client ID** and **Client Secret** obtained earlier into the configuration dialog. + +![Image 3](/imgs/dingtalk-bot-3.png) + +After creation, click the **Request URL** button and copy the callback address. + +## 3. Add **Bot** Capability to the App + +In the DingTalk Developer Console, click **Add App Capability** on the left sidebar, and add the **Bot** capability to the internal enterprise app you just created. + +![Image 4](/imgs/dingtalk-bot-4.png) + +## 4. Configure Bot Callback Address + +Click the **Bot** capability on the left sidebar, then set the **Message Receiving Mode** at the bottom to **HTTP Mode**, and paste the FastGPT callback address you copied earlier as the message receiving address. + +![Image 5](/imgs/dingtalk-bot-5.png) + +After debugging, click **Publish**. + +## 5. Publish the App + +After the bot is published, you still need to publish the app version on the **Version Management and Publishing** page. + +![Image 6](/imgs/dingtalk-bot-6.png) + +Click **Create New Version**, set the version number and description, then click save to publish. + +![Image 7](/imgs/dingtalk-bot-7.png) + +Once the app is published, you can use the bot within your DingTalk enterprise. You can chat with the bot privately, or add the bot to a group and `@mention the bot` to start a conversation. + +![Image 8](/imgs/dingtalk-bot-8.png) + + +## FAQ + +### How to start a new chat history + +To reset your chat history, send a `Reset` message to the bot (case-sensitive), and the bot will start a new chat history. diff --git a/document/content/docs/use-cases/external-integration/feishu.en.mdx b/document/content/docs/use-cases/external-integration/feishu.en.mdx new file mode 100644 index 0000000000..9b87d7d960 --- /dev/null +++ b/document/content/docs/use-cases/external-integration/feishu.en.mdx @@ -0,0 +1,103 @@ +--- +title: Lark Bot Integration +description: FastGPT Lark Bot Integration Tutorial +--- + +Starting from version 4.8.10, FastGPT commercial edition supports direct Lark bot integration without additional APIs. + +## 1. Create a Lark App + +Creating a free test enterprise makes debugging easier. + +1. Create a custom enterprise app in the [Lark Open Platform](https://open.feishu.cn/app) developer console. + +![Image](/imgs/feishu-bot-1.png) + +Add a **Bot** capability to the app. + +## 2. Create a Publishing Channel in FastGPT + +In FastGPT, select the app you want to integrate. On the Publishing Channels page, create a new Lark bot publishing channel and fill in the basic information. + +![Image](/imgs/feishu-bot-2.png) + +## 3. Get App ID and App Secret + +In the Lark Open Platform developer console, find the App ID and App Secret for the custom enterprise app you just created, and enter them in the FastGPT publishing channel dialog. + +![Image](/imgs/feishu-bot-3.png) + +Enter both parameters in the FastGPT configuration dialog. + +![Image](/imgs/feishu-bot-4.png) + +(Optional) In the Lark Open Platform developer console, go to Events & Callbacks -> Encryption Strategy to get the Encrypt Key, and enter it in the Lark bot integration dialog. + +![Image](/imgs/feishu-bot-5.png) + +The Encrypt Key encrypts communication between Lark servers and FastGPT. +If using HTTPS, the Encrypt Key is not needed. If using HTTP, the Encrypt Key is recommended. +The Verification Token is generated by default for source verification. However, we use Lark's officially recommended, more secure verification method, so this configuration can be ignored. + +## 4. Configure Callback URL + +After creating the publishing channel, click **Request URL** and copy the corresponding request URL. + +In the Lark console, click `Events & Callbacks` on the left sidebar, click the edit icon next to `Configure Subscription Method`, and paste the copied request URL into the input field. + +| | | | +| --- | --- | --- | +| ![Image](/imgs/feishu-bot-10.jpg) | ![Image](/imgs/feishu-bot-11.jpg) | ![Image](/imgs/feishu-bot-6.png) | + +## 5. Configure Bot Callback Events and Permissions + +* Add the `Receive Message` event + +On the `Events & Callbacks` page, click `Add Event`. + +Search for `Receive Message`, or directly search for `im.message.receive_v1`, find the `Receive Message v2.0` event, check it, and click `Confirm Add`. + +After adding the event, add two permissions: click the corresponding permission, and a popup will prompt you to add permissions. Add the two permissions shown above. + +| | | +| --- | --- | +| ![Image](/imgs/feishu-bot-7.png) | ![Image](/imgs/feishu-bot-8.png) | + +It is not recommended to enable the two "legacy versions" shown above -- use the new version permissions instead. +- If "Read messages users send to the bot in private chats" is enabled, private messages sent to the bot will be forwarded to FastGPT +- If "Receive @bot message events in group chats" is enabled, messages @mentioning the bot in group chats will be forwarded to FastGPT +- If (not recommended) "Get all messages in groups" is enabled, all group chat messages will be forwarded to FastGPT + +## 6. Configure Reply Message Permission + +In the Lark console, click `Permission Management` on the left sidebar, enter `send message` in the search box, find the `Send messages as the app` permission, and enable it. + +![](/imgs/feishu-bot-13.jpg) + +## 7. Publish the Bot + +Click `Version Management & Publishing` on the left side of the Lark console to publish the bot. + +![](/imgs/feishu-bot-12.jpg) + +You can then find your bot in the workspace. Next, add the bot to a group or chat with it privately. + +![Image](/imgs/feishu-bot-9.png) + +## FAQ + +### Sent a message but no response + +1. Check if the Lark bot callback URL, permissions, etc. are configured correctly. +2. Check FastGPT chat logs to see if there is a corresponding question record. +3. If there is a record but Lark does not respond, the bot is missing the required permissions. +4. If there is no record, the app may have encountered an error. Try the simplest bot first. (Lark bots cannot accept global variables, files, or image content as input) + +### How to start a new chat history + +Lark bot chat history chatId comes from several sources: +1. Private chat window +2. Individual topics in Lark topic groups +3. In group chats, composed of group ID + personal ID. + +To reset your chat history, send a `Reset` message to the bot (case-sensitive), and the bot will start a new chat history. diff --git a/document/content/docs/use-cases/external-integration/meta.en.json b/document/content/docs/use-cases/external-integration/meta.en.json new file mode 100644 index 0000000000..5888e299b8 --- /dev/null +++ b/document/content/docs/use-cases/external-integration/meta.en.json @@ -0,0 +1,11 @@ +{ + "title": "External FastGPT Integration", + "description": "Tutorial on external applications calling FastGPT features through various methods", + "pages": [ + "openapi", + "feishu", + "dingtalk", + "wecom", + "official_account" + ] +} diff --git a/document/content/docs/use-cases/external-integration/official_account.en.mdx b/document/content/docs/use-cases/external-integration/official_account.en.mdx new file mode 100644 index 0000000000..e524cc3e99 --- /dev/null +++ b/document/content/docs/use-cases/external-integration/official_account.en.mdx @@ -0,0 +1,128 @@ +--- +title: WeChat Official Account Integration +description: FastGPT WeChat Official Account Integration Tutorial +--- + +Starting from version 4.8.10, FastGPT commercial edition supports direct WeChat Official Account integration without additional APIs. + +**Note: Currently only verified official accounts are supported (both Service Accounts and Subscription Accounts).** + +## 1. Create a Publishing Channel in FastGPT + +In FastGPT, select the app you want to integrate. On the _Publishing Channels_ page, create a new WeChat Official Account publishing channel and fill in the basic information. + +![Image](/imgs/offiaccount-1.png) + +## 2. Get AppID, Secret, and Token + +### 1. Log in to the WeChat Official Account Platform and select your account. + +Open the WeChat Official Account website: https://mp.weixin.qq.com + +**Only verified official accounts are supported. Unverified accounts are not currently supported.** + +Developers can apply for a WeChat Official Account test account from this link for testing. Test accounts work normally but cannot configure AES Key. + +![Image](/imgs/offiaccount-2.png) + +### 2. Enter the 3 parameters into the FastGPT configuration dialog. + +![Image](/imgs/offiaccount-3.png) + +## 3. Add FastGPT IP to IP Whitelist + +![Image](/imgs/offiaccount-4.png) + +Self-hosted users can check their own IP address. + +International edition users (cloud.fastgpt.io) can add the following IP whitelist: + +``` +35.240.227.100 +34.124.237.188 +34.143.240.160 +34.87.51.146 +34.87.79.202 +35.247.163.68 +34.87.102.86 +35.198.192.104 +34.126.163.205 +34.124.189.116 +34.143.149.171 +34.87.173.252 +34.142.157.52 +34.87.180.104 +34.87.20.189 +34.87.110.152 +34.87.44.74 +34.87.152.33 +35.197.149.75 +35.247.161.35 +``` + +China Mainland users (fastgpt.cn) can add the following IP whitelist: + +``` +47.97.1.240 +121.43.105.217 +121.41.178.7 +121.40.65.187 +47.97.59.172 +101.37.205.32 +120.55.195.90 +120.26.229.115 +120.55.193.112 +47.98.190.173 +112.124.41.79 +121.196.235.183 +121.41.75.88 +121.43.108.48 +112.124.12.6 +121.43.52.222 +121.199.162.43 +121.199.162.102 +120.55.94.163 +47.99.59.223 +112.124.46.5 +121.40.46.247 +120.26.145.73 +120.26.147.199 +121.43.125.163 +121.196.228.45 +121.43.126.202 +120.26.144.37 +``` + +## 4. Get AES Key and Select Encryption Mode + +![Image](/imgs/offiaccount-5.png) + +![Image](/imgs/offiaccount-6.png) + +1. Randomly generate an AES Key and enter it into the FastGPT configuration dialog. + +2. Select the encryption mode as Secure Mode. + +## 5. Get URL + +1. Confirm creation in FastGPT and get the URL. + +![Image](/imgs/offiaccount-7.png) + +2. Enter it in the URL field on the WeChat Official Account Platform, then submit and save. + +![Image](/imgs/offiaccount-8.png) + +## 6. Enable Server Configuration (Skip if already auto-enabled) + +![Image](/imgs/offiaccount-9.png) + +## 7. Start Using + +Now when users send messages to the official account, messages will be forwarded to FastGPT, and conversation results will be returned through the official account. + +## FAQ + +### How to start a new chat history + +To reset your chat history, send a `Reset` message to the bot (case-sensitive), and the bot will start a new chat history. diff --git a/document/content/docs/use-cases/external-integration/openapi.en.mdx b/document/content/docs/use-cases/external-integration/openapi.en.mdx new file mode 100644 index 0000000000..2cb0e7a60d --- /dev/null +++ b/document/content/docs/use-cases/external-integration/openapi.en.mdx @@ -0,0 +1,37 @@ +--- +title: Access App via API +description: Access FastGPT app via API +--- + +import { Alert } from '@/components/docs/Alert'; + +In FastGPT, you can create multiple API keys for each app to access the app's API endpoints. Each key can only access one app. For complete endpoint documentation, [see the Chat API reference](/docs/openapi/intro). + +## Get API Key + +Go to App -> "API Access", then click "API Key" to create a key. + + + Keep your key safe. Once the dialog is closed, you cannot copy the key again -- you can only create a new key and copy it. + + +![](/imgs/fastgpt-api1.jpg) + + + Tip: For security, you can set a quota or expiration time to prevent key abuse. + + +## Replace Variables in Third-Party Apps + +```bash +OPENAI_API_BASE_URL: http://localhost:3000/api (replace with your deployed domain) +OPENAI_API_KEY = the key obtained in the previous step +``` + +**[ChatGPT Next Web](https://github.com/Yidadaa/ChatGPT-Next-Web) Example:** + +![](/imgs/chatgptnext.png) + +**[ChatGPT Web](https://github.com/Chanzhaoyu/chatgpt-web) Example:** + +![](/imgs/chatgptweb.png) diff --git a/document/content/docs/use-cases/external-integration/wecom.en.mdx b/document/content/docs/use-cases/external-integration/wecom.en.mdx new file mode 100644 index 0000000000..3f93f04321 --- /dev/null +++ b/document/content/docs/use-cases/external-integration/wecom.en.mdx @@ -0,0 +1,72 @@ +--- +title: WeCom Bot Integration +description: FastGPT WeCom Bot Integration Tutorial +--- + +- Starting from version 4.12.4, FastGPT commercial edition supports direct WeCom bot integration without additional APIs. +- Starting from version 4.14.4, FastGPT cloud service edition supports WeCom intelligent bot integration through custom domain configuration. + +## 1. (Required for Cloud Service Edition) Configure Custom Domain + +WeCom requires intelligent bot message push addresses to use the enterprise's primary domain, so cloud service edition users must configure a custom domain before using WeCom bots. + +- [Configure Custom Domain](/docs/introduction/guide/team_permissions/customDomain) + +If you are a commercial edition user, continue using your enterprise domain. + +## 2. Create an Intelligent Bot + +### 2.1 Super Admin Login + +[Click to open WeCom Admin Console](https://work.weixin.qq.com/) + +### 2.2 Find the Intelligent Bot Entry + +On the "Security & Management" - "Management Tools" page, click "Intelligent Bot" (Note: Only the enterprise creator or super admin has permission to see this entry) + +![Image](/imgs/use-cases/external-integration/wecom/1.png) + +### 2.3 Select "API Mode Creation" for the Intelligent Bot + +On the create bot page, scroll down and click "API Mode Creation" + +![Image](/imgs/use-cases/external-integration/wecom/2.png) + +### 2.4 Get Key Credentials + +Randomly generate or manually enter Token and Encoding-AESKey, and record them + +![Image](/imgs/use-cases/external-integration/wecom/3.png) + +### 2.5 Create WeCom Bot Publishing Channel + +In FastGPT, select the Agent you want to use. On the Publishing Channels page, select "WeCom Bot" and click "Create" + +![Image](/imgs/use-cases/external-integration/wecom/4.png) + +### 2.6 Configure Publishing Channel Information + +Configure the publishing channel information. You need to enter the Token and AESKey recorded in step 2.4 (Token and Encoding-AESKey) + +![Image](/imgs/use-cases/external-integration/wecom/5.png) + +### 2.7 Copy Callback URL + +After clicking "Confirm", select your configured custom domain, copy the callback URL, and paste it back into the WeCom intelligent bot configuration page. + +![Image](/imgs/use-cases/external-integration/wecom/6.png) + +## 3. Use the Intelligent Bot + +In the WeCom platform's "Contacts", you can find the created bot and start sending messages + +![Image](/imgs/use-cases/external-integration/wecom/7.png) + +## FAQ + +### Sent a message but no response + +1. Check if the trusted domain is configured correctly. +2. Check if Token and Encoding-AESKey are correct. +3. Check FastGPT chat logs to see if there is a corresponding question record. +4. If there is no record, the app may have encountered an error. Try the simplest bot first. diff --git a/document/content/docs/use-cases/index.en.mdx b/document/content/docs/use-cases/index.en.mdx new file mode 100644 index 0000000000..8dcbaa4de8 --- /dev/null +++ b/document/content/docs/use-cases/index.en.mdx @@ -0,0 +1,8 @@ +--- +title: Use Cases +description: FastGPT Use Cases +--- + +import { Redirect } from '@/components/docs/Redirect'; + + diff --git a/document/content/docs/use-cases/meta.en.json b/document/content/docs/use-cases/meta.en.json new file mode 100644 index 0000000000..f20a1680dd --- /dev/null +++ b/document/content/docs/use-cases/meta.en.json @@ -0,0 +1,11 @@ +{ + "title": "Use Cases", + "description": "More information about FastGPT practical use cases", + "root": true, + "pages": [ + "---External Integration---", + "...external-integration", + "---Application Examples---", + "...app-cases" + ] +} diff --git a/document/data/doc-last-modified.json b/document/data/doc-last-modified.json index 2211e8b718..a654992a95 100644 --- a/document/data/doc-last-modified.json +++ b/document/data/doc-last-modified.json @@ -1,100 +1,195 @@ { + "document/content/docs/faq/app.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/faq/app.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/faq/chat.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/faq/chat.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/faq/dataset.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/faq/dataset.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/faq/error.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/faq/error.mdx": "2025-12-10T20:07:05+08:00", + "document/content/docs/faq/external_channel_integration.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/faq/external_channel_integration.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/faq/index.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/faq/index.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/faq/other.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/faq/other.mdx": "2025-08-04T22:07:52+08:00", + "document/content/docs/faq/points_consumption.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/faq/points_consumption.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/introduction/cloud.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/introduction/cloud.mdx": "2026-02-26T00:26:52+08:00", + "document/content/docs/introduction/commercial.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/introduction/commercial.mdx": "2025-09-21T23:09:46+08:00", + "document/content/docs/introduction/development/configuration.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/configuration.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/introduction/development/custom-models/bge-rerank.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/custom-models/bge-rerank.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/custom-models/chatglm2-m3e.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/custom-models/chatglm2-m3e.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/introduction/development/custom-models/chatglm2.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/custom-models/chatglm2.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/custom-models/m3e.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/custom-models/m3e.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/custom-models/marker.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/custom-models/marker.mdx": "2025-08-04T22:07:52+08:00", + "document/content/docs/introduction/development/custom-models/mineru.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/custom-models/mineru.mdx": "2025-09-17T18:33:31+08:00", + "document/content/docs/introduction/development/custom-models/ollama.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/custom-models/ollama.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/introduction/development/custom-models/xinference.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/custom-models/xinference.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/introduction/development/design/dataset.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/design/dataset.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/design/design_plugin.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/design/design_plugin.mdx": "2025-11-06T14:47:55+08:00", + "document/content/docs/introduction/development/docker.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/development/docker.mdx": "2026-02-13T11:35:13+08:00", + "document/content/docs/introduction/development/faq.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/development/faq.mdx": "2025-08-12T22:22:18+08:00", + "document/content/docs/introduction/development/intro.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/development/intro.mdx": "2026-02-12T18:02:02+08:00", + "document/content/docs/introduction/development/migration/docker_db.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/migration/docker_db.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/migration/docker_mongo.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/migration/docker_mongo.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/modelConfig/ai-proxy.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/modelConfig/ai-proxy.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/introduction/development/modelConfig/intro.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/modelConfig/intro.mdx": "2025-12-03T08:36:19+08:00", + "document/content/docs/introduction/development/modelConfig/one-api.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/modelConfig/one-api.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/modelConfig/ppio.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/modelConfig/ppio.mdx": "2025-09-29T11:52:39+08:00", + "document/content/docs/introduction/development/modelConfig/siliconCloud.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/introduction/development/modelConfig/siliconCloud.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/introduction/development/object-storage.en.mdx": "2026-02-26T17:44:00+08:00", "document/content/docs/introduction/development/object-storage.mdx": "2026-01-09T18:25:02+08:00", + "document/content/docs/introduction/development/proxy/cloudflare.en.mdx": "2026-02-26T17:44:00+08:00", "document/content/docs/introduction/development/proxy/cloudflare.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/proxy/http_proxy.en.mdx": "2026-02-26T17:44:00+08:00", "document/content/docs/introduction/development/proxy/http_proxy.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/proxy/nginx.en.mdx": "2026-02-26T17:44:00+08:00", "document/content/docs/introduction/development/proxy/nginx.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/development/sealos.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/introduction/development/sealos.mdx": "2026-02-26T16:29:03+08:00", + "document/content/docs/introduction/development/signoz.en.mdx": "2026-02-26T17:53:07+08:00", "document/content/docs/introduction/development/signoz.mdx": "2026-02-12T16:37:50+08:00", + "document/content/docs/introduction/guide/DialogBoxes/htmlRendering.en.mdx": "2026-02-26T17:53:07+08:00", "document/content/docs/introduction/guide/DialogBoxes/htmlRendering.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/DialogBoxes/quoteList.en.mdx": "2026-02-26T17:53:07+08:00", "document/content/docs/introduction/guide/DialogBoxes/quoteList.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/admin/sso.en.mdx": "2026-02-26T17:53:07+08:00", "document/content/docs/introduction/guide/admin/sso.mdx": "2026-01-05T20:53:39+08:00", + "document/content/docs/introduction/guide/admin/teamMode.en.mdx": "2026-02-26T17:53:07+08:00", "document/content/docs/introduction/guide/admin/teamMode.mdx": "2025-08-27T16:59:57+08:00", + "document/content/docs/introduction/guide/course/ai_settings.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/course/ai_settings.mdx": "2025-07-24T13:00:27+08:00", + "document/content/docs/introduction/guide/course/chat_input_guide.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/course/chat_input_guide.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/course/fileInput.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/course/fileInput.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/course/quick-start.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/course/quick-start.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/basic-mode.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/basic-mode.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/evaluation.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/evaluation.mdx": "2025-07-24T13:10:25+08:00", + "document/content/docs/introduction/guide/dashboard/gapier.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/gapier.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/intro.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/intro.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/mcp_server.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/mcp_server.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/mcp_tools.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/mcp_tools.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/ai_chat.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/ai_chat.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/content_extract.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/content_extract.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/coreferenceResolution.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/workflow/coreferenceResolution.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/custom_feedback.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/workflow/custom_feedback.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/dataset_search.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/dataset_search.mdx": "2025-07-24T13:00:27+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/document_parsing.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/workflow/document_parsing.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/form_input.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/form_input.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/http.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/http.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/knowledge_base_search_merge.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/workflow/knowledge_base_search_merge.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/laf.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/workflow/laf.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/loop.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/loop.mdx": "2025-09-17T22:29:56+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/question_classify.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/question_classify.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/reply.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/reply.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/sandbox.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/dashboard/workflow/sandbox.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/text_editor.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/text_editor.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/tfswitch.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/tfswitch.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/tool.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/tool.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/user-selection.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/user-selection.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/dashboard/workflow/variable_update.en.mdx": "2026-02-26T16:42:10+08:00", "document/content/docs/introduction/guide/dashboard/workflow/variable_update.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/knowledge_base/RAG.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/RAG.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/knowledge_base/api_dataset.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/api_dataset.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/knowledge_base/collection_tags.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/collection_tags.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/introduction/guide/knowledge_base/dataset_engine.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/dataset_engine.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/knowledge_base/lark_dataset.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/lark_dataset.mdx": "2025-09-17T17:40:47+08:00", + "document/content/docs/introduction/guide/knowledge_base/template.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/template.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/knowledge_base/third_dataset.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/third_dataset.mdx": "2025-07-24T13:00:27+08:00", + "document/content/docs/introduction/guide/knowledge_base/websync.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/websync.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/introduction/guide/knowledge_base/yuque_dataset.en.mdx": "2026-02-26T16:50:22+08:00", "document/content/docs/introduction/guide/knowledge_base/yuque_dataset.mdx": "2025-09-17T22:29:56+08:00", + "document/content/docs/introduction/guide/plugins/bing_search_plugin.en.mdx": "2026-02-26T17:53:07+08:00", "document/content/docs/introduction/guide/plugins/bing_search_plugin.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/plugins/dev_system_tool.en.mdx": "2026-02-26T17:53:07+08:00", "document/content/docs/introduction/guide/plugins/dev_system_tool.mdx": "2025-11-06T14:47:55+08:00", + "document/content/docs/introduction/guide/plugins/doc2x_plugin_guide.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/guide/plugins/doc2x_plugin_guide.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/plugins/google_search_plugin_guide.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/guide/plugins/google_search_plugin_guide.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/plugins/searxng_plugin_guide.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/guide/plugins/searxng_plugin_guide.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/plugins/upload_system_tool.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/guide/plugins/upload_system_tool.mdx": "2025-11-04T16:58:12+08:00", + "document/content/docs/introduction/guide/team_permissions/customDomain.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/guide/team_permissions/customDomain.mdx": "2025-12-10T20:07:05+08:00", + "document/content/docs/introduction/guide/team_permissions/invitation_link.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/guide/team_permissions/invitation_link.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/introduction/guide/team_permissions/team_roles_permissions.en.mdx": "2026-02-26T18:17:53+08:00", "document/content/docs/introduction/guide/team_permissions/team_roles_permissions.mdx": "2025-07-23T21:35:03+08:00", - "document/content/docs/introduction/index.en.mdx": "2026-02-26T16:29:03+08:00", + "document/content/docs/introduction/index.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/introduction/index.mdx": "2026-02-26T00:26:52+08:00", + "document/content/docs/openapi/app.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/openapi/app.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/openapi/chat.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/openapi/chat.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/openapi/dataset.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/openapi/dataset.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/openapi/index.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/openapi/index.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/openapi/intro.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/openapi/intro.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/openapi/share.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/openapi/share.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/protocol/index.en.mdx": "2026-02-26T17:32:58+08:00", "document/content/docs/protocol/index.mdx": "2025-07-30T15:38:30+08:00", "document/content/docs/protocol/open-source.en.mdx": "2025-08-05T23:20:39+08:00", "document/content/docs/protocol/open-source.mdx": "2025-08-05T23:20:39+08:00", @@ -102,109 +197,212 @@ "document/content/docs/protocol/privacy.mdx": "2025-12-15T23:36:54+08:00", "document/content/docs/protocol/terms.en.mdx": "2025-12-15T23:36:54+08:00", "document/content/docs/protocol/terms.mdx": "2025-12-15T23:36:54+08:00", - "document/content/docs/toc.en.mdx": "2026-02-26T16:29:03+08:00", + "document/content/docs/toc.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/toc.mdx": "2026-02-24T13:48:31+08:00", + "document/content/docs/upgrading/4-10/4100.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-10/4100.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-10/4101.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-10/4101.mdx": "2025-09-08T20:07:20+08:00", + "document/content/docs/upgrading/4-11/4110.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-11/4110.mdx": "2026-02-26T00:26:52+08:00", + "document/content/docs/upgrading/4-11/4111.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-11/4111.mdx": "2025-08-07T22:49:09+08:00", + "document/content/docs/upgrading/4-12/4120.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-12/4120.mdx": "2025-09-07T14:41:48+08:00", + "document/content/docs/upgrading/4-12/4121.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-12/4121.mdx": "2025-09-07T14:41:48+08:00", + "document/content/docs/upgrading/4-12/4122.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-12/4122.mdx": "2025-09-07T14:41:48+08:00", + "document/content/docs/upgrading/4-12/4123.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-12/4123.mdx": "2025-09-07T20:55:14+08:00", + "document/content/docs/upgrading/4-12/4124.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-12/4124.mdx": "2025-09-17T22:29:56+08:00", + "document/content/docs/upgrading/4-13/4130.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-13/4130.mdx": "2025-11-04T15:06:39+08:00", + "document/content/docs/upgrading/4-13/4131.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-13/4131.mdx": "2025-09-30T15:47:06+08:00", + "document/content/docs/upgrading/4-13/4132.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-13/4132.mdx": "2025-12-15T11:50:00+08:00", + "document/content/docs/upgrading/4-14/4140.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/4140.mdx": "2025-11-06T15:43:00+08:00", + "document/content/docs/upgrading/4-14/4141.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/4141.mdx": "2025-12-31T09:54:29+08:00", + "document/content/docs/upgrading/4-14/4142.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/4142.mdx": "2025-11-18T19:27:14+08:00", + "document/content/docs/upgrading/4-14/4143.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/4143.mdx": "2026-02-04T14:27:58+08:00", + "document/content/docs/upgrading/4-14/4144.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/4144.mdx": "2026-02-04T14:27:58+08:00", + "document/content/docs/upgrading/4-14/4145.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/4145.mdx": "2026-01-18T23:59:15+08:00", + "document/content/docs/upgrading/4-14/41451.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/41451.mdx": "2026-01-20T11:53:27+08:00", + "document/content/docs/upgrading/4-14/4146.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/4146.mdx": "2026-02-12T16:37:50+08:00", - "document/content/docs/upgrading/4-14/4147.mdx": "2026-02-24T19:54:14+08:00", + "document/content/docs/upgrading/4-14/4147.en.mdx": "2026-02-26T20:05:36+08:00", + "document/content/docs/upgrading/4-14/4147.mdx": "2026-02-26T18:14:55+08:00", + "document/content/docs/upgrading/4-14/4148.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-14/4148.mdx": "2026-02-25T18:28:16+08:00", + "document/content/docs/upgrading/4-8/40.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/40.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/41.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/41.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/42.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/42.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/421.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/421.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/43.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/43.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/44.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/44.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/441.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/441.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/442.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/442.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/445.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/445.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/446.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/446.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/447.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/447.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/45.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/45.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/451.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/451.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/452.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/452.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/46.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/46.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/461.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/461.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/462.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/462.mdx": "2025-08-04T22:07:52+08:00", + "document/content/docs/upgrading/4-8/463.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/463.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/464.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/464.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/upgrading/4-8/465.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/465.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/466.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/466.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/467.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/467.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/upgrading/4-8/468.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/468.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/469.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/469.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/upgrading/4-8/47.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/47.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/471.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/471.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/48.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/48.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/481.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/481.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4810.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4810.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4811.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4811.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4812.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4812.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4813.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4813.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4814.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4814.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4815.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4815.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/4816.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4816.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/4817.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4817.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4818.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4818.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4819.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4819.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/482.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/482.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4820.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4820.mdx": "2025-08-05T23:20:39+08:00", + "document/content/docs/upgrading/4-8/4821.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4821.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4822.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4822.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/4823.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/4823.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/483.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/483.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/484.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/484.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/485.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/485.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/486.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/486.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/487.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/487.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/488.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/488.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-8/489.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-8/489.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/490.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/490.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/upgrading/4-9/491.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/491.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/4910.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/4910.mdx": "2025-08-04T22:07:52+08:00", + "document/content/docs/upgrading/4-9/4911.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/4911.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/4912.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/4912.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/4913.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/4913.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/4914.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/4914.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/492.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/492.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/upgrading/4-9/493.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/493.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/494.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/494.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/495.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/495.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/496.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/496.mdx": "2025-08-04T22:07:52+08:00", + "document/content/docs/upgrading/4-9/497.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/497.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/498.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/498.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/4-9/499.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/4-9/499.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/upgrading/index.en.mdx": "2026-02-26T20:05:36+08:00", "document/content/docs/upgrading/index.mdx": "2025-08-02T19:38:37+08:00", + "document/content/docs/use-cases/app-cases/dalle3.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/app-cases/dalle3.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/use-cases/app-cases/english_essay_correction_bot.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/app-cases/english_essay_correction_bot.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/use-cases/app-cases/feishu_webhook.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/use-cases/app-cases/feishu_webhook.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/use-cases/app-cases/fixingEvidence.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/use-cases/app-cases/fixingEvidence.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/use-cases/app-cases/google_search.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/app-cases/google_search.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/use-cases/app-cases/lab_appointment.en.mdx": "2026-02-26T17:42:53+08:00", "document/content/docs/use-cases/app-cases/lab_appointment.mdx": "2025-12-10T20:07:05+08:00", + "document/content/docs/use-cases/app-cases/multi_turn_translation_bot.en.mdx": "2026-02-26T17:32:58+08:00", "document/content/docs/use-cases/app-cases/multi_turn_translation_bot.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/use-cases/app-cases/submit_application_template.en.mdx": "2026-02-26T18:38:22+08:00", "document/content/docs/use-cases/app-cases/submit_application_template.mdx": "2026-01-27T15:19:19+08:00", + "document/content/docs/use-cases/app-cases/translate-subtitle-using-gpt.en.mdx": "2026-02-26T18:38:22+08:00", "document/content/docs/use-cases/app-cases/translate-subtitle-using-gpt.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/use-cases/external-integration/dingtalk.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/external-integration/dingtalk.mdx": "2025-07-23T21:35:03+08:00", + "document/content/docs/use-cases/external-integration/feishu.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/external-integration/feishu.mdx": "2025-07-24T14:23:04+08:00", + "document/content/docs/use-cases/external-integration/official_account.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/external-integration/official_account.mdx": "2026-02-26T00:26:52+08:00", + "document/content/docs/use-cases/external-integration/openapi.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/external-integration/openapi.mdx": "2026-02-12T18:45:30+08:00", + "document/content/docs/use-cases/external-integration/wecom.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/external-integration/wecom.mdx": "2025-12-10T20:07:05+08:00", + "document/content/docs/use-cases/index.en.mdx": "2026-02-26T17:28:07+08:00", "document/content/docs/use-cases/index.mdx": "2025-07-24T14:23:04+08:00" } \ No newline at end of file diff --git a/document/middleware.ts b/document/middleware.ts index 9480575ffb..fb98b50723 100644 --- a/document/middleware.ts +++ b/document/middleware.ts @@ -57,7 +57,35 @@ export default function middleware(request: NextRequest) { } } - // Continue with i18n middleware + // Check if URL has a language prefix + const hasLangPrefix = i18n.languages.some( + (l) => pathname.startsWith(`/${l}/`) || pathname === `/${l}` + ); + + if (hasLangPrefix) { + // Save user's language preference to cookie when visiting a localized URL + const currentCookie = request.cookies.get('FD_LOCALE')?.value; + if (currentCookie !== lang) { + // @ts-expect-error - Fumadocs middleware signature mismatch + const response = i18nMiddleware(request) ?? NextResponse.next(); + // @ts-ignore + response.cookies.set('FD_LOCALE', lang, { + path: '/', + maxAge: 60 * 60 * 24 * 365 + }); + return response; + } + } else { + // No language prefix — check cookie for user's language preference + const cookieLocale = request.cookies.get('FD_LOCALE')?.value; + if (cookieLocale && i18n.languages.includes(cookieLocale)) { + const newUrl = new URL(`/${cookieLocale}${pathname}`, request.url); + newUrl.search = request.nextUrl.search; + return NextResponse.redirect(newUrl); + } + } + + // Continue with i18n middleware (falls back to Accept-Language detection) // @ts-expect-error - Fumadocs middleware signature mismatch return i18nMiddleware(request); }