クエリを実行

クエリトークンを作成でトークンを発行したクエリを実行し、回答を Server-Sent Events としてストリーミングで返します。認証情報はナレッジベースの API キーではなく、クエリトークンです。トークンはリクエストの受け付け時に検証されます。

2 回の呼び出しの流れとストリームの読み方については、ナレッジベースへのクエリを参照してください。

再試行すべきエラーとエラー詳細の意味については、エラーの処理を参照してください。

クエリが成功すると、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 秒後）より前に使用してください。このトークンで認可されるのは、そのナレッジベースに対する「クエリを実行」だけです。

同じリクエストで、「クエリトークンを作成」が返した trace_id を X-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#

質問です。空白のみではないクエリを指定してください。また、UTF-8 で 16,384 バイトまでに制限されます。

Length: max 16000Pattern: \S

sessionIdstring#

セッション ID です。クエリトークンを作成の request オブジェクトからコピーします。

Responses

text/event-stream

ストリームが開きました。リクエストの Accept にかかわらず、イベントは text/event-stream として続きます。ストリームが開く前の失敗は、HTTP エラーとして処理してください。開いた後は、HTTP ステータスが 200 であっても answer.error イベントを失敗として処理してください。

クエリトークンを作成クエリ記録一覧を取得