agentic_huge_data_base / wiki
页面 Dify · 9 服务 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 9

9 · 服务 API（Service APIs）

应用编排与外部知识接入 · 本章是 Dify DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Dify 章节9 状态全文译文 模块接口与服务契约、测试、发布与运维、工作流与编排、系统架构
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Service APIs 上一章8.5 下一章9.1
源码线索
  • api/controllers/common/controller_schemas.py
  • api/controllers/console/app/audio.py
  • api/controllers/console/explore/audio.py
  • api/controllers/console/explore/conversation.py
  • api/controllers/console/explore/message.py
  • api/controllers/console/explore/saved_message.py
  • api/controllers/service_api/app/audio.py
  • api/controllers/service_api/app/conversation.py
  • api/controllers/service_api/app/message.py
  • api/controllers/web/audio.py
模块标签
  • 接口与服务契约
  • 测试、发布与运维
  • 工作流与编排
  • 系统架构
  • 界面与交互

中文译文

服务 API（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/langgenius/dify/9-service-apis
翻译时间：2026-05-27T08:44:21.947Z
翻译模型：deepseek-chat
原文字符数：10453
项目：Dify (dify)

---

服务 API

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

  • api/controllers/common/controller_schemas.py
  • api/controllers/console/app/audio.py
  • api/controllers/console/explore/audio.py
  • api/controllers/console/explore/conversation.py
  • api/controllers/console/explore/message.py
  • api/controllers/console/explore/saved_message.py
  • api/controllers/service_api/app/audio.py
  • api/controllers/service_api/app/conversation.py
  • api/controllers/service_api/app/message.py
  • api/controllers/web/audio.py
  • api/controllers/web/conversation.py
  • api/controllers/web/message.py
  • api/controllers/web/saved_message.py
  • api/core/app/layers/conversation_variable_persist_layer.py
  • api/core/app/task_pipeline/based_generate_task_pipeline.py
  • api/services/audio_service.py
  • api/services/conversation_service.py
  • api/services/conversation_variable_updater.py
  • api/services/message_service.py
  • api/services/saved_message_service.py
  • api/services/web_conversation_service.py
  • api/tests/unit_tests/controllers/test_conversation_rename_payload.py
  • api/tests/unit_tests/controllers/web/test_pydantic_models.py
  • web/app/components/develop/template/template.en.mdx
  • web/app/components/develop/template/template.ja.mdx
  • web/app/components/develop/template/template.zh.mdx
  • web/app/components/develop/template/template_advanced_chat.en.mdx
  • web/app/components/develop/template/template_advanced_chat.ja.mdx
  • web/app/components/develop/template/template_advanced_chat.zh.mdx
  • web/app/components/develop/template/template_chat.en.mdx
  • web/app/components/develop/template/template_chat.ja.mdx
  • web/app/components/develop/template/template_chat.zh.mdx
  • web/app/components/develop/template/template_workflow.en.mdx
  • web/app/components/develop/template/template_workflow.ja.mdx
  • web/app/components/develop/template/template_workflow.zh.mdx

本文档提供 Dify 服务 API 的高层次技术概述。这些端点使开发者能够将 Dify 的应用能力——包括聊天、文本生成和复杂工作流——集成到自己的产品中。

所有服务 API 均通过 Authorization: Bearer {API_KEY} 请求头使用 API-Key 认证方式进行身份验证 web/app/components/develop/template/template_chat.en.mdx:12-19。

---

API 架构与请求流程

服务 API 架构旨在通过统一的认证和响应交付机制，处理多种应用模式（聊天、补全、工作流）。

API 表面路由

Dify 通过基于 Flask 的控制器层路由请求。service_api 命名空间专门使用应用特定的 API 密钥处理外部集成，这与 Dify 仪表盘使用的 console_api 不同。

API 请求处理流程

graph TD
    subgraph "外部客户端"
        Client["客户端应用"]
    end

    subgraph "Dify API 层 [api/controllers/service_api/]"
        Auth["@validate_app_token<br/>wraps.py"]
        ChatCtrl["chat.py<br/>/chat-messages"]
        WfCtrl["workflow.py<br/>/workflows/run"]
        CompCtrl["completion.py<br/>/completion-messages"]
        MsgCtrl["message.py<br/>/messages"]
    end

    subgraph "服务与核心层"
        AppGen["AppGenerateService<br/>services/app_generate_service.py"]
        WfAppServ["WorkflowAppService<br/>services/workflow_app_service.py"]
        MsgServ["MessageService<br/>services/message_service.py"]
        ConvServ["ConversationService<br/>services/conversation_service.py"]
    end

    Client --> Auth
    Auth --> ChatCtrl
    Auth --> WfCtrl
    Auth --> CompCtrl
    Auth --> MsgCtrl

    ChatCtrl --> AppGen
    CompCtrl --> AppGen
    WfCtrl --> WfAppServ
    MsgCtrl --> MsgServ
    MsgServ --> ConvServ

来源： api/controllers/service_api/wraps.py:14-15，api/controllers/service_api/app/message.py:39-40，api/services/message_service.py:25-25

响应模式：流式与阻塞

Dify 支持两种主要响应模式，通过 response_mode 参数配置：

  • streaming（流式）：推荐用于大语言模型（LLM）交互。它使用服务器推送事件（SSE）在生成时逐块交付内容，产生"打字机"效果并防止超时 web/app/components/develop/template/template_chat.en.mdx:44-46。
  • blocking（阻塞）：仅在执行完成后返回完整响应。由于 Cloudflare 的限制，此模式受 100 秒超时限制，并且不支持 Agent 助手模式 web/app/components/develop/template/template_chat.en.mdx:47-49。

详情请参见 API 架构与请求流程。

---

API 分类

聊天与补全 API

聊天 API 通过 conversation_id 支持会话持久化，使大语言模型（LLM）能够在多轮对话中保持上下文 web/app/components/develop/template/template_chat.en.mdx:5-6。补全 API 是无状态的，适用于单轮任务，如摘要或翻译 web/app/components/develop/template/template.en.mdx:5-6。

  • 端点：POST /chat-messages，POST /completion-messages
  • 关键参数：query，inputs，user，files
  • 详情：详情请参见 聊天与补全 API。

来源： web/app/components/develop/template/template_chat.en.mdx:24-71，web/app/components/develop/template/template.en.mdx:24-68

工作流执行 API

此 API 执行已发布的工作流图。与聊天应用不同，工作流应用通常不基于会话 web/app/components/develop/template/template_workflow.en.mdx:5-6。

  • 端点：POST /workflows/run
  • 事件：返回一系列执行事件，包括 workflow_started、node_started、text_chunk 和 node_finished web/app/components/develop/template/template_workflow.en.mdx:91-138。
  • 详情：详情请参见 工作流执行 API。

来源： web/app/components/develop/template/template_workflow.en.mdx:24-29，web/app/components/develop/template/template_workflow.zh.mdx:91-119

文件上传与管理 API

支持多模态能力，允许用户上传文件（图片、文档、音频、视频），然后在消息请求中引用这些文件 web/app/components/develop/template/template_chat.en.mdx:58-65。

  • 端点：POST /files/upload
  • 传输方式：支持 local_file（通过 upload_file_id）和 remote_url web/app/components/develop/template/template_chat.en.mdx:66-70。
  • 详情：详情请参见 文件上传与管理 API。

来源： web/app/components/develop/template/template.zh.mdx:179-184，web/app/components/develop/template/template_chat.en.mdx:58-71

会话与反馈 API

提供交互生命周期的管理功能，包括检索消息历史记录，以及允许最终用户对模型响应提供反馈（喜欢/不喜欢）。

  • 端点：GET /messages，POST /messages/:message_id/feedbacks，GET /conversations api/controllers/service_api/app/message.py:39-117，api/controllers/service_api/app/conversation.py:138-151。
  • 分页：通过 first_id 或 last_id 支持无限滚动分页 api/services/conversation_service.py:35-47。
  • 详情：详情请参见 会话与反馈 API。

来源： api/controllers/service_api/app/message.py:39-82，api/services/conversation_service.py:162-179

高级聊天与智能体 API

对于使用"Agent"或"高级聊天"（基于工作流的聊天）模式的应用，API 提供细粒度的追踪和专门的事件，如 agent_thought 和 agent_message web/app/components/develop/template/template_chat.zh.mdx:121-139。

  • 事件：捕获工具调用、观察结果和 Agent 推理步骤 web/app/components/develop/template/template_chat.zh.mdx:127-136。
  • 详情：详情请参见 高级聊天与 Agent API。

---

客户端 SDK

Dify 提供官方 SDK，以简化常见语言的集成。

  • 语言：Python、Node.js 和 PHP。
  • 详情：详情请参见 客户端 SDK。

---

分布式追踪

所有执行 API 都支持可选的 trace_id，用于将 Dify 执行与外部监控系统关联。系统按以下优先级解析该 ID：

  1. HTTP 请求头 X-Trace-Id
  2. URL 查询参数 trace_id
  3. 请求体字段 trace_id

来源： web/app/components/develop/template/template_chat.en.mdx:80-85，web/app/components/develop/template/template_workflow.en.mdx:64-68