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

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

应用编排与外部知识接入 · 聚焦本章的模块关系、源码依据与实现要点。

项目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

聊天与补全 API

相关源文件

本章引用的主要源码文件：

  • 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 命名空间的入口点到底层服务逻辑的请求流程。

消息处理流程
Dify · 消息处理流程 · 图 1
Dify · 消息处理流程 · 图 1

来源：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

对话实体与服务映射
Dify · 对话实体与服务映射 · 图 2
Dify · 对话实体与服务映射 · 图 2

来源：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