Files
FastGPT/docSite/content/docs/development/openApi.md
2023-10-24 13:19:23 +08:00

18 KiB
Raw Blame History

title, description, icon, draft, toc, weight
title description icon draft toc weight
OpenAPI 使用API Key 使用) FastGPT OpenAPI 文档 api false true 512

基本配置

baseUrl: "https://fastgpt.run/api"
headers: {
    Authorization: "Bearer apikey"
}

如何获取 API Key

FastGPT 的 API Key 有 2 类,一类是全局通用的 key一类是携带了 AppId 也就是有应用标记的 key。

通用key 应用特定 key

接口

发起对话

{{% alert icon="🤖 " context="success" %}} 该接口 API Key 需使用应用特定的 key否则会报错。

有些包的 BaseUrl 需要添加 v1 路径,有些不需要,建议都试一下。 {{% /alert %}}

对话接口兼容GPT的接口!如果你的项目使用的是标准的GPT官方接口,可以直接通过修改 BaseUrlAuthorization 来访问 FastGpt 应用。

请求参数说明

  • headers.Authorization: Bearer apikey
  • chatId: string | undefined 。
    • 为 undefined 时(不传入),不使用 FastGpt 提供的上下文功能,完全通过传入的 messages 构建上下文。 不会将你的记录存储到数据库中,你也无法在记录汇总中查阅到。
    • 为非空字符串时,意味着使用 chatId 进行对话,自动从 FastGpt 数据库取历史记录,并使用 messages 数组最后一个内容作为用户问题。(请自行确保 chatId 唯一,长度不限制)
  • messages: 结构与 GPT接口 完全一致。
  • detail: 是否返回详细值(模块状态,响应的完整结果),stream模式下会通过event进行区分非stream模式结果保存在responseData中。
  • variables: 变量内容,一个对象,会替换{{key}}变量。在HTTP模块中会发给接口,可作为身份凭证等标识。

请求示例:

curl --location --request POST 'https://fastgpt.run/api/v1/chat/completions' \
--header 'Authorization: Bearer apikey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "chatId":"111",
    "stream":false,
    "detail": false,
    "variables": {
        "cTime": "2022/2/2 22:22"
    },
    "messages": [
        {
            "content": "导演是谁",
            "role": "user"
        }
    ]
}'

{{< tabs tabTotal="3" >}} {{< tab tabName="detail=false 响应" >}} {{< markdownify >}}

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}]}

{{< /markdownify >}} {{< /tab >}}

{{< tab tabName="detail=true 响应" >}} {{< markdownify >}}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":""},"index":0,"finish_reason":null}]}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"电"},"index":0,"finish_reason":null}]}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"影"},"index":0,"finish_reason":null}]}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"《"},"index":0,"finish_reason":null}]}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"铃"},"index":0,"finish_reason":null}]}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"芽"},"index":0,"finish_reason":null}]}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"。"},"index":0,"finish_reason":null}]}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":""},"index":0,"finish_reason":null}]}

event: answer
data: {"id":"","object":"","created":0,"choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

event: answer
data: [DONE]

event: appStreamResponse
data: [{"moduleName":"KB Search","price":1.2000000000000002,"model":"Embedding-2","tokens":6,"similarity":0.61,"limit":3},{"moduleName":"AI Chat","price":463.5,"model":"FastAI-4k","tokens":309,"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":"电影《铃芽之旅》的导演是新海诚。"}]}]

{{< /markdownify >}} {{< /tab >}}

{{< tab tabName="stream=false,detail=true 响应" >}} {{< markdownify >}}

{
    "responseData": [ // 不同模块的响应值, 不同版本具体值可能有差异,可先 log 自行查看最新值。
        {
            "moduleName": "KB 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
        }
    ]
}

{{< /markdownify >}} {{< /tab >}} {{< /tabs >}}

知识库

{{% alert icon="🤖 " context="success" %}} 此部分 API 需使用全局通用的 API Key。 {{% /alert %}}

如何获取知识库IDdatasetId 如何获取文件IDfile_id

知识库添加数据

{{< tabs tabTotal="4" >}} {{< tab tabName="请求示例" >}} {{< markdownify >}}

curl --location --request POST 'https://fastgpt.run/api/core/dataset/data/pushData' \
--header 'Authorization: Bearer apikey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "collectionId": "64663f451ba1676dbdef0499",
    "mode": "index",
    "prompt": "qa 拆分引导词index 模式下可以忽略",
    "billId": "可选。如果有这个值,本次的数据会被聚合到一个订单中,这个值可以重复使用。可以参考 [创建训练订单] 获取该值。",
    "data": [
        {
            "a": "test",
            "q": "1111",
            "file_id": "关联的文件ID/URL/manual/mark",
            "source": "来源名称"
        },
        {
            "a": "test2",
            "q": "22222"
        }
    ]
}'

{{< /markdownify >}} {{< /tab >}}

{{< tab tabName="参数说明" >}} {{< markdownify >}}

{
    "collectionId": "文件的ID参考上面的第二张图",
    "mode": "index | qa ", //  index 模式: 直接将 q 转成向量存起来a 直接入库。qa 模式: 只关注 data 里的 q将 q 丢给大模型,让其根据 prompt 拆分成 qa 问答对。  
    "prompt": "拆分提示词,需严格按照模板,建议不要传入。",
    "data": [
        {
            "q": "生成索引的内容index 模式下最大 tokens 为3000建议不超过 1000",
            "a": "预期回答/补充",
            "file_id": "如果推送数据到手动录入,这里可以留空; 如果希望关联到某个文件中需要填写对应文件的ID; 如果希望加入到手动标注中,可设置为: mark",
        },
        {
            "q": "生成索引的内容qa 模式下最大 tokens 为10000建议 8000 左右",
            "a": "预期回答/补充"
        }
    ]
}

{{< /markdownify >}} {{< /tab >}}

{{< tab tabName="响应例子" >}} {{< markdownify >}}

{
    "code": 200,
    "statusText": "",
    "data": {
        "insertLen": 1, // 最终插入成功的数量
        "overToken": [], // 超出 token 的
        "fileIdInvalid": [  // file_id 无效的
            {
                "a": "飞飞dsaf飞",
                "q": "测试是32否收到",
                "file_id": "32dwe"
            }
        ],
        "error": [] // 其他错误
    }
}

{{< /markdownify >}} {{< /tab >}}

{{< tab tabName="QA Prompt 模板" >}} {{< markdownify >}}

{{theme}} 里的内容可以换成数据的主题。默认为:它们可能包含多个主题内容

我会给你一段文本,{{theme}},学习它们,并整理学习成果,要求为:
1. 提出最多 25 个问题。
2. 给出每个问题的答案。
3. 答案要详细完整,答案可以包含普通文字、链接、代码、表格、公示、媒体链接等 markdown 元素。
4. 按格式返回多个问题和答案:

Q1: 问题。
A1: 答案。
Q2:
A2:
……

我的文本:"""{{text}}"""

{{< /markdownify >}} {{< /tab >}}

{{< /tabs >}}

搜索测试

{{< tabs tabTotal="2" >}} {{< tab tabName="请求示例" >}} {{< markdownify >}}

curl --location --request POST 'https://fastgpt.run/api/core/dataset/searchTest' \
--header 'Authorization: Bearer apiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datasetId": "知识库的ID",
    "text": "导演是谁"
}'

{{< /markdownify >}} {{< /tab >}}

{{< tab tabName="响应示例" >}} {{< markdownify >}}

返回 top12 结果

{
  "code": 200,
  "statusText": "",
  "data": [
    {
      "id": "5613327",
      "q": "该人有获奖情况吗?",
      "a": "该人获得过2020/07全国大学生服务外包大赛国家一等奖和2021/05国家创新创业计划立项的获奖情况。",
      "source": "余金隆简历.pdf",
      "score": 0.41556452839298963
    },
    ......
  ]
}

{{< /markdownify >}} {{< /tab >}}

{{< /tabs >}}

订单

创建训练订单

请求示例

curl --location --request POST 'https://fastgpt.run/api/common/bill/createTrainingBill' \
--header 'Authorization: Bearer {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw ''

响应结果

data 为 billId可用于 api 添加数据时进行账单聚合。

{
  "code": 200,
  "statusText": "",
  "message": "",
  "data": "65112ab717c32018f4156361"
}

免登录分享链接校验(内测中)

免登录链接配置中,增加了凭证校验服务器后,使用分享链接时会向服务器发起请求,校验链接是否可用,并在每次对话结束后,向服务器发送对话结果。下面以host来表示凭证校验服务器。服务器接口仅需返回是否校验成功即可,不需要返回其他数据,格式如下:

{
    "success": true,
    "message": "错误提示"
}

分享链接中增加额外 query

增加一个 query: authToken。例如

原始的链接:https://fastgpt.run/chat/share?shareId=648aaf5ae121349a16d62192
完整链接: https://fastgpt.run/chat/share?shareId=648aaf5ae121349a16d62192&authToken=userid12345

发出校验请求时候,会在body中携带 token={{authToken}} 的参数。

初始化校验

FastGPT 发出的请求

curl --location --request POST '{{host}}/shareAuth/init' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "sintdolore"
}'

对话前校验

FastGPT 发出的请求

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

对话结果上报

FastGPT 发出的请求

curl --location --request POST '{{host}}/shareAuth/finish' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "sint dolore",
    "responseData": [
        {
            "moduleName": "KB 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": "电影《铃芽之旅》的导演是新海诚。"
                }
            ]
        }
    ]
}'

响应值与 chat 接口相同,增加了一个 token。可以重点关注responseData里的值price 与实际价格的倍率为100000

此接口无需响应值

使用案例