### Install Ollama on Windows

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/ollama

Download and run the Windows installer from the official Ollama website, then start the service from the command line.

```bash
ollama serve
```

--------------------------------

### Install Ollama on Linux

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/ollama

Install Ollama on Linux by downloading and executing the official installation script, then start the service.

```bash
curl https://ollama.com/install.sh | sh
ollama serve
```

--------------------------------

### Install Ollama on macOS

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/ollama

Install Ollama using Homebrew on macOS and then start the service.

```bash
brew install ollama
ollama serve
```

--------------------------------

### Install Dependencies and Run Application

Source: https://doc.fastgpt.io/zh-CN/self-host/dev

Install all dependencies at the root level, then navigate to the app project and run the development server. Initial compilation may be slow.

```bash
# 代码根目录下执行，会安装根 package、projects 和 packages 内所有依赖
# 如果提示 isolate-vm 安装失败，可以参考：https://github.com/laverdet/isolated-vm?tab=readme-ov-file#requirements
pwd # 应该在代码的根目录
pnpm i
cd projects/app
pnpm dev
```

--------------------------------

### Cross-Version Upgrade Example

Source: https://doc.fastgpt.io/zh-CN/self-host/upgrading/upgrade-intruction

For cross-version upgrades, it is recommended to upgrade incrementally, executing upgrade scripts for each version sequentially. Always back up your data before starting.

```markdown
1. Modify the image to 4.5, execute the upgrade script
2. Modify the image to 4.5.1, execute the upgrade script
3. Modify the image to 4.5.2, execute the upgrade script
4. Modify the image to 4.6, execute the upgrade script
5. .....
```

--------------------------------

### Run bge-rerank Model (Source Deployment)

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/bge-rerank

Execute the application script to start the bge-rerank model after installation and model download.

```bash
python app.py
```

--------------------------------

### Install Dependencies and Create New Tool

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/dev_system_tool

Install project dependencies using Bun and then use the provided script to create a new tool. This prepares the project for writing new tool code.

```bash
bun i
bun run new:tool
```

--------------------------------

### Start Development Environment with Docker Compose

Source: https://doc.fastgpt.io/zh-CN/self-host/dev

Navigate to the development directory and run Docker Compose to start FastGPT dependencies. Ensure any existing Docker instances are stopped to avoid port conflicts.

```bash
cd FastGPT/deploy/dev
docker compose up -d
```

--------------------------------

### Chat Start Authentication - Success

Source: https://doc.fastgpt.io/zh-CN/openapi/share

Example of a successful authentication request before starting a chat. The `authToken` and user's question are sent in the request body.

```curl
curl --location --request POST '{{host}}/shareAuth/start' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "[authToken]",
    "question": "用户问题",
}'
```

```json
{
  "success": true,
  "data": {
    "uid": "用户唯一凭证"
  }
}
```

--------------------------------

### Deploy FastGPT with Interactive Script

Source: https://doc.fastgpt.io/zh-CN/self-host/deploy/docker

Executes an interactive script to guide users through selecting deployment options, vector database versions, and IP addresses for FastGPT setup.

```bash
bash <(curl -fsSL https://doc.fastgpt.cn/deploy/install.sh)
```

--------------------------------

### Install Xinference with Transformers and vLLM Backends

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/xinference

Install Xinference with support for Transformers and vLLM inference engines. PyTorch and CUDA are automatically handled but may require manual installation for version compatibility.

```bash
pip install "xinference[transformers]"
pip install "xinference[vllm]"
pip install "xinference[transformers,vllm]"
```

--------------------------------

### Alibaba Cloud OSS Configuration Example

Source: https://doc.fastgpt.io/zh-CN/self-host/config/object-storage

Example environment variables for configuring Alibaba Cloud Object Storage Service (OSS). Note the OSS_ENDPOINT format and whether to enable CNAME or secure connections.

```bash
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
```

--------------------------------

### Install Dependencies

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/bge-rerank

Install the necessary Python packages for the bge-rerank model by running this command.

```bash
pip install -r requirements.txt
```

--------------------------------

### MinIO/AWS S3 Object Storage Configuration Example

Source: https://doc.fastgpt.io/zh-CN/self-host/config/object-storage

Example environment variables for configuring MinIO or AWS S3 compatible object storage. Ensure STORAGE_EXTERNAL_ENDPOINT is accessible by both server and client. When configured, download mode defaults to 'presigned'.

```bash
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_CDN_ENDPOINT=https://cdn.example.com
STORAGE_S3_ENDPOINT=http://127.0.0.1:9000
STORAGE_S3_FORCE_PATH_STYLE=true
STORAGE_S3_MAX_RETRIES=3
```

--------------------------------

### Tencent Cloud COS Configuration Example

Source: https://doc.fastgpt.io/zh-CN/self-host/config/object-storage

Example environment variables for configuring Tencent Cloud Object Storage (COS). Configure protocol, acceleration, and custom domain as needed.

```bash
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=
```

--------------------------------

### Tool Output Parameter Configuration Example

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/dev_system_tool

Defines the structure for tool output parameters, including their keys, value types, labels, and descriptions. This example shows the output for DALL-E 3, including the image link and potential system errors.

```json
{
  // ...
  versionList: [
    {
      // ...
      outputs: [
        {
          valueType: WorkflowIOValueTypeEnum.string,
          key: 'link',
          label: '图片访问链接',
          description: '图片访问链接'
        },
        {
          type: FlowNodeOutputTypeEnum.error,
          valueType: WorkflowIOValueTypeEnum.string,
          key: 'system_error',
          label: '错误信息'
        }
      ]
    }
  ],
}
```

--------------------------------

### Docker Deployment of Xinference

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/xinference

Use the official Xinference Docker image for a one-click installation and startup. Ensure Docker is installed on your machine.

```bash
docker run  -p 9997:9997 --gpus all xprobe/xinference:latest xinference-local -H 0.0.0.0
```

--------------------------------

### Install llama-cpp-python for CTransformers

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/xinference

Install the llama-cpp-python library with specific compilation flags for different hardware platforms when using the CTransformers backend.

```bash
CMAKE_ARGS="-DLLAMA_METAL=on" pip install llama-cpp-python
CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python
CMAKE_ARGS="-DLLAMA_HIPBLAS=on" pip install llama-cpp-python
```

--------------------------------

### Install Docker and Docker Compose on Linux/macOS

Source: https://doc.fastgpt.io/zh-CN/self-host/deploy/docker

Installs Docker and Docker Compose on Linux or macOS systems. Ensure you have curl installed. After installation, verify the versions.

```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~
```

--------------------------------

### Tool Input Parameter Configuration Example

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/dev_system_tool

Defines the structure for tool input parameters, specifying their keys, labels, allowed input types, value types, and descriptions for tool usage. This example is for DALL-E 3's prompt input.

```json
{
//...
  versionList: [
    {
      // 其他配置
      inputs: [
        {
          key: 'prompt',
          label: '绘图提示词',
          valueType: WorkflowIOValueTypeEnum.string,
          renderTypeList: [FlowNodeInputTypeEnum.reference, FlowNodeInputTypeEnum.input],
          toolDescription: '绘图提示词'
        }
      ],
    }
    // ...
  ]
}
```

--------------------------------

### Install Marker PDF Parser (Docker)

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/marker

Quickly install the Marker PDF parsing service using Docker. Ensure you have Docker and GPU support configured.

```bash
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
```

--------------------------------

### Secret Input Configuration Example

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/dev_system_tool

Defines the structure for configuring secret inputs, such as API keys or endpoints, for a tool. This example shows how to set up URL and authorization inputs for DALL-E 3.

```json
{
  // 其他配置
  secretInputConfig: [
    {
      key: 'url',
      label: 'Dalle3 接口基础地址',
      description: '例如：https://api.openai.com',
      inputType: 'input',
      required: true
    },
    {
      key: 'authorization',
      label: '接口凭证（不需要 Bearer）',
      description: 'sk-xxxx',
      required: true,
      inputType: 'secret'
    }
  ]
}
```

--------------------------------

### Local Development Workflow Summary

Source: https://doc.fastgpt.io/zh-CN/self-host/dev

A summary of the steps for local development, including dependency installation, configuration, and running the app.

```bash
1. 根目录: pnpm i
2. 复制 config.json -> config.local.json
3. 复制 .env.template -> .env.local
4. cd projects/app
5. pnpm dev
```

--------------------------------

### Chat Start Authentication - Failure (Identity)

Source: https://doc.fastgpt.io/zh-CN/openapi/share

Example of a failed authentication request before starting a chat due to an invalid identity token.

```json
{
  "success": false,
  "message": "身份验证失败"
}
```

--------------------------------

### Chat Start Authentication - Failure (Violation)

Source: https://doc.fastgpt.io/zh-CN/openapi/share

Example of a failed authentication request before starting a chat due to a violation (e.g., prohibited words).

```json
{
  "success": false,
  "message": "存在违规词"
}
```

--------------------------------

### Build System Tool Package

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/upload_system_tool

Use this command to package your system tool files into a `.pkg` format for uploading. Ensure you are in the fastgpt-plugin project directory.

```bash
bun run build:pkg
```

--------------------------------

### SSO Get User Info Failure Response

Source: https://doc.fastgpt.io/zh-CN/guide/admin/sso

Example of a failed response when fetching SSO user information.

```json
{
  "success": false,
  "message": "错误信息",
  "username": "",
  "avatar": "",
  "contact": ""
}
```

--------------------------------

### Toolset File Structure Example

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/dev_system_tool

Shows the file structure for a toolset, which is a collection of tools. It includes a 'children' directory for tools and common configuration files.

```text
children
└── tool // 这个里面的结构就和上面的 tool 一致，但是没有 README 和 assets 目录
config.ts
index.ts
logo.svg
README.md
assets/
package.json
```

--------------------------------

### SSO Get User Info Success Response

Source: https://doc.fastgpt.io/zh-CN/guide/admin/sso

Example of a successful response when fetching SSO user information.

```json
{
  "success": true,
  "message": "",
  "username": "fastgpt-123456789",
  "avatar": "https://example.webp",
  "contact": "+861234567890",
  "memberName": "成员名（非必填）"
}
```

--------------------------------

### Manually Execute Postinstall Script

Source: https://doc.fastgpt.io/zh-CN/self-host/dev

If automatic execution fails, manually run the postinstall.sh script to initialize ChakraUI theme types.

```bash
./scripts/postinstall.sh
```

--------------------------------

### SSO Get Auth URL Failure Response

Source: https://doc.fastgpt.io/zh-CN/guide/admin/sso

Example of a failed response when requesting the SSO redirect URL.

```json
{
   "success": false,
   "message": "错误信息",
   "authURL": ""
}
```

--------------------------------

### SSO Get Auth URL Success Response

Source: https://doc.fastgpt.io/zh-CN/guide/admin/sso

Example of a successful response when requesting the SSO redirect URL.

```json
{
  "success": true,
  "message": "",
  "authURL": "https://example.com/somepath/login/oauth?redirect_uri=https%3A%2F%2Ffastgpt.cn%2Flogin%2Fprovider%0A"
}
```

--------------------------------

### Initialize Project and Add Remotes

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/dev_system_tool

Initialize a new Git repository and add 'origin' (your fork) and 'upstream' (official repository) remotes. This is a prerequisite for managing your plugin development.

```bash
git init
git remote add origin git@github.com:[your-name]/fastgpt-plugin.git
git remote add upstream git@github.com:labring/fastgpt-plugin.git
```

--------------------------------

### JavaScript: HTTP Request for Weather Data

Source: https://doc.fastgpt.io/zh-CN/guide/build/workflow/nodes/sandbox-v2

This JavaScript example makes an HTTP GET request to a weather API using `SystemHelper.httpRequest`. It retrieves temperature and weather conditions for a specified city, with a 10-second timeout.

```javascript
async function main({city}){
    const res = await SystemHelper.httpRequest(
        `https://api.example.com/weather?city=${city}`,
        { method: 'GET', timeout: 10 }
    )
    
    return {
        temperature: res.data.temp,
        weather: res.data.condition
    }
}
```

--------------------------------

### Create Backup Directory on Host Machine

Source: https://doc.fastgpt.io/zh-CN/self-host/migration/docker_mongo

Create a backup directory on the host machine for data synchronization with the FastGPT container.

```bash
mkdir -p /fastgpt/data/backup
```

--------------------------------

### Install OrbStack on macOS

Source: https://doc.fastgpt.io/zh-CN/self-host/deploy/docker

Installs OrbStack on macOS using Homebrew, a recommended alternative for Docker and container management.

```bash
brew install orbstack
```

--------------------------------

### Deploy FastGPT with Interactive Script

Source: https://doc.fastgpt.io/zh-CN/self-host

Executes an interactive script to guide users through selecting deployment options, database versions, and IP addresses for FastGPT deployment. Requires a Linux, MacOS, or Windows WSL environment.

```bash
bash <(curl -fsSL https://doc.fastgpt.io/deploy/install.sh)
```

--------------------------------

### Tool Calling Response Example

Source: https://doc.fastgpt.io/zh-CN/self-host/troubleshooting/model-errors

This is an example of a response chunk from a tool-calling test, indicating successful tool invocation with `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
}
```

--------------------------------

### Tool Code Structure Example

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/dev_system_tool

Illustrates the standard file structure for a system tool within the fastgpt-plugin project. This includes source code, tests, configuration, and entry points.

```text
src // 源代码，处理逻辑
└── index.ts
test // 测试样例
└── index.test.ts
config.ts // 配置，配置工具的名称、描述、类型、图标等
index.ts // 入口，不要改这个文件
logo.svg // Logo，替换成你的工具的 Logo
README.md // （可选）README 文件，用于展示工具的使用说明和示例
assets/ // （可选）assets 目录，用于存放工具的资源文件，如图片、音频等
package.json // npm 包
```

--------------------------------

### System Plugin Entry Point and Logic

Source: https://doc.fastgpt.io/zh-CN/guide/build/tools/system-plugins/dev_system_tool

Implement the main processing logic for a system plugin in `index.ts`. This example defines input and output schemas using Zod and an asynchronous `tool` function that formats the current time.

```typescript
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<typeof InputType>): Promise<z.infer<typeof OutputType>> {
  const formatStr = props.formatStr || 'yyyy-MM-dd HH:mm:ss';

  return {
    time: format(new Date(), formatStr)
  };
}
```

--------------------------------

### Install Xinference with CTransformers Backend

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/xinference

Install Xinference and the ctransformers library for using GGML-based models on personal devices. This is recommended for Macbooks or personal computers.

```bash
pip install xinference
pip install ctransformers
```

--------------------------------

### Example Organization List Response

Source: https://doc.fastgpt.io/zh-CN/guide/admin/sso

An example JSON object representing a successful response for fetching the organization list. It shows a root department and a sub-department.

```json
{
  "success": true,
  "message": "",
   "orgList": [
      {
         "id": "od-125151515",
         "name": "根部门",
         "parentId": ""
      },
      {
         "id": "od-51516152",
         "name": "子部门",
         "parentId": "od-125151515"
      }
   ]
}
```

--------------------------------

### Start FastGPT Docker Containers

Source: https://doc.fastgpt.io/zh-CN/self-host/deploy/docker

Pulls necessary images and starts the FastGPT containers in detached mode. Ensure your docker-compose version is 2.17 or higher.

```bash
# Start containers
docker compose --profile prepull pull opensandbox-agent-sandbox-image opensandbox-execd-image opensandbox-egress-image && docker compose up -d
```

--------------------------------

### Upload Backup Archive to New Environment

Source: https://doc.fastgpt.io/zh-CN/self-host/migration/docker_mongo

Upload the compressed backup archive from the local machine to the designated backup directory in the new FastGPT environment.

```bash
scp -rfv [本地电脑路径]/Downloads/fastgpt/fastgptbackup-2024-05-03.tar.gz root@[新环境fastgpt服务器地址]:/Downloads/fastgpt/backup
```

--------------------------------

### Create Backup Directory for New Environment

Source: https://doc.fastgpt.io/zh-CN/self-host/migration/docker_mongo

Create a specific directory in the new FastGPT environment for storing backup files.

```bash
mkdir -p /fastgpt/mongobackup
```

--------------------------------

### Install Old Marker Version (Docker)

Source: https://doc.fastgpt.io/zh-CN/self-host/custom-models/marker

Install an older version of the Marker PDF parsing service using Docker for compatibility with FastGPT versions prior to v4.9.0.

```bash
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
```