# ms-dify-client

**Repository Path**: glacierck/ms-dify-client

## Basic Information

- **Project Name**: ms-dify-client
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-15
- **Last Updated**: 2025-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dify API 客户端使用指南

## 概述
本项目提供了一个用于与 Dify API 交互的 Python 客户端库，支持同步和异步两种操作模式。通过该客户端，可以方便地调用 Dify 的各种功能，包括对话生成、内容补全、工作流执行等，并支持流式响应及任务中断功能。
更多API信息见官方文档：https://docs.dify.ai/api-reference/对话消息/发送对话消息

## 核心功能
- 同步客户端（`Client`）和异步客户端（`AsyncClient`）支持
- 工作流（Workflows）功能
- 聊天对话（Chat）功能 【待更新】
- 流式响应处理
- 任务中断（停止流式任务）功能
- 文本补全（Completion）功能 【待更新】
- 文件上传功能 【待更新】
- 消息反馈和建议功能 【待更新】

## 安装
```bash
pip install -r requirements.txt
```

## 快速开始

### 同步客户端示例
见[test_sync.py](test_sync.py)中的main_sync

### 异步客户端示例

见[test_sync.py](test_sync.py)中的main_async

## 停止流式任务

当需要中断正在进行的流式任务时，可以使用停止功能：
见[test_stop.py](test_stop.py)
### 停止任务

```python
# 启动流式任务并获取task_id
chat_req = models.ChatRequest(
    messages=[{"role": "user", "content": "请讲一个很长的故事"}],
    response_mode=models.ResponseMode.STREAMING,
    user="user-123"
)
stream_iterator = client.chat_messages(chat_req)
task_id = None

for event in stream_iterator:
    if event.task_id:
        task_id = event.task_id
        # 获取到task_id后，等待2秒停止任务
        time.sleep(2)
        break

# 停止任务
if task_id:
    stop_req = models.StopRequest(user="user-123")
    stop_response = client.stop_chat_messages(task_id, stop_req)
    print("停止结果:", "成功" if stop_response.success else "失败")
```

## 主要 API 参考

### 同步客户端（`Client`）主要方法

| 方法名 | 描述 |
|--------|------|
| `completion_messages` | 文本补全功能 |
| `stop_completion_messages` | 停止文本补全流式任务 |
| `chat_messages` | 聊天对话功能 |
| `stop_chat_messages` | 停止聊天流式任务 |
| `run_workflows` | 执行工作流 |
| `stop_workflows` | 停止工作流流式任务 |
| `upload_files` | 上传文件 |
| `feedback_messages` | 提交消息反馈 |
| `suggest_messages` | 获取消息建议 |

### 异步客户端（`AsyncClient`）主要方法

| 方法名 | 描述 | 对应同步方法 |
|--------|------|------------|
| `acompletion_messages` | 异步文本补全 | `completion_messages` |
| `astop_completion_messages` | 异步停止文本补全流式任务 | `stop_completion_messages` |
| `achat_messages` | 异步聊天对话 | `chat_messages` |
| `astop_chat_messages` | 异步停止聊天流式任务 | `stop_chat_messages` |
| `arun_workflows` | 异步执行工作流 | `run_workflows` |
| `astop_workflows` | 异步停止工作流流式任务 | `stop_workflows` |
| `aupload_files` | 异步上传文件 | `upload_files` |
| `afeedback_messages` | 异步提交消息反馈 | `feedback_messages` |
| `asuggest_messages` | 异步获取消息建议 | `suggest_messages` |

## 注意事项

1. 所有 API 调用需要有效的 `api_key`，请确保正确设置
2. 流式响应模式（`STREAMING`）适用于需要实时获取部分结果的场景
3. 阻塞模式（`BLOCKING`）会等待完整结果返回，适用于需要一次性获取全部结果的场景
4. 停止任务功能仅适用于流式任务，需要提供有效的 `task_id`
5. 所有用户标识（`user`）应保持一致，以便正确跟踪对话历史和任务

## 错误处理

API 调用可能会抛出异常，建议使用 `try-except` 块捕获并处理：

```python
try:
    response = client.chat_messages(chat_req)
except Exception as e:
    print(f"API 调用失败: {str(e)}")
```

异步调用同样适用：

```python
try:
    response = await client.achat_messages(chat_req)
except Exception as e:
    print(f"异步 API 调用失败: {str(e)}")
```