OpenSource
/
ragflow
Слідкувати 4
В обрані 0
Форк 0
Код Проблеми 0 Запити на злиття 0 Релізи 33 Вікі Активність
Переглянути джерело

Docs: Update HTTP API reference with simplified response format and parameters (#9454) 

### What problem does this PR solve?

- Make `session_id` optional and add `inputs` parameter
- Remove deprecated `sync_dsl` parameter
- Update request/response examples to match current API behavior

### Type of change

- [x] Documentation Update
tags/v0.20.2
Liu An 2 місяці тому
джерело
5e8cd693a5
коміт
3d645ff31a
Аккаунт користувача з таким Email не знайдено
1 змінених файлів з 295 додано та 227 видалено
Розділений перегляд Показати статистику Diff
  1. 295
    227
      docs/references/http_api_reference.md

+ 295
- 227
docs/references/http_api_reference.md Переглянути файл

@@ -79,91 +79,71 @@ curl --request POST \
Stream:

```json
{
"id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
data:{
"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728",
"choices": [
{
"delta": {
"content": "This is a test. If you have any specific questions or need information, feel",
"content": "Hello! It seems like you're just greeting me. If you have a specific",
"role": "assistant",
"function_call": null,
"tool_calls": null
"tool_calls": null,
"reasoning_content": null
},
"finish_reason": null,
"index": 0,
"logprobs": null
}
],
"created": 1740543996,
"created": 1755084508,
"model": "model",
"object": "chat.completion.chunk",
"system_fingerprint": "",
"usage": null
}
// omit duplicated information
{"choices":[{"delta":{"content":" free to ask, and I will do my best to provide an answer based on","role":"assistant"}}]}
{"choices":[{"delta":{"content":" the knowledge I have. If your question is unrelated to the provided knowledge base,","role":"assistant"}}]}
{"choices":[{"delta":{"content":" I will let you know.","role":"assistant"}}]}
// the last chunk
{
"id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
"choices": [
{
"delta": {
"content": null,
"role": "assistant",
"function_call": null,
"tool_calls": null
},
"finish_reason": "stop",
"index": 0,
"logprobs": null
}
],
"created": 1740543996,
"model": "model",
"object": "chat.completion.chunk",
"system_fingerprint": "",
"usage": {
"prompt_tokens": 18,
"completion_tokens": 225,
"total_tokens": 243
}
}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " question or need information, feel free to ask, and I'll do my best", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " to assist you based on the knowledge base provided.", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": null, "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": "stop", "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": {"prompt_tokens": 5, "completion_tokens": 188, "total_tokens": 193}}

data:[DONE]
```

Non-stream:

```json
{
"choices":[
"choices": [
{
"finish_reason":"stop",
"index":0,
"logprobs":null,
"message":{
"content":"This is a test. If you have any specific questions or need information, feel free to ask, and I will do my best to provide an answer based on the knowledge I have. If your question is unrelated to the provided knowledge base, I will let you know.",
"role":"assistant"
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "Hello! I'm your smart assistant. What can I do for you?",
"role": "assistant"
}
}
],
"created":1740543499,
"id":"chatcmpl-3a9c3572f29311efa69751e139332ced",
"model":"model",
"object":"chat.completion",
"usage":{
"completion_tokens":246,
"completion_tokens_details":{
"accepted_prediction_tokens":246,
"reasoning_tokens":18,
"rejected_prediction_tokens":0
"created": 1755084403,
"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728",
"model": "model",
"object": "chat.completion",
"usage": {
"completion_tokens": 55,
"completion_tokens_details": {
"accepted_prediction_tokens": 55,
"reasoning_tokens": 5,
"rejected_prediction_tokens": 0
},
"prompt_tokens":18,
"total_tokens":264
"prompt_tokens": 5,
"total_tokens": 60
}
}
```


Failure:

```json
@@ -225,91 +205,74 @@ curl --request POST \
Stream:

```json
{
"id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
"choices": [
{
"delta": {
"content": "This is a test. If you have any specific questions or need information, feel",
"role": "assistant",
"function_call": null,
"tool_calls": null
},
"finish_reason": null,
"index": 0,
"logprobs": null
}
],
"created": 1740543996,
"model": "model",
data: {
"id": "5fa65c94-e316-4954-800a-06dfd5827052",
"object": "chat.completion.chunk",
"system_fingerprint": "",
"usage": null
}
// omit duplicated information
{"choices":[{"delta":{"content":" free to ask, and I will do my best to provide an answer based on","role":"assistant"}}]}
{"choices":[{"delta":{"content":" the knowledge I have. If your question is unrelated to the provided knowledge base,","role":"assistant"}}]}
{"choices":[{"delta":{"content":" I will let you know.","role":"assistant"}}]}
// the last chunk
{
"id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
"model": "99ee29d6783511f09c921a6272e682d8",
"choices": [
{
"delta": {
"content": null,
"role": "assistant",
"function_call": null,
"tool_calls": null
"content": "Hello"
},
"finish_reason": "stop",
"index": 0,
"logprobs": null
"finish_reason": null,
"index": 0
}
],
"created": 1740543996,
"model": "model",
"object": "chat.completion.chunk",
"system_fingerprint": "",
"usage": {
"prompt_tokens": 18,
"completion_tokens": 225,
"total_tokens": 243
}
]
}

data: {"id": "518022d9-545b-4100-89ed-ecd9e46fa753", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": "!"}, "finish_reason": null, "index": 0}]}

data: {"id": "f37c4af0-8187-4c86-8186-048c3c6ffe4e", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " How"}, "finish_reason": null, "index": 0}]}

data: {"id": "3ebc0fcb-0f85-4024-b4a5-3b03234a16df", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " can"}, "finish_reason": null, "index": 0}]}

data: {"id": "efa1f3cf-7bc4-47a4-8e53-cd696f290587", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " I"}, "finish_reason": null, "index": 0}]}

data: {"id": "2eb6f741-50a3-4d3d-8418-88be27895611", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " assist"}, "finish_reason": null, "index": 0}]}

data: {"id": "f1227e4f-bf8b-462c-8632-8f5269492ce9", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " you"}, "finish_reason": null, "index": 0}]}

data: {"id": "35b669d0-b2be-4c0c-88d8-17ff98592b21", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " today"}, "finish_reason": null, "index": 0}]}

data: {"id": "f00d8a39-af60-4f32-924f-d64106a7fdf1", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": "?"}, "finish_reason": null, "index": 0}]}

data: [DONE]
```

Non-stream:

```json
{
"choices":[
"choices": [
{
"finish_reason":"stop",
"index":0,
"logprobs":null,
"message":{
"content":"This is a test. If you have any specific questions or need information, feel free to ask, and I will do my best to provide an answer based on the knowledge I have. If your question is unrelated to the provided knowledge base, I will let you know.",
"role":"assistant"
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "Hello! How can I assist you today?",
"role": "assistant"
}
}
],
"created":1740543499,
"id":"chatcmpl-3a9c3572f29311efa69751e139332ced",
"model":"model",
"object":"chat.completion",
"usage":{
"completion_tokens":246,
"completion_tokens_details":{
"accepted_prediction_tokens":246,
"reasoning_tokens":18,
"rejected_prediction_tokens":0
"created": null,
"id": "17aa4ec5-6d36-40c6-9a96-1b069c216d59",
"model": "99ee29d6783511f09c921a6272e682d8",
"object": "chat.completion",
"param": null,
"usage": {
"completion_tokens": 9,
"completion_tokens_details": {
"accepted_prediction_tokens": 0,
"reasoning_tokens": 0,
"rejected_prediction_tokens": 0
},
"prompt_tokens":18,
"total_tokens":264
"prompt_tokens": 1,
"total_tokens": 10
}
}
```


Failure:

```json
@@ -999,7 +962,7 @@ Updates configurations for a specified document.

```bash
curl --request PUT \
--url http://{address}/api/v1/datasets/{dataset_id}/info/{document_id} \
--url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '
@@ -2929,12 +2892,8 @@ Asks a specified agent a question to start an AI-powered conversation.
- In streaming mode, not all responses include a reference, as this depends on the system's judgement.
- In streaming mode, the last message is an empty message:

```json
data:
{
"code": 0,
"data": true
}
```
[DONE]
```

:::
@@ -2949,10 +2908,9 @@ Asks a specified agent a question to start an AI-powered conversation.
- Body:
- `"question"`: `string`
- `"stream"`: `boolean`
- `"session_id"`: `string`
- `"session_id"`: `string`(optional)
- `"inputs"`: `object`(optional)
- `"user_id"`: `string`(optional)
- `"sync_dsl"`: `boolean` (optional)
- other parameters: `string`

:::info IMPORTANT
You can include custom parameters in the request body, but first ensure they are defined in the [Begin](../guides/agent/agent_component_reference/begin.mdx) agent component.
@@ -2960,7 +2918,7 @@ You can include custom parameters in the request body, but first ensure they are

##### Request example

- If the **Begin** component does not take parameters, the following code will create a session.
- If the **Begin** component does not take parameters.

```bash
curl --request POST \
@@ -2969,10 +2927,12 @@ curl --request POST \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data-binary '
{
"question": "Hello",
"stream": false,
}'
```

- If the **Begin** component takes parameters, the following code will create a session.
- If the **Begin** component takes parameters.

```bash
curl --request POST \
@@ -2980,10 +2940,32 @@ curl --request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data-binary '
{
"lang":"English",
"file":"How is the weather tomorrow?"
}'
{
"question": "Hello",
"stream": false,
"inputs": {
"line_var": {
"type": "line",
"value": "I am line_var"
},
"int_var": {
"type": "integer",
"value": 1
},
"paragraph_var": {
"type": "paragraph",
"value": "a\nb\nc"
},
"option_var": {
"type": "options",
"value": "option 2"
},
"boolean_var": {
"type": "boolean",
"value": true
}
}
}'
```

The following code will execute the completion process
@@ -3013,149 +2995,235 @@ curl --request POST \
- `false`: Disable streaming.
- `"session_id"`: (*Body Parameter*)
The ID of the session. If it is not provided, a new session will be generated.
- `"inputs"`: (*Body Parameter*)
Parameters specified in the **Begin** component.
- `"user_id"`: (*Body parameter*), `string`
The optional user-defined ID. Valid *only* when no `session_id` is provided.
- `"sync_dsl"`: (*Body parameter*), `boolean`
Whether to synchronize the changes to existing sessions when an agent is modified, defaults to `false`.
- Other parameters: (*Body Parameter*)
Parameters specified in the **Begin** component.

#### Response

success without `session_id` provided and with no parameters specified in the **Begin** component:

Stream:

```json
data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
"created_at": 1755083342,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"answer": "Hi! I'm your smart assistant. What can I do for you?",
"reference": {},
"id": "31e6091d-88d4-441b-ac65-eae1c055be7b",
"session_id": "2987ad3eb85f11efb2a70242ac120005"
}
"content": "Hello"
},
"session_id": "eaf19a8e783511f0b9b61a6272e682d8"
}

data:{
"event": "message",
"message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
"created_at": 1755083342,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"content": "!"
},
"session_id": "eaf19a8e783511f0b9b61a6272e682d8"
}

data:{
"code": 0,
"message": "",
"data": true
"event": "message",
"message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
"created_at": 1755083342,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"content": " How"
},
"session_id": "eaf19a8e783511f0b9b61a6272e682d8"
}

...

data:[DONE]
```

Success without `session_id` provided and with parameters specified in the **Begin** component:
Non-stream:

```json
data:{
{
"code": 0,
"message": "",
"data": {
"session_id": "eacb36a0bdff11ef97120242ac120006",
"answer": "",
"reference": [],
"param": [
{
"key": "lang",
"name": "Target Language",
"optional": false,
"type": "line",
"value": "English"
},
{
"key": "file",
"name": "Files",
"optional": false,
"type": "file",
"value": "How is the weather tomorrow?"
},
{
"key": "hhyt",
"name": "hhty",
"optional": true,
"type": "line"
"created_at": 1755083440,
"data": {
"created_at": 547061.147866385,
"elapsed_time": 2.595433341921307,
"inputs": {},
"outputs": {
"_created_time": 547061.149137775,
"_elapsed_time": 8.720310870558023e-05,
"content": "Hello! How can I assist you today?"
}
]
},
"event": "workflow_finished",
"message_id": "25807f94783611f095171a6272e682d8",
"session_id": "25663198783611f095171a6272e682d8",
"task_id": "99ee29d6783511f09c921a6272e682d8"
}
}
data:
```

Success with parameters specified in the **Begin** component:
Success without `session_id` provided and with parameters specified in the **Begin** component:

Stream:

```json
data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "0e273472783711f0806e1a6272e682d8",
"created_at": 1755083830,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"answer": "How",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": "Hello"
},
"session_id": "0e0d1542783711f0806e1a6272e682d8"
}

data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "0e273472783711f0806e1a6272e682d8",
"created_at": 1755083830,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"answer": "How is",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": "!"
},
"session_id": "0e0d1542783711f0806e1a6272e682d8"
}

data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "0e273472783711f0806e1a6272e682d8",
"created_at": 1755083830,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"answer": "How is the",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": " How"
},
"session_id": "0e0d1542783711f0806e1a6272e682d8"
}
data:{

...

data:[DONE]
```

Non-stream:

```json
{
"code": 0,
"message": "",
"data": {
"answer": "How is the weather",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
"created_at": 1755083779,
"data": {
"created_at": 547400.868004651,
"elapsed_time": 3.5037803899031132,
"inputs": {
"boolean_var": {
"type": "boolean",
"value": true
},
"int_var": {
"type": "integer",
"value": 1
},
"line_var": {
"type": "line",
"value": "I am line_var"
},
"option_var": {
"type": "options",
"value": "option 2"
},
"paragraph_var": {
"type": "paragraph",
"value": "a\nb\nc"
}
},
"outputs": {
"_created_time": 547400.869271305,
"_elapsed_time": 0.0001251999055966735,
"content": "Hello there! How can I assist you today?"
}
},
"event": "workflow_finished",
"message_id": "effdad8c783611f089261a6272e682d8",
"session_id": "efe523b6783611f089261a6272e682d8",
"task_id": "99ee29d6783511f09c921a6272e682d8"
}
}
```

Success with parameters specified in the **Begin** component:

Stream:

```json
data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "5b62e790783711f0bc531a6272e682d8",
"created_at": 1755083960,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"answer": "How is the weather tomorrow",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": "Hello"
},
"session_id": "979e450c781d11f095cb729e3aa55728"
}

data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "5b62e790783711f0bc531a6272e682d8",
"created_at": 1755083960,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"answer": "How is the weather tomorrow?",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": "!"
},
"session_id": "979e450c781d11f095cb729e3aa55728"
}

data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "5b62e790783711f0bc531a6272e682d8",
"created_at": 1755083960,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"answer": "How is the weather tomorrow?",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": " You"
},
"session_id": "979e450c781d11f095cb729e3aa55728"
}
data:{

...

data:[DONE]
```

Non-stream:

```json
{
"code": 0,
"message": "",
"data": true
"data": {
"created_at": 1755084029,
"data": {
"created_at": 547650.750818867,
"elapsed_time": 1.6227330720284954,
"inputs": {},
"outputs": {
"_created_time": 547650.752800839,
"_elapsed_time": 9.628792759031057e-05,
"content": "Hello! It appears you've sent another \"Hello\" without additional context. I'm here and ready to respond to any requests or questions you may have. Is there something specific you'd like to discuss or learn about?"
}
},
"event": "workflow_finished",
"message_id": "84eec534783711f08db41a6272e682d8",
"session_id": "979e450c781d11f095cb729e3aa55728",
"task_id": "99ee29d6783511f09c921a6272e682d8"
}
}
```


Писати Попередній перегляд
Завантаження…
Відмінити
Зберегти