FastGPT API接口调用教程｜一键部署

在大模型应用快速落地的过程中，很多团队都会遇到一个共同问题：模型能力有了，但如何快速搭建一个可用、可扩展、可接入业务系统的 AI 应用？
FastGPT 正是为了解决这一类问题而诞生的开源知识库问答与 AI 应用编排平台。它可以帮助开发者快速完成知识库构建、工作流编排、AI 对话应用发布，并通过 API 接口对外提供服务。

本文将围绕 FastGPT API接口调用教程 与 一键部署实践 展开，带你从环境准备、平台部署、应用创建、API Key 获取，到接口调用示例、常见问题排查，完整走通 FastGPT 的使用流程。

一、FastGPT 是什么？

FastGPT 是一个基于大语言模型的 AI 应用开发平台，常用于以下场景：

• 企业内部知识库问答
• 客服机器人
• 文档问答系统
• 私有化智能助手
• AI 工作流自动化
• 业务系统中的智能问答接口
• RAG 检索增强生成应用

它的核心能力包括：

1. 知识库管理
   支持上传文档、网页、文本等数据，并将内容向量化存储，供大模型检索使用。

2. AI 应用编排
   可以通过可视化方式配置提示词、模型、知识库、变量、插件和工作流。

3. API 接口调用
   应用创建完成后，可以通过标准接口供外部系统调用，例如网站、App、企业微信、钉钉、CRM、ERP 等。

4. 支持私有化部署
   可通过 Docker Compose 快速部署，适合企业内网或私有云环境使用。

二、为什么选择 FastGPT？

相比直接调用 OpenAI、通义千问、智谱、DeepSeek 等模型接口，FastGPT 的优势在于它不仅仅是一个模型调用工具，而是一个完整的 AI 应用平台。

1. 降低开发成本

如果从零开发一个知识库问答系统，通常需要处理：

• 文档解析
• 文本切分
• 向量化
• 向量数据库存储
• 检索召回
• Prompt 拼接
• 上下文管理
• API 封装
• 权限管理
• 前端聊天界面

FastGPT 已经内置了这些能力，开发者只需要进行配置，就能快速构建应用。

2. 适合业务系统集成

FastGPT 支持通过 API 调用创建好的 AI 应用，因此非常适合嵌入到现有系统中。例如：

• 在官网中接入智能客服
• 在管理后台中加入 AI 助手
• 在企业内部知识库中接入问答机器人
• 在工单系统中自动生成回复建议
• 在教育平台中提供智能答疑

3. 支持多模型接入

FastGPT 可以接入多种大模型服务，包括但不限于：

• OpenAI
• Azure OpenAI
• DeepSeek
• 通义千问
• 智谱 GLM
• Moonshot Kimi
• 百度文心一言
• 本地私有化模型

对于企业来说，这意味着可以根据成本、效果、合规要求灵活选择模型。

三、一键部署前的准备工作

在开始部署 FastGPT 之前，需要准备一台服务器。推荐配置如下：

如果你只是测试体验，2 核 4GB 的服务器通常也可以运行；如果要用于生产环境，建议使用更高配置，并单独部署数据库、向量数据库和对象存储。

四、安装 Docker 与 Docker Compose

FastGPT 推荐使用 Docker Compose 部署，因此需要先安装 Docker。

1. 更新系统依赖

sudo apt update
sudo apt upgrade -y

2. 安装 Docker

curl -fsSL https://get.docker.com | bash

安装完成后，检查 Docker 是否安装成功：

docker -v

如果能看到类似输出，说明安装成功：

Docker version 24.x.x

3. 安装 Docker Compose

新版 Docker 通常已经内置 Compose 插件，可以通过以下命令检查：

docker compose version

如果输出版本号，说明可直接使用。如果没有安装，可以根据系统环境安装 Docker Compose 插件。

4. 设置 Docker 开机启动

sudo systemctl enable docker
sudo systemctl start docker

五、FastGPT 一键部署流程

FastGPT 官方通常会提供 Docker Compose 部署配置。实际部署时，建议参考官方最新文档，因为镜像版本、环境变量可能会随着版本更新发生变化。

下面给出一个通用部署思路。

1. 创建部署目录

mkdir -p /opt/fastgpt
cd /opt/fastgpt

2. 获取部署文件

可以通过 Git 拉取官方项目：

git clone https://github.com/labring/FastGPT.git
cd FastGPT

如果你只需要部署文件，可以进入对应的部署目录，例如：

cd projects/app

不同版本目录结构可能略有差异，请以官方仓库说明为准。

3. 配置环境变量

FastGPT 部署通常需要配置以下内容：

• MongoDB 数据库连接
• PostgreSQL 或向量数据库连接
• 模型 API Key
• 系统访问地址
• 登录密钥
• 默认模型配置
• 文件存储配置

常见环境变量包括：

OPENAI_BASE_URL=https://api.openai.com/v1
CHAT_API_KEY=your_api_key
TOKEN_KEY=your_token_key
ROOT_KEY=your_root_key

如果使用 DeepSeek、通义千问等兼容 OpenAI 格式的接口，也可以将 OPENAI_BASE_URL 改成对应服务商的地址。

例如 DeepSeek：

OPENAI_BASE_URL=https://api.deepseek.com/v1
CHAT_API_KEY=sk-xxxxxxxx

需要注意的是，不同服务商对模型名称、接口地址、鉴权方式可能存在差异，配置时要结合模型服务商文档进行调整。

4. 启动服务

在包含 docker-compose.yml 文件的目录下执行：

docker compose up -d

查看容器运行状态：

docker ps

如果容器全部正常启动，就可以通过浏览器访问 FastGPT。

例如：

http://服务器IP:3000

如果你使用了 Nginx 反向代理，也可以绑定域名访问：

https://fastgpt.example.com

六、初始化 FastGPT 平台

访问 FastGPT 后，通常需要进行初始化设置，包括：

1. 创建管理员账号
2. 配置模型供应商
3. 配置默认对话模型
4. 配置向量模型
5. 测试模型连通性

1. 登录后台

使用部署时配置的管理员账号或初始化账号登录系统。

2. 配置模型

在模型配置中，需要确保至少配置两类模型：

• 对话模型：用于回答用户问题，例如 GPT-4、DeepSeek Chat、Qwen 等。
• 向量模型：用于知识库文本向量化，例如 text-embedding-3-small、bge-m3 等。

如果知识库问答效果不好，常见原因之一就是向量模型不匹配或检索配置不合理。

3. 创建知识库

进入知识库模块，可以新建一个知识库，例如：

企业产品手册知识库

然后上传文档，例如：

• PDF
• Word
• Markdown
• TXT
• Excel
• 网页文本

上传后系统会自动进行解析、分块、向量化。处理完成后，就可以在应用中引用该知识库。

七、创建 FastGPT 应用

FastGPT 的应用相当于一个可调用的 AI 服务。你可以创建一个简单对话应用，也可以创建带知识库检索的智能问答应用。

1. 新建应用

进入「应用」模块，点击新建应用。常见类型包括：

• 简单聊天应用
• 知识库问答应用
• 工作流应用
• 插件应用

如果你要做企业知识库问答，建议选择知识库问答或工作流模式。

2. 配置系统提示词

系统提示词会影响 AI 的回答风格和行为边界。例如：

你是一个专业的企业知识库助手。
请根据知识库内容回答用户问题。
如果知识库中没有相关信息，请明确说明“当前知识库中没有找到相关内容”，不要编造答案。
回答时保持简洁、准确、专业。

一个好的提示词可以显著提高问答质量，尤其是在企业应用场景下，应尽量要求模型基于知识库回答，避免幻觉。

3. 绑定知识库

在应用配置中选择之前创建好的知识库，并设置检索参数，例如：

• 检索数量
• 相似度阈值
• 是否启用重排模型
• 是否引用来源
• 是否混合检索

如果问题比较复杂，建议开启重排模型，以提升召回内容的准确性。

4. 调试应用

在 FastGPT 页面中输入问题进行测试，例如：

请介绍一下我们公司的售后服务政策。

如果应用能准确引用知识库内容回答，说明基本配置已经完成。

八、获取 FastGPT API Key

要通过外部系统调用 FastGPT 应用，需要获取 API Key。

通常操作流程如下：

1. 进入对应应用详情页
2. 找到「API 访问」或「发布」相关设置
3. 创建或复制 API Key
4. 记录应用 ID 或接口地址
5. 在业务系统中调用接口

API Key 非常重要，类似系统访问密码，不建议直接暴露在前端页面中。正确做法是：

• 前端请求自己的后端服务
• 后端保存 FastGPT API Key
• 后端再调用 FastGPT 接口
• 最后将结果返回给前端

这样可以避免 API Key 泄露。

九、FastGPT API 接口调用方式

FastGPT 的 API 通常兼容 OpenAI Chat Completions 格式，因此对于已经接入过 OpenAI 的开发者来说，上手成本非常低。

典型请求地址类似：

https://你的FastGPT域名/api/v1/chat/completions

或者：

http://服务器IP:3000/api/v1/chat/completions

具体地址需要根据部署方式和版本确定。

十、使用 curl 调用 FastGPT API

下面是一个基础的 curl 调用示例：

curl --location 'https://fastgpt.example.com/api/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_FASTGPT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "chatId": "test-chat-001",
  "stream": false,
  "detail": false,
  "messages": [
    {
      "role": "user",
      "content": "请介绍一下公司的售后服务政策"
    }
  ]
}'

参数说明：

如果调用成功，会返回模型生成的回答内容。

十一、Node.js 调用示例

如果你的业务系统使用 Node.js，可以使用 fetch 或 axios 调用 FastGPT API。

1. 使用 fetch

const apiKey = 'YOUR_FASTGPT_API_KEY';
const url = 'https://fastgpt.example.com/api/v1/chat/completions';

async function callFastGPT(question) {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatId: 'node-chat-001',
      stream: false,
      detail: false,
      messages: [
        {
          role: 'user',
          content: question
        }
      ]
    })
  });

  if (!response.ok) {
    throw new Error(`FastGPT API error: ${response.status}`);
  }

  const data = await response.json();
  console.log(data);
  return data;
}

callFastGPT('请总结一下产品的核心优势');

2. 使用 axios

import axios from 'axios';

const result = await axios.post(
  'https://fastgpt.example.com/api/v1/chat/completions',
  {
    chatId: 'axios-chat-001',
    stream: false,
    detail: false,
    messages: [
      {
        role: 'user',
        content: '如何申请售后服务？'
      }
    ]
  },
  {
    headers: {
      Authorization: 'Bearer YOUR_FASTGPT_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

console.log(result.data);

十二、Python 调用示例

Python 后端同样可以很方便地接入 FastGPT。

import requests

url = "https://fastgpt.example.com/api/v1/chat/completions"
api_key = "YOUR_FASTGPT_API_KEY"

payload = {
    "chatId": "python-chat-001",
    "stream": False,
    "detail": False,
    "messages": [
        {
            "role": "user",
            "content": "请说明一下退换货规则"
        }
    ]
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print("请求失败：", response.status_code, response.text)

在实际项目中，建议对接口调用增加异常处理、超时控制和日志记录，例如：

response = requests.post(
    url,
    json=payload,
    headers=headers,
    timeout=60
)

十三、流式输出调用

如果你希望像 ChatGPT 一样逐字输出，可以启用流式返回：

{
  "chatId": "stream-chat-001",
  "stream": true,
  "detail": false,
  "messages": [
    {
      "role": "user",
      "content": "请详细介绍一下 FastGPT 的优势"
    }
  ]
}

流式输出适合以下场景：

• 在线客服聊天窗口
• AI 助手对话页面
• 长文本生成
• 用户体验要求较高的交互场景

需要注意的是，流式输出通常采用 SSE 方式返回，前端或后端需要按流处理数据，而不是一次性等待完整 JSON。

十四、生产环境接入建议

FastGPT 部署完成并能调用 API 后，如果要进入生产环境，还需要关注安全性、稳定性和可维护性。

1. 使用 HTTPS

生产环境建议通过 Nginx 配置 HTTPS，避免 API Key 和用户数据明文传输。

2. API Key 不要暴露在前端

不要在浏览器 JavaScript 中直接写 FastGPT API Key。应通过后端中转调用。

3. 设置访问频率限制

可以在 Nginx、API 网关或后端服务中增加限流策略，防止接口被恶意刷爆。

4. 做好日志监控

建议记录：

• 请求时间
• 用户 ID
• chatId
• 问题内容
• 响应状态
• 耗时
• 错误信息

这些日志有助于排查问题和优化问答效果。

5. 定期更新知识库

知识库问答的准确性依赖数据质量。企业文档变更后，应及时更新知识库内容，避免用户获取过期答案。

十五、常见问题排查

1. API 返回 401 Unauthorized

常见原因：

• API Key 错误
• Authorization 格式不正确
• Key 已失效
• 调用了错误的应用接口

正确格式：

Authorization: Bearer YOUR_FASTGPT_API_KEY

2. API 返回 404

可能原因：

• 接口地址错误
• 反向代理路径配置错误
• FastGPT 服务未正常启动
• 版本接口路径发生变化

建议检查：

docker ps
docker logs 容器名称

3. 知识库没有命中内容

可能原因：

• 文档未完成向量化
• 问题表达和文档内容差异较大
• 相似度阈值设置过高
• 检索数量设置过少
• 向量模型效果不佳

可以尝试降低相似度阈值、增加检索数量，或优化文档切分方式。

4. 回答出现编造内容

可以从以下方面优化：

• 强化系统提示词
• 要求模型仅基于知识库回答
• 开启引用来源
• 调整检索参数
• 使用更强的模型
• 对高风险问题增加人工审核

5. 接口响应慢

可能原因：

• 模型服务响应慢
• 服务器配置较低
• 知识库检索耗时较长
• 网络访问模型供应商延迟高
• 返回内容过长

优化方式：

• 使用更快的模型
• 开启流式输出
• 优化知识库规模
• 配置缓存
• 升级服务器配置

十六、FastGPT 与业务系统集成方案

在企业项目中，推荐采用如下架构：

前端页面 / App / 企业微信
        ↓
业务后端服务
        ↓
FastGPT API
        ↓
大模型服务 + 知识库

这种架构的优势是：

• API Key 不暴露
• 可以做用户权限校验
• 可以记录业务日志
• 可以统一限流
• 可以对问题进行预处理
• 可以对答案进行后处理
• 可以结合企业账号体系

例如，一个企业客服系统中，用户在前端输入问题后，后端可以先判断用户身份，再调用 FastGPT。如果问题涉及订单、售后、发票等业务数据，还可以先查询数据库，再将相关数据作为上下文传给 FastGPT，最终返回更个性化的回答。

十七、部署完成后的优化方向

FastGPT 一键部署只是第一步，要真正让 AI 应用好用，还需要持续优化。

1. 优化知识库文档质量

建议文档内容结构清晰，避免大量重复、过期、无关信息。对于 FAQ 类内容，可以整理成问答格式，提高召回效果。

2. 合理设置文本分块

文本分块过大，会导致检索不精准；分块过小，又可能缺少上下文。可以根据文档类型调整分块策略。

3. 设计高质量提示词

提示词应明确角色、回答范围、输出格式和禁止行为。例如：

如果无法从知识库中找到答案，请不要猜测。
请使用中文回答。
回答应包含步骤说明。
涉及价格、合同、法律责任的问题，请提示用户联系人工客服确认。

4. 使用工作流增强能力

FastGPT 的工作流能力可以实现更复杂的业务逻辑，例如：

• 用户问题分类
• 多知识库路由
• 调用外部 HTTP 接口
• 数据库查询
• 结果格式化
• 人工客服转接

这让 FastGPT 不仅能做问答，还能成为业务自动化入口。

十八、总结

本文围绕 FastGPT API接口调用教程｜一键部署，完整介绍了 FastGPT 的部署、初始化、应用创建和 API 调用方法。

整体流程可以概括为：

1. 准备服务器环境
2. 安装 Docker 与 Docker Compose
3. 拉取 FastGPT 部署文件
4. 配置模型 API Key 和环境变量
5. 启动 FastGPT 服务
6. 创建知识库并上传文档
7. 创建 AI 应用并调试
8. 获取 API Key
9. 使用 curl、Node.js、Python 调用接口
10. 按生产环境要求进行安全和性能优化

对于开发者来说，FastGPT 最大的价值在于：它把知识库、模型调用、应用编排和 API 发布整合到了一起，让 AI 应用从 Demo 到上线变得更加高效。

如果你的目标是快速搭建一个可私有化部署、可接入业务系统、可扩展的 AI 问答平台，那么 FastGPT 是一个非常值得尝试的方案。通过一键部署和标准 API 调用，你可以在较短时间内完成从平台搭建到业务集成的全过程。