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

OpenWebUI 通过 HTTP 方式提供对外接口，使得开发者可以通过标准 HTTP 请求快速对接拥有 RAG 能力的模型基座。下面将介绍如何获取认证信息、基础对话调用以及知识库集成流程。

获取 API 密钥

OpenWebUI 使用 Bearer Token 机制对 API 请求进行身份验证。你可以在 OpenWebUI 的'设置 > 帐户'中获取 API 密钥，或者使用 JWT（JSON Web 令牌）进行身份验证。

注意：JWT 通常有时效性限制，而 API 密钥是永久有效的。每次请求都需要将 API Key 设置到 HTTP 请求头中：

Authorization: Bearer eyJhbGci***

API 使用说明

基础接口功能包括列出在 OpenWebUI 注册的模型和发起聊天请求。

列出已配置模型

接口作用	地址	方法
列出所有已配置的模型	/api/models	GET

请求示例：http://127.0.0.1:3000/api/models

响应结果：

{
  "data": [
    {
      "id": "deepseek-r1:1.5b",
      "name": "deepseek-r1:1.5b",
      "object": "model",
      "created": 1741313196,
      "owned_by": "ollama",
      "ollama": {
        "name": "deepseek-r1:1.5b",
        "model": "deepseek-r1:1.5b",
        "modified_at": "2025-02-26T09:59:46.3066414+08:00",
        "size": 1117322599,
        "digest": "a42b25d8c10a841bd24724309898ae851466696a7d7f3a0a408b895538ccbc96",
        "details": {
          "parent_model": "",
          "format": "gguf",
          "family": "qwen2",
          "families": ["qwen2"],
          "parameter_size": "1.8B",
          "quantization_level": "Q4_K_M"
        },
        "urls": []
      },
      "actions": []
    }
  ]
}

发起聊天请求

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

接口作用	地址	方法
调用后端模型进行聊天	/api/chat/completions	POST

请求参数说明：

参数	说明
model	从 /api/models 接口返回的模型 id
role	user=用户输入，assistant=AI 助手回复，system=系统设定，tool=工具调用返回值
content	提问内容

请求示例：

{
  "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。

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