运行查询

运行已通过创建查询令牌获取令牌的查询，并以 Server-Sent Events 流式返回回答。此接口以查询令牌作为凭据，不使用知识库 API 密钥。服务端在受理请求时校验令牌。

两步调用流程及流的读取方式，详见查询知识库。

哪些错误应当重试、错误详情各字段的含义，详见处理错误。

查询成功时，会先保存查询记录，再发送 answer.done。重复调用会再次运行查询。

1 min read

post/knowledge-fs/query-stream

Request example

curl --request POST \
  --url https://api.dify.ai/v1/knowledge-fs/query-stream \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Trace-ID: <string>' \
  --header 'Content-Type: application/json' \
  --data '{
  "activeDocumentIds": [],
  "activeEntityIds": [],
  "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
  "mode": "fast",
  "query": "What changed in the refund policy this quarter?"
}'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/query-stream"
headers = {
    "Authorization": "Bearer <token>",
    "X-Trace-ID": "<string>",
    "Content-Type": "application/json",
}
payload = {
    "activeDocumentIds": [],
    "activeEntityIds": [],
    "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
    "mode": "fast",
    "query": "What changed in the refund policy this quarter?"
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/query-stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'X-Trace-ID': '<string>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "activeDocumentIds": [],
    "activeEntityIds": [],
    "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
    "mode": "fast",
    "query": "What changed in the refund policy this quarter?"
  })
});

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/query-stream',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "activeDocumentIds": [],
  "activeEntityIds": [],
  "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
  "mode": "fast",
  "query": "What changed in the refund policy this quarter?"
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'X-Trace-ID: <string>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/knowledge-fs/query-stream"
	payload := strings.NewReader("{\n  \"activeDocumentIds\": [],\n  \"activeEntityIds\": [],\n  \"knowledgeSpaceId\": \"8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f\",\n  \"mode\": \"fast\",\n  \"query\": \"What changed in the refund policy this quarter?\"\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Trace-ID", "<string>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/knowledge-fs/query-stream"))
    .header("Authorization", "Bearer <token>")
    .header("X-Trace-ID", "<string>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"activeDocumentIds\": [],\n  \"activeEntityIds\": [],\n  \"knowledgeSpaceId\": \"8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f\",\n  \"mode\": \"fast\",\n  \"query\": \"What changed in the refund policy this quarter?\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/knowledge-fs/query-stream')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['X-Trace-ID'] = '<string>'
request['Content-Type'] = 'application/json'
request.body = '{
  "activeDocumentIds": [],
  "activeEntityIds": [],
  "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
  "mode": "fast",
  "query": "What changed in the refund policy this quarter?"
}'

response = http.request(request)
puts response.read_body

Response

<string>

{
  "code": "KNOWLEDGE_FS_INVALID_REQUEST",
  "error": "The Agent Knowledge Base request is invalid.",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK",
  "error": "The Agent Knowledge Base request is invalid.",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  },
  "mode": "fast"
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400,
  "violations": [
    {
      "field": [
        "knowledgeSpaceId"
      ],
      "type": "missing"
    }
  ]
}

{
  "code": "KNOWLEDGE_FS_ACCESS_DENIED",
  "error": "You do not have permission to perform this Agent Knowledge Base operation.",
  "failure": {
    "action": "contact_admin",
    "category": "authorization",
    "code": "KNOWLEDGE_FS_ACCESS_DENIED",
    "message": "You do not have permission to perform this Agent Knowledge Base operation.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "knowledge_fs_invalid_credential",
  "message": "Invalid Agent Knowledge Base service credential.",
  "status": 401
}

{
  "code": "KNOWLEDGE_FS_ACCESS_DENIED",
  "error": "You do not have permission to perform this Agent Knowledge Base operation.",
  "failure": {
    "action": "contact_admin",
    "category": "authorization",
    "code": "KNOWLEDGE_FS_ACCESS_DENIED",
    "message": "You do not have permission to perform this Agent Knowledge Base operation.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "KNOWLEDGE_FS_NOT_FOUND",
  "error": "The requested Agent Knowledge Base resource was not found.",
  "failure": {
    "category": "not_found",
    "code": "KNOWLEDGE_FS_NOT_FOUND",
    "message": "The requested Agent Knowledge Base resource was not found.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "QUERY_IMAGE_NOT_FOUND",
  "error": "The requested Agent Knowledge Base resource was not found.",
  "failure": {
    "category": "not_found",
    "code": "KNOWLEDGE_FS_NOT_FOUND",
    "message": "The requested Agent Knowledge Base resource was not found.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "not_found",
  "message": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.",
  "status": 404
}

{
  "code": "RETRIEVAL_DELETION_IN_PROGRESS",
  "error": "This Agent Knowledge Base is being deleted and cannot be searched.",
  "failure": {
    "category": "conflict",
    "code": "RETRIEVAL_DELETION_IN_PROGRESS",
    "message": "This Agent Knowledge Base is being deleted and cannot be searched.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "RETRIEVAL_EXECUTION_LEASE_LOST",
  "error": "The retrieval execution expired before it could finish. Run the query again.",
  "failure": {
    "action": "retry",
    "category": "conflict",
    "code": "RETRIEVAL_EXECUTION_LEASE_LOST",
    "message": "The retrieval execution expired before it could finish. Run the query again.",
    "retryPolicy": "manual",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "knowledge_fs_request_too_large",
  "message": "Agent Knowledge Base request is too large.",
  "status": 413
}

{
  "code": "KNOWLEDGE_FS_INTERNAL_ERROR",
  "error": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
  "failure": {
    "action": "contact_admin",
    "category": "internal",
    "code": "KNOWLEDGE_FS_INTERNAL_ERROR",
    "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
    "retryPolicy": "manual",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "knowledge_fs_upstream_unavailable",
  "message": "Agent Knowledge Base is unavailable.",
  "status": 502
}

{
  "code": "KNOWLEDGE_FS_UNAVAILABLE",
  "error": "Agent Knowledge Base is temporarily unavailable. Try again later.",
  "failure": {
    "action": "retry",
    "category": "dependency",
    "code": "KNOWLEDGE_FS_UNAVAILABLE",
    "message": "Agent Knowledge Base is temporarily unavailable. Try again later.",
    "retryPolicy": "manual",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "knowledge_fs_operation_unavailable",
  "message": "Agent Knowledge Base operation is not available.",
  "status": 503
}

post/knowledge-fs/query-stream

Authorization

Authorizationstringheaderrequired#

创建查询令牌返回的查询令牌，以 Authorization: Bearer {token} 形式发送。须在返回的 expires_at 之前使用，该时间最晚为签发后 60 秒。该令牌只能用于对该知识库调用「运行查询」。

在同一请求中发送 X-Trace-ID，值为「创建查询令牌」返回的 trace_id。

Headers

X-Trace-IDstringrequired#

创建查询令牌响应中的 trace_id，与令牌中的 trace_id 声明值相同。与令牌不一致的值会被拒绝并返回 403。参见查询知识库。

Body

application/json

activeDocumentIdsstring[]#

从返回的 request 对象复制。这些 ID 不会对检索到的内容进行筛选或排序。

Items: max 100

activeEntityIdsstring[]#

从返回的 request 对象复制。这些 ID 不会对检索到的内容进行筛选或排序。

Items: max 100

knowledgeSpaceIdstringrequired#

知识库的内部 ID，从创建查询令牌返回的 request 对象复制。必须与令牌一致，不一致会被拒绝并返回 403。

Length: min 1

modeenum<string>#

检索深度，从创建查询令牌返回的 request 对象复制。可传 null，表示使用知识库的默认深度。

Options:fastdeepresearchnull

querystringrequired#

要查询的问题。不能为空白，且不超过 16,384 个 UTF-8 字节。

Length: max 16000Pattern: \S

sessionIdstring#

会话 ID，从创建查询令牌返回的 request 对象复制。

Responses

text/event-stream

流已建立。无论请求发送的 Accept 是什么，后续事件都以 text/event-stream 返回。流建立之前，按 HTTP 错误处理失败；流建立之后，即使 HTTP 状态码为 200，收到 answer.error 事件也应按失败处理。

创建查询令牌获取查询记录列表