9.5 · 会话与反馈 API（Conversation and Feedback APIs）

会话与反馈 API（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/langgenius/dify/9.5-conversation-and-feedback-apis

翻译时间：2026-05-27T08:44:27.654Z

翻译模型：deepseek-chat

原文字符数：14228

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

本文档记录了用于管理对话、检索消息历史、提交反馈以及访问相关元数据的 REST API 端点和内部服务逻辑。这些组件支持具有历史上下文的持久化聊天界面、用户情感收集以及 AI 生成的后续交互。

---

API 总览

对话和消息管理 API 提供了对用户交互持久化状态的访问。这些端点分为服务 API（面向外部开发者）、Web API（面向 Dify 的 Web 应用）和控制台 API（面向 Dify 仪表盘）。

核心 API 资源和控制器

以下 REST 资源通过服务 API 层暴露：

资源	控制器类	路由模式
消息列表	MessageListApi	GET /messages
消息反馈	MessageFeedbackApi	POST /messages/<uuid:message_id>/feedbacks
应用反馈	AppGetFeedbacksApi	GET /app/feedbacks
建议问题	MessageSuggestedApi	GET /messages/<uuid:message_id>/suggested
对话列表	ConversationApi	GET /conversations
对话详情	ConversationDetailApi	DELETE /conversations/<uuid:c_id>
对话重命名	ConversationRenameApi	POST /conversations/<uuid:c_id>/name
对话变量	ConversationVariablesApi	GET /conversations/<uuid:c_id>/variables

来源：api/controllers/service_api/app/message.py:39-175, api/controllers/service_api/app/conversation.py:138-254

对话和消息数据模型

下图将自然语言概念映射到代码库中使用的 SQLAlchemy 模型和数据库实体。

erDiagram
    "App (models.model.App)" ||--o{ "Conversation (models.model.Conversation)" : "拥有多个"
    "Conversation (models.model.Conversation)" ||--o{ "Message (models.model.Message)" : "包含"
    "Conversation (models.model.Conversation)" ||--o{ "ConversationVariable (models.model.ConversationVariable)" : "持久化状态"
    "Message (models.model.Message)" ||--o| "MessageFeedback (models.model.MessageFeedback)" : "用户评分"
    "Message (models.model.Message)" ||--o| "MessageAnnotation (models.model.MessageAnnotation)" : "管理员修正"
    "Message (models.model.Message)" ||--o{ "AgentThought (fields.conversation_fields.AgentThought)" : "推理步骤"

    "Conversation (models.model.Conversation)" {
        uuid id
        uuid app_id
        string from_source "api/console/web"
        uuid from_end_user_id
        string name "自动生成或自定义"
        json inputs "初始变量"
        boolean is_deleted
    }

    "Message (models.model.Message)" {
        uuid id
        uuid conversation_id
        string query "用户输入"
        string answer "大语言模型输出"
        integer message_tokens
        integer answer_tokens
        string status "normal/error/paused"
    }

    "MessageFeedback (models.model.MessageFeedback)" {
        uuid id
        string rating "like/dislike"
        string content "可选文本"
        string from_source "user/admin"
    }

    "ConversationVariable (models.model.ConversationVariable)" {
        uuid id
        uuid conversation_id
        string name
        string value_type
        text value
    }

来源：api/models/model.py:69-300, api/services/conversation_service.py:18-19, api/fields/conversation_fields.py:33-41, api/controllers/service_api/app/conversation.py:73-81

---

对话管理

列出和分页对话

端点： GET /conversations 服务： ConversationService.pagination_by_last_id

检索特定用户的对话列表。Dify 使用"无限滚动"分页模式，即使用当前集合的 last_id 来获取下一页。

实现细节： ConversationService 构建一个 SQLAlchemy 语句，通过 app_id、from_source（用于隔离 API 用户和控制台用户）以及用户 ID 进行过滤。它支持按 created_at 或 updated_at 排序 api/services/conversation_service.py:71-72。

# api/services/conversation_service.py:51-58
stmt = select(Conversation).where(
    Conversation.is_deleted == False,
    Conversation.app_id == app_model.id,
    Conversation.from_source == ("api" if isinstance(user, EndUser) else "console"),
    Conversation.from_end_user_id == (user.id if isinstance(user, EndUser) else None),
    Conversation.from_account_id == (user.id if isinstance(user, Account) else None),
    or_(Conversation.invoke_from.is_(None), Conversation.invoke_from == invoke_from.value),
)

来源：api/services/conversation_service.py:35-101, api/controllers/service_api/app/conversation.py:138-183

对话重命名和自动生成

端点： POST /conversations/:c_id/name 逻辑： ConversationService.rename

对话可以手动重命名或自动生成名称。自动生成功能使用对话的第一条消息作为上下文，让大语言模型生成一个简洁的标题。

1. 手动重命名：更新 Conversation 模型中的 name 字段，并设置 updated_at api/services/conversation_service.py:131-133。
2. 自动生成：调用 LLMGenerator.generate_conversation_name，传入第一条消息的查询内容 api/services/conversation_service.py:152-155。

来源：api/services/conversation_service.py:118-160, api/controllers/service_api/app/conversation.py:218-254

---

消息历史与内容

检索消息历史

端点： GET /messages 服务： MessageService.pagination_by_first_id

检索特定对话中的历史消息。与对话列表不同，消息历史通常使用 first_id 来获取更早的消息（在聊天界面中向上滚动）。

数据增强： Dify 在检索过程中调用 attach_message_extra_contents，以注入元数据，例如通过 ExecutionExtraContent 领域模型关联的检索到的知识片段或文件附件 api/services/message_service.py:54-65。

来源：api/services/message_service.py:68-125, api/controllers/service_api/app/message.py:39-80, api/controllers/console/app/message.py:169-200

消息反馈机制

端点： POST /messages/:message_id/feedbacks 模型： MessageFeedback

用户可以提交 like 或 dislike 评分。MessageService.create_feedback 中的逻辑处理以下情况：

• 如果不存在记录，则创建新记录。
• 更新现有评分。
• 如果评分设置为 None（撤销），则删除记录。

# api/services/message_service.py:195-199
if not rating and feedback:
    db.session.delete(feedback)
elif rating and feedback:
    feedback.rating = rating
    feedback.content = content

来源：api/services/message_service.py:179-200, api/controllers/service_api/app/message.py:82-118

---

建议问题

端点： GET /messages/:message_id/suggested 服务： MessageService.get_suggested_questions_after_answer

此功能根据上一条助手的回复生成后续问题。仅当在应用程序配置中启用此功能时才可用。

逻辑流程：

1. 验证消息存在且属于该对话 api/services/message_service.py:270-274。
2. 检查功能是否已禁用，如果禁用则抛出 SuggestedQuestionsAfterAnswerDisabledError 异常 api/services/message_service.py:277-278。
3. 调用 LLMGenerator.generate_suggested_questions 获取 AI 生成的后续问题 api/services/message_service.py:284-288。

来源：api/services/message_service.py:265-290, api/controllers/service_api/app/message.py:142-175

---

音频服务

Dify 提供语音转文本（ASR）和文本转语音（TTS）API，以支持语音交互。

功能	端点	服务方法
音频转文本	POST /audio-to-text	AudioService.transcript_asr
文本转音频	POST /text-to-audio	AudioService.transcript_tts

ASR 逻辑：在调用 SPEECH2TEXT 模型实例之前，验证文件大小（限制 30MB）和扩展名 api/services/audio_service.py:50-74。 TTS 逻辑：从应用程序功能中检索配置的语音，并调用 TTS 模型实例。它可以使用 stream_with_context 流式传输响应 api/services/audio_service.py:86-152。

来源：api/services/audio_service.py:31-165, api/controllers/web/audio.py:52-156

---

内部服务协调

下图展示了 service_api 控制器如何与核心服务交互以处理请求。

graph LR
    subgraph "控制器 (api/controllers/service_api/app/)"
        MC["message.py<br/>(MessageListApi)"]
        CC["conversation.py<br/>(ConversationApi)"]
        AC["audio.py<br/>(AudioApi)"]
    end

    subgraph "服务 (api/services/)"
        MS["MessageService"]
        CS["ConversationService"]
        AS["AudioService"]
    end

    subgraph "核心组件"
        LLMG["core.llm_generator.LLMGenerator"]
        DB["extensions.ext_database.db"]
        MM["core.model_manager.ModelManager"]
    end

    MC --> MS
    CC --> CS
    AC --> AS
    MS --> DB
    CS --> LLMG
    CS --> DB
    AS --> MM

来源：api/controllers/service_api/app/message.py:39-175, api/services/message_service.py:66-125, api/services/conversation_service.py:33-110, api/services/audio_service.py:64-67