agentic_huge_data_base / wiki
页面 Dify · 9.2 聊天与补全 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 9.2

9.2 · 聊天与补全 API（Chat and Completion APIs）

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

项目Dify 章节9.2 状态全文译文 模块接口与服务契约、工作流与编排、测试、发布与运维、界面与交互
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Chat and Completion APIs 上一章9.1 下一章9.3
源码线索
  • api/controllers/common/controller_schemas.py
  • api/controllers/console/app/advanced_prompt_template.py
  • api/controllers/console/app/audio.py
  • api/controllers/console/app/completion.py
  • api/controllers/console/app/conversation.py
  • api/controllers/console/app/conversation_variables.py
  • api/controllers/console/app/mcp_server.py
  • api/controllers/console/app/message.py
  • api/controllers/console/app/model_config.py
  • api/controllers/console/app/site.py
模块标签
  • 接口与服务契约
  • 工作流与编排
  • 测试、发布与运维
  • 界面与交互
  • 配置治理

中文译文

聊天与补全 API（中文译文）

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

---

聊天与补全 API

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • api/controllers/common/controller_schemas.py
  • api/controllers/console/app/advanced_prompt_template.py
  • api/controllers/console/app/audio.py
  • api/controllers/console/app/completion.py
  • api/controllers/console/app/conversation.py
  • api/controllers/console/app/conversation_variables.py
  • api/controllers/console/app/mcp_server.py
  • api/controllers/console/app/message.py
  • api/controllers/console/app/model_config.py
  • api/controllers/console/app/site.py
  • api/controllers/console/app/statistic.py
  • api/controllers/console/app/workflow_app_log.py
  • api/controllers/console/app/workflow_statistic.py
  • api/controllers/console/explore/audio.py
  • api/controllers/console/explore/completion.py
  • api/controllers/console/explore/conversation.py
  • api/controllers/console/explore/message.py
  • api/controllers/console/explore/saved_message.py
  • api/controllers/console/explore/workflow.py
  • api/controllers/service_api/app/audio.py
  • api/controllers/service_api/app/completion.py
  • api/controllers/service_api/app/conversation.py
  • api/controllers/service_api/app/message.py
  • api/controllers/service_api/app/workflow.py
  • api/controllers/web/audio.py
  • api/controllers/web/completion.py
  • api/controllers/web/conversation.py
  • api/controllers/web/message.py
  • api/controllers/web/saved_message.py
  • api/controllers/web/workflow.py
  • api/core/app/layers/conversation_variable_persist_layer.py
  • api/core/app/task_pipeline/based_generate_task_pipeline.py
  • api/services/advanced_prompt_template_service.py
  • api/services/app_model_config_service.py
  • api/services/audio_service.py
  • api/services/auth/api_key_auth_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/services/workflow/workflow_converter.py
  • api/services/workflow_app_service.py
  • api/tests/unit_tests/controllers/console/app/test_mcp_server_response.py
  • api/tests/unit_tests/controllers/service_api/app/test_workflow.py
  • api/tests/unit_tests/controllers/test_conversation_rename_payload.py
  • api/tests/unit_tests/controllers/web/test_pydantic_models.py

本文档详细介绍了聊天与补全消息 API，这些 API 使外部应用能够向 Dify 应用发送消息并接收 AI 生成的响应。它们是对话式 AI 和文本生成场景的主要端点。

概述

Dify 通过 Service API 提供两个主要的消息发送 API 供外部使用：

  • 聊天 API（POST /chat-messages）：用于具有会话持久化的对话式应用。支持对话历史、代理模式和工具调用。api/controllers/service_api/app/completion.py:178-180
  • 补全 API（POST /completion-messages）：用于无对话上下文状态的无状态文本生成。适用于翻译、摘要和内容生成。api/controllers/service_api/app/completion.py:82-83
  • 工作流 API（POST /workflows/run）：专门用于工作流应用，提供详细的节点级执行事件，不支持会话。api/controllers/service_api/app/workflow.py:13-16
聊天与补全 API 对比
特性聊天 API补全 API工作流 API
端点/chat-messages/completion-messages/workflows/run
会话持久化是（通过 conversation_id）否否
应用模式CHAT、AGENT_CHAT、ADVANCED_CHATCOMPLETIONWORKFLOW
标题生成支持 auto_generate_name不适用不适用

来源：api/controllers/service_api/app/completion.py:103-106、api/controllers/service_api/app/completion.py:178-185、api/controllers/service_api/app/workflow.py:17-23

API 请求流程

下图展示了从 service_api 命名空间的入口点到底层服务逻辑的请求流程。

消息处理流程
graph TB
    subgraph "自然语言空间"
        USER_INPUT["用户问题/查询"]
    end

    subgraph "代码实体空间"
        NS["service_api_ns（命名空间）"]
        AUTH["validate_app_token（装饰器）"]

        subgraph "控制器"
            CHAT_API["ChatApi（POST /chat-messages）"]
            COMP_API["CompletionApi（POST /completion-messages）"]
            WORKFLOW_API["WorkflowRunApi（POST /workflows/run）"]
        end

        subgraph "服务层"
            GEN_SVC["AppGenerateService"]
            MSG_SVC["MessageService"]
        end

        DB[("SQLAlchemy 模型：<br/>App、Message、Conversation、WorkflowRun")]
    end

    USER_INPUT --> NS
    NS --> AUTH
    AUTH --> CHAT_API
    AUTH --> COMP_API
    AUTH --> WORKFLOW_API

    CHAT_API --> GEN_SVC
    COMP_API --> GEN_SVC
    GEN_SVC --> MSG_SVC
    MSG_SVC --> DB

来源：api/controllers/service_api/app/completion.py:117-123、api/controllers/service_api/app/completion.py:205-211、api/services/app_generate_service.py:1-20、api/services/message_service.py:66-70

认证

所有 Service API 端点均使用 API 密钥认证。系统通过 @validate_app_token 装饰器验证令牌并获取关联的 App 和 EndUser 模型。该装饰器确保只有经过授权的客户端才能访问应用资源。

来源：api/controllers/service_api/wraps.py:14-15、api/controllers/service_api/app/completion.py:96-97、api/controllers/service_api/app/completion.py:186-187

聊天 API

聊天 API（POST /chat-messages）支持对话式应用。它支持基础助手、代理助手和高级聊天（基于工作流）。

请求体参数

载荷使用 ChatRequestPayload Pydantic 模型进行校验。

参数类型必填描述
querystring是用户输入/问题内容。
inputsdict是应用定义的变量值。
response_modestring否streaming（流式）或 blocking（阻塞）。
conversation_idstring否用于继续现有对话的 UUID。api/controllers/service_api/app/completion.py:57-57
fileslist[dict]否多模态输入（图片、文档等）。api/controllers/service_api/app/completion.py:55-55
auto_generate_namebool否自动生成对话标题。默认值：true。api/controllers/service_api/app/completion.py:59-59

来源：api/controllers/service_api/app/completion.py:52-61、api/controllers/service_api/app/completion.py:62-76

会话与对话管理

Dify 通过 Conversation 模型和 ConversationService 管理聊天状态。会话通过 conversation_id 进行标识。

对话生命周期
操作端点服务方法
列表GET /conversationsConversationService.pagination_by_last_id
重命名POST /conversations/{id}/nameConversationService.rename
删除DELETE /conversations/{id}ConversationService.delete
自动命名POST /conversations/{id}/nameConversationService.auto_generate_name

来源：api/controllers/service_api/app/conversation.py:165-173、api/services/conversation_service.py:118-125、api/services/conversation_service.py:138-140、api/services/conversation_service.py:182-183

对话实体与服务映射
graph LR
    subgraph "API 层"
        C_API["ConversationApi（controllers/service_api/app/conversation.py）"]
        M_API["MessageListApi（controllers/service_api/app/message.py）"]
    end

    subgraph "逻辑层"
        C_SVC["ConversationService（services/conversation_service.py）"]
        M_SVC["MessageService（services/message_service.py）"]
        LLM_GEN["LLMGenerator（core/llm_generator/llm_generator.py）"]
    end

    subgraph "数据库层"
        C_MODEL["Conversation（models/model.py）"]
        M_MODEL["Message（models/model.py）"]
        V_MODEL["ConversationVariable（models/model.py）"]
    end

    C_API --> C_SVC
    M_API --> M_SVC
    C_SVC --> C_MODEL
    C_SVC --> V_MODEL
    C_SVC -- "标题生成" --> LLM_GEN
    M_SVC --> M_MODEL

来源：api/controllers/service_api/app/conversation.py:138-151、api/services/conversation_service.py:33-47、api/services/conversation_service.py:152-155、api/services/message_service.py:66-76

音频与多模态 API

Dify 通过 Service API 中的专用端点支持语音转文本（ASR）和文本转语音（TTS）。

  • 音频转文本：POST /audio-to-text 使用 AudioService.transcript_asr 将上传的文件转换为文本。api/controllers/service_api/app/audio.py:33-43
  • 文本转音频：POST /text-to-audio 使用 AudioService.transcript_tts 将文本转换为语音。api/controllers/service_api/app/audio.py:66-78

来源：api/services/audio_service.py:32-33、api/services/audio_service.py:76-85

错误处理

API 使用标准 HTTP 状态码。控制器会捕获服务层异常并将其映射为适当的 HTTP 响应。

状态码错误类描述
400BadRequest参数校验失败（例如通过 Pydantic）。
401UnauthorizedAPI 令牌无效或缺失。
404NotFound资源（对话、消息）不存在。
429InvokeRateLimitError配额或速率限制已超出。
500InternalServerError意外的服务端故障。

来源：api/controllers/service_api/app/completion.py:133-145、api/controllers/service_api/app/message.py:76-79、api/controllers/service_api/app/workflow.py:17-23