agentscope-ai / agentscope-ai/agentscope-java
[Bug] Dify Cloud 检索接口 query 字段返回字符串,导致 DifyResponse 反序列化失败(kb_search 对 api.dify.ai 引用恒为空)
- Langage dominant
- Java
- Étoiles
- 5.6k
- Forks
- 1.3k
- Merge moyen
- 4 j 12 h
- PR mergées (30 j)
- 77
Description
## 背景
我们基于 agentscope-java `2.0.0-RC4` 构建了一套智能体平台,通过 `agentscope-extensions-rag-dify` 接入 Dify 知识库做 RAG 检索(`kb_search` 工具)。本地用 stub/mock 的 Dify 响应(`query` 写成对象形态)联调时一切正常;但一旦切到**真实的 Dify Cloud(api.dify.ai)**知识库,`kb_search` 就完全失效——检索结果与引用恒为空。
## 问题现象
- 对真实 Dify 知识库执行 `kb_search`(以及连接管理里的「连通测试」)时,后端抛 `Failed to deserialize DifyResponse`。
- 由于整个响应反序列化失败,检索到的 `records` 被整体丢弃,**知识库引用恒为空**,RAG 完全不可用。
- 本地 stub(把 `query` 写成对象)不暴露此问题,**只有连真实 Dify Cloud 才触发**,隐蔽性较强。
## 根因
`io.agentscope.core.rag.integration.dify.model.DifyResponse.Query` 把响应里的 `query` 字段建模为**对象**:
```java
public static class Query {
private String content; // 仅默认构造 + getter/setter
public String getContent() { return content; }
public void setContent(String content) { this.content = content; }
}
```
它期望 `query` 是 `{"content":"..."}`。但**真实 api.dify.ai 返回的 `query` 是裸字符串**。Jackson 无法把一个 JSON string 构造成 `Query` 对象,于是整个 `DifyResponse` 反序列化失败,连带丢弃所有 records。
## 我们的发现 / 排查过程(供参考)
1. 最初怀疑是依赖版本或本地构建问题,逐一排除后,把范围锁定到 Dify 响应的反序列化环节。
2. 我们翻了 Dify 官方 GitHub 源码 `api/services/hit_testing_service.py`,发现它构造响应时 `query` 是**对象** `{"content": query}`(`compact_retrieve_response` / `compact_external_retrieve_response`)。这一度让我们以为 agentscope 的 DTO 没问题、是别处的锅。
3. 为了确认,我们**实际调用了一次真实的 api.dify.ai 检索接口**,结果发现线上服务返回的 `query` 是**裸字符串**,与 GitHub `main` 源码不一致(推测是 Dify Cloud 的部署版本与 main 分支存在差异,或外部 Service API 走了与 hit-testing 不同的序列化路径)。**最终以线上实测为准。**
## 复现步骤
调用 Dify Cloud 检索接口:
```
POST https://api.dify.ai/v1/datasets/{dataset_id}/retrieve
Authorization: Bearer {api_key}
Content-Type: application/json
{"query":"ping","retrieval_model":{"search_method":"semantic_search","top_k":1}}
```
实测响应(HTTP 200,已脱敏):
```json
{
"query": "ping",
"records": [
{ "segment": { "id": "...", "content": "...", "position": 1, "document": { "id": "...", "name": "..." } }, "score": 0.9 }
]
}
```
注意顶层 `query` 是字符串 `"ping"`,**不是** `{"content":"ping"}`。
## 影响范围
所有使用 **Dify Cloud(api.dify.ai)** 知识库的 agentscope-java 用户,`kb_search` 检索结果与引用恒为空,RAG 功能不可用。经核实 `2.0.0-RC4` 与最新 `main` 分支均未修复。
## 建议修复
给 `DifyResponse.Query` 增加一个委托模式(DELEGATING)的 `@JsonCreator`,并**保留**默认构造 + setter,使其同时兼容「字符串」与「对象」两种形态:
```java
@JsonCreator(mode = JsonCreator.Mode.DELEGATING)
public static Query fromString(String content) {
Query query = new Query();
query.setContent(content);
return query;
}
```
裸字符串走该工厂、对象形态走默认 bean,两种都不再报错。我们本地已用此方案验证可行(兼容两种 payload),乐意提交 PR。
## 最后
顺便恳请官方**加快 2.0 正式版、尤其是知识库 / RAG 模块的发布节奏** 🙏。目前还停留在 RC 阶段,而知识库是大量落地场景的刚需,希望能把这类「与真实 Dify Cloud 对接」的兼容性问题修好后尽快 GA 上架,让大家能放心把知识库能力用于生产环境。非常感谢维护者们的辛勤付出!
Guide de contribution
Ouvrir le guide de contribution
Évaluation
Cette issue n'a pas encore été évaluée.