Python 调用 Dify API 实现知识检索与前端溯源展示

1.3、注意事项

• files 字段仅在传入 file_id 时添加，允许无图时直接问答。
• upload_file 使用 with open 避免句柄泄漏，并在 multipart 表单里传 user。
• delete 可能返回 204/空 body，必须使用安全解析。
• 示例里用 ret_send、ret_delete 避免变量覆盖导致拿不到 answer。
• 若要流式输出，将 response_mode 改为 "streaming" 并按 SSE 处理返回。

1.4、适配其他项目的改动指引

• 如需在多线程/多协程环境复用：将会话 id 存储在线程上下文或显式传入。
• 若有多用户：实例化时传入不同 user 值；或在方法参数增加 user 覆盖。
• 如需支持多文件：在 send 中把 data["files"] 扩展为文件列表，并按 Dify 要求传 type/transfer_method/upload_file_id。
• 若要改为流式：封装一个 send_stream，使用 stream=True 并消费 SSE 事件。

二、代码部分

import os.path
import requests

class DifyChat:
    """ 一个极简的 Dify HTTP API 调用封装（适合快速验证流程）。
    你这里用到的核心接口：
    - POST /v1/chat-messages 发起一次对话消息（可选携带图片）
    - POST /v1/files/upload 上传文件，得到 upload_file_id（给 chat-messages 的 files 用）
    - DELETE /v1/conversations/{id} 删除会话（有的服务端会返回空 body）
    """
    def __init__(self, api_url, api_key, user="abc-123"):
        """ :param api_url: Dify 服务地址（到 /v1 这一层），例如 http://10.0.100.98/v1
        :param api_key: Dify 应用 API Key（通常以 app- 开头）
        :param user: 用于标识请求用户的字符串。Dify 多数接口需要这个字段用于配额/会话归属。 
        """
        self.api_url = api_url
        self.api_key = api_key
        self.user = user
        # JSON 请求通用 Header（upload_file 是 multipart，会单独传 headers）
        self.headers = {'Authorization': f'Bearer {self.api_key}', 'Content-Type': 'application/json'}

    @staticmethod
    def _safe_parse_response(response):
        """ 尽量把响应解析成 JSON。
        - 像 DELETE 这类接口，经常返回 204 No Content（空 body）
        - 或者返回纯文本/HTML 错误页（不是 JSON）
        因此这里做'兜底'，避免直接 response.json() 抛 JSONDecodeError。
        """
        try:
            # 204/205 等可能无 body
            if response.status_code in (204, 205) or not response.content:
                return {"status_code": response.status_code, "ok": response.ok, "text": ""}
            return response.json()
        except Exception:
            return {"status_code": response.status_code, "ok": response.ok, "text": response.text,}

    def create_chat(self, chat_name):
        """ 创建 chat（是否需要取决于你的 Dify 应用/版本；很多情况下直接用 chat-messages 即可）。 
        """
        url = f'{self.api_url}/chats/create'
        data = {'chat_name': chat_name}
        response = requests.post(url, json=data, headers=self.headers)
        return self._safe_parse_response(response)

    def send(self, message, file_id=None, conversation_id=""):
        """ 发送一条消息（文本问答），可选带图片。
        :param message: 用户问题/提示词（query）
        :param file_id: upload_file 接口返回的 id（即 upload_file_id）；不传则表示纯文本问答
        :param conversation_id: 继续同一个会话时传入；留空表示开启新会话
        """
        url = f'{self.api_url}/chat-messages'
        data = {
            # inputs: 给'工作流应用/带变量的应用'传入输入变量；纯聊天一般为空即可
            "inputs": {},
            # query: 你的提问文本
            "query": message,
            # blocking: 同步等待完整结果；如果你要流式输出，可改为 streaming（并按 SSE 解析）
            "response_mode": "blocking",
            # conversation_id: 传入就续聊，不传就新开一轮会话
            "conversation_id": conversation_id or "",
            # user: 用于标识请求用户
            "user": self.user
        }
        # 只有在传入 file_id 时才携带 files 字段（不传图就纯文本问答）
        # files 的含义：告诉 Dify'本次对话引用了哪些已上传文件'。
        if file_id:
            data["files"] = [
                {
                    # type: 文件类型，这里是 image
                    "type": "image",
                    # transfer_method: local_file 表示使用'先上传 /files/upload，再在此引用 upload_file_id'的方式
                    "transfer_method": "local_file",
                    # upload_file_id: /files/upload 返回的 id
                    "upload_file_id": file_id
                }
            ]
        response = requests.post(url, json=data, headers=self.headers)
        return self._safe_parse_response(response)

    def delete(self, conver_id):
        """ 删除会话。
        注意：服务端可能返回 204（空响应体），所以不能直接 response.json()。
        """
        url = f'{self.api_url}/conversations/{conver_id}'
        data = {"user": self.user}
        response = requests.delete(url, json=data, headers=self.headers)
        return self._safe_parse_response(response)

    def upload_file(self, file_path):
        """ 上传本地文件到 Dify，返回值中通常包含：{"id": "..."}。
        随后把这个 id 作为 send(..., file_id=...) 的 upload_file_id 来引用。
        """
        url = f'{self.api_url}/files/upload'
        # Dify 通常要求 multipart form 里带 user 字段
        data = {"user": self.user}
        headers = {'Authorization': f'Bearer {self.api_key}'}
        with open(file_path, 'rb') as f:
            files = {'file': ("a.jpg", f, 'image/jpg')}
        response = requests.post(url, files=files, data=data, headers=headers)
        return self._safe_parse_response(response)

# 示例
if __name__ == "__main__":
    # 你的 Dify 服务地址（到 /v1）
    api_url = "http://127.0.0.1/v1"
    # 你的应用 API Key
    api_key = "app-xxxxxxxxxxxxxxxxxxxx"
    # 你的提问 query
    query = "时空之战的主要人物有哪些？"
    # image_path 为空字符串或不存在文件时：纯文本问答
    # image_path 指向真实图片文件时：会先上传图片，再在对话里引用该图片
    image_path = ""
    # image_path = "./beiguangdeshudianta1.jpg"
    chat = DifyChat(api_url, api_key)
    if not os.path.exists(image_path):
        # 方式 1：不上传图片，纯文本问答
        ret_send = chat.send(query)
    else:
        # 方式 2：需要图片时才上传，并把 file_id 带到 send 里
        ret_upload = chat.upload_file(image_path)
        file_id = ret_upload["id"]
        ret_send = chat.send(query, file_id=file_id)
    # send 的返回里一般会有 message_id / conversation_id / answer 等字段
    message_id = ret_send.get("message_id")
    conver_id = ret_send.get("conversation_id")
    print(ret_send)
    # 如果你的应用正常返回 answer，这里会打印答案
    if isinstance(ret_send, dict) and "answer" in ret_send:
        print(ret_send["answer"])
    # 可选：删除会话（有的场景你不需要删，保留会话便于续聊）
    # 注意：delete 的返回可能是 204 空 body，因此 ret_delete 不一定包含 JSON 字段
    if conver_id:
        ret_delete = chat.delete(conver_id)
        print(ret_delete)

三、返回内容分析

ret_send 的返回全部内容如下：

{
  'event': 'message',
  'task_id': 'e50a0154-5523-4c1a-93de-ae45a2568d00',
  'id': 'c3f11257-cc16-4718-84f8-f5a550b38757',
  'message_id': 'c3f11257-cc16-4718-84f8-f5a550b38757',
  'conversation_id': '3a1f9dd3-97a0-4d6e-bf74-bae87754ab02',
  'mode': 'advanced-chat',
  'answer': '根据提供的知识内容，时空之战的主要人物包括：\n\n1. 大雄：故事的主角，原本性格懦弱、逃避责任，但在经历未来世界的战斗后实现内心成长。\n2. 哆啦 A 梦：大雄的好朋友，来自未来的机器猫，拥有众多神奇道具，是事件的关键推动者。\n3. 特兰克斯：来自未来的超级赛亚人，身披战甲，拥有强大战斗力，为拯救未来世界而寻求帮助。\n',
  'metadata': {
    'retriever_resources': [
      {
        'position': 1,
        'dataset_id': '04adf974-e176-4d80-8d56-9720718b2b37',
        'dataset_name': '时空之战_1',
        'document_id': '时空之战.md',
        'document_name': '时空之战.md',
        'data_source_type': None,
        'segment_id': None,
        'retriever_from': 'workflow',
        'score': 0.36003251935408387,
        'hit_count': None,
        'word_count': None,
        'segment_position': None,
        'index_node_hash': None,
        'content': '# 哆啦 A 梦与超级赛亚人：时空之战\n\n在一个寻常的午后，大雄依旧坐在书桌前发呆，作业堆得像山，连第一页都没动。...',
        'page': None,
        'doc_metadata': None
      },
      ...
    ],
    'usage': {
      'prompt_tokens': 22886,
      'completion_tokens': 413,
      'total_tokens': 23299,
      ...,
      'latency': 4.649309985339642
    }
  },
  'created_at': 1769582803
}

其中 answer 是需要展示的内容：

根据提供的知识内容，时空之战的主要人物包括：
1. 大雄：故事的主角，原本性格懦弱、逃避责任，但在经历未来世界的战斗后实现内心成长。
2. 哆啦 A 梦：大雄的好朋友，来自未来的机器猫，拥有众多神奇道具，是事件的关键推动者。
3. 特兰克斯：来自未来的超级赛亚人，身披战甲，拥有强大战斗力，为拯救未来世界而寻求帮助。

其中，知识检索的内容，存储在了 metadata 内，可用作前端对'知识检索'原文的追溯。

四、总结

通过这样一个简单的示例调用，展示了调用 Dify 服务的整个过程，尤其是与前后端人员的交互，清楚的知道了返回内容，便于展示需要。