OpenWebUI 对外 HTTP 接口配置与调用详解

发起聊天请求

这里演示一个简单的非流式聊天调用。

请求参数说明：

请求示例：

{
  "model": "deepseek-r1:1.5b",
  "messages": [
    {
      "role": "user",
      "content": "你好啊"
    }
  ]
}

响应结果：

{
  "id": "deepseek-r1:1.5b-09322e4f-ba07-42fc-894c-c64424240670",
  "created": 1741313942,
  "model": "deepseek-r1:1.5b",
  "choices": [
    {
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop",
      "message": {
        "content": "\n\n你好！很高兴见到你，有什么我可以帮忙的吗？",
        "role": "assistant"
      }
    }
  ],
  "object": "chat.completion",
  "usage": {
    "response_token/s": 22.73,
    "prompt_token/s": 41.32,
    "total_duration": 890745200,
    "load_duration": 19290900,
    "prompt_eval_count": 5,
    "prompt_tokens": 5,
    "prompt_eval_duration": 121000000,
    "eval_count": 17,
    "completion_tokens": 17,
    "eval_duration": 748000000,
    "approximate_total": "0h0m0s",
    "total_tokens": 22,
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}

流式响应

在实际开发中，为了获得更好的用户体验，我们通常会开启流式响应。只需在请求体中将 stream 设置为 true。

请求示例：

{
  "model": "deepseek-r1:1.5b",
  "messages": [
    {
      "role": "user",
      "content": "什么是 java"
    }
  ],
  "stream": true
}

响应数据会以 SSE (Server-Sent Events) 格式分段返回，以 data: 开头，最后以 [DONE] 结束。例如：

data: {"id": "...", "choices": [{"delta": {"content": "的关键"}}], ...}
data: {"id": "...", "choices": [{"delta": {"content": "。"}}], ...}
data: [DONE]

关联知识库文件

如果在对话中需要引用特定文档，可以在请求中附带知识库文件或集合 ID。

指定知识文件：

{
  "model": "gpt-4-turbo",
  "messages": [
    {"role": "user", "content": "Explain the concepts in this document."}
  ],
  "files": [
    {"type": "file", "id": "your-file-id-here"}
  ]
}

指定知识集合：

{
  "model": "gpt-4-turbo",
  "messages": [
    {"role": "user", "content": "Provide insights on the historical perspectives covered in the collection."}
  ],
  "files": [
    {"type": "collection", "id": "your-collection-id-here"}
  ]
}

RAG 知识库集成

Retrieval Augmented Generation (RAG) 功能通过整合外部来源的数据来增强响应。以下说明知识库创建与数据上传的相关接口（默认请求头 Content-Type: application/json）。

1. 创建知识库

接口：POST /api/v1/knowledge/create

请求参数：

{
  "name": "知识库名称",
  "description": "知识库说明",
  "access_control": null
}

响应结果包含生成的知识库 ID：

{
  "id": "e13f471f-cc6c-4df1-9210-8eb586bf8b6b",
  "user_id": "e42bf055-03e4-421e-894d-c18a58b6b73d",
  "name": "test",
  "description": "for test",
  "data": null,
  "meta": null,
  "access_control": null,
  "created_at": 1741317031,
  "updated_at": 1741317031,
  "files": null
}

2. 上传知识库文件

接口：POST /api/v1/files/

注意：此接口需使用 multipart/form-data 格式上传二进制文件流。

响应结果：

{
  "id": "77cb080c-5de8-4ffb-9304-d658e44a4dfb",
  "user_id": "e42bf055-03e4-421e-894d-c18a58b6b73d",
  "hash": "93737981707e6327ca3adf45a7ae11bfd33bc7fcbb0de82c85c390efa1a2f01c",
  "filename": "日志.txt",
  "data": {
    "content": "文件上传内容"
  },
  "meta": {
    "name": "日志.txt",
    "content_type": "text/plain",
    "size": 5587,
    "data": {},
    "collection_name": "file-77cb080c-5de8-4ffb-9304-d658e44a4dfb"
  },
  "created_at": 1741317221,
  "updated_at": 1741317221
}

3. 关联知识库与文件

接口：POST /api/v1/knowledge/{knowledge_id}/file/add

其中 {knowledge_id} 对应第一步创建的 ID，file_id 对应第二步上传文件的 ID。

请求参数：

{
  "file_id": "77cb080c-5de8-4ffb-9304-d658e44a4dfb"
}

响应结果会更新知识库状态，显示已关联的文件列表。

此外，如果需要管理多轮会话，可以访问 /api/v1/chats/{chat_id}，该接口主要负责查询和新增会话，并通过 chat_id 关联到 /api/chat/completions。

如果不确定某些接口的具体行为，建议直接在浏览器打开调试窗口查看网络调用情况，这通常是排查问题最直接的方法。