Feign API 参考

Knowledge 服务通过 Feign 接口向其他微服务提供知识检索能力。

接口定义

KnowledgeRetrieveApi

路径: /feign/knowledge/retrieve

供其他微服务调用的知识检索接口。

---

检索接口

POST /feign/knowledge/retrieve/search

执行知识检索,返回检索结果。

请求参数 (KnowledgeSearchRequest)

{
  "libraryCodes": ["tech-docs", "api-docs"],
  "query": "分布式锁如何实现?",
  "includeContent": true,
  "enableHybridSearch": false
}

参数	类型	必填	说明
libraryCodes	List<String>	是	知识库编码列表
query	String	是	检索查询词
includeContent	boolean	否	是否包含分片内容 (默认 false)
enableHybridSearch	boolean	否	是否启用混合检索 (默认 false)

响应参数 (RetrievalResult)

{
  "documents": [
    {
      "documentId": 1,
      "libraryId": 1,
      "title": "分布式锁指南",
      "source": "https://example.com/doc/1",
      "score": 0.85,
      "fileType": "md",
      "sectionTitle": "什么是分布式锁",
      "content": "分布式锁是...",
      "highlightRanges": [
        { "start": 0, "end": 85 }
      ]
    }
  ],
  "totalCount": 1,
  "costMs": 150,
  "error": null
}

字段	类型	说明
documents	List<RetrievedDocument>	检索结果列表
totalCount	int	结果总数
costMs	long	检索耗时 (毫秒)
error	String	错误信息 (如有)

---

数据模型

KnowledgeSearchRequest

检索请求:

public class KnowledgeSearchRequest {
    private List<String> libraryCodes;    // 知识库编码列表
    private String query;                 // 检索查询词
    private boolean includeContent;       // 是否包含内容
    private boolean enableHybridSearch;   // 是否启用混合检索
}

RetrievalResult

检索结果:

public class RetrievalResult {
    private List<RetrievedDocument> documents;  // 检索结果列表
    private int totalCount;                     // 总数
    private long costMs;                        // 耗时
    private String error;                       // 错误信息
}

RetrievedDocument

检索到的文档:

public class RetrievedDocument {
    private Long documentId;             // 文档 ID
    private Long libraryId;              // 知识库 ID
    private String title;                // 文档标题
    private String source;               // 来源
    private Double score;                // 相似度分数
    private String fileType;             // 文件类型
    private String sectionTitle;         // 章节标题
    private String content;              // 分片内容
    private List<HighlightRange> highlightRanges;  // 高亮区间
}

HighlightRange

高亮区间:

public class HighlightRange {
    private int start;  // 原文起始位置
    private int end;    // 原文结束位置
}

---

使用示例

Spring Cloud OpenFeign

1. 定义 Feign 客户端

@FeignClient(name = "knowledge", path = "/feign/knowledge/retrieve")
public interface KnowledgeRetrieveClient {
    
    @PostMapping("/search")
    RetrievalResult search(@RequestBody KnowledgeSearchRequest request);
}

2. 注入并调用

@Service
public class MyService {
    
    @Autowired
    private KnowledgeRetrieveClient knowledgeClient;
    
    public void doSearch(String query) {
        KnowledgeSearchRequest request = new KnowledgeSearchRequest();
        request.setLibraryCodes(List.of("tech-docs"));
        request.setQuery(query);
        request.setIncludeContent(true);
        
        RetrievalResult result = knowledgeClient.search(request);
        
        for (RetrievedDocument doc : result.getDocuments()) {
            System.out.println("文档: " + doc.getTitle());
            System.out.println("分数: " + doc.getScore());
            System.out.println("内容: " + doc.getContent());
        }
    }
}

HTTP 调用示例

curl -X POST http://localhost:8080/feign/knowledge/retrieve/search \
  -H "Content-Type: application/json" \
  -d '{
    "libraryCodes": ["tech-docs"],
    "query": "分布式锁如何实现?",
    "includeContent": true
  }'

---

注意事项

1. 知识库编码

libraryCodes 使用的是知识库的 code 字段,而非 id。这是为了在微服务间解耦,避免 ID 冲突。

2. 性能考虑

• Feign 接口仅返回检索结果,不调用 LLM 生成回答
• 适用于其他微服务需要知识检索,但自行处理业务逻辑的场景

下一步

• 返回 检索系统概览