知识库检索（Knowledge Search）

知识库检索是蜀农 API 提供的农技知识库检索工具，能检索平台内置的农业专业知识库（涵盖作物种植、病虫害防治、土壤肥料、农事管理等领域），并为模型的回答提供可追溯的知识依据。

核心能力

能力	说明
农业知识库	检索平台内置的农业专业知识库，覆盖水稻、小麦、玉米、油菜等主要作物的种植与植保知识
精准引用溯源	回答附知识条目引用，包含来源条目、分类与相关性评分，便于追溯
检索范围可控	可指定知识库编码（`kb_code`）、返回片段数（`top_k`）与相关度阈值（`min_score`），灵活控制检索范围
重排序支持	可通过 `use_rerank` 启用重排序，提升检索结果的相关性
多工具混合调用	可与自定义 Function、天气搜索等工具协同使用，模型自动判断调用优先级与必要性
响应模式灵活	支持流式和非流式响应，两种方式都会返回检索与总结内容

前提条件

确保账号已开通知识库检索服务。
准备 API Key，参考获取 API Key 与鉴权。
知识库检索产生的费用按计费说明执行。

API 示例

Python 示例（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SHUNONG_API_KEY"],
    base_url="https://ai.agriwis.com/api/v1",
)

completion = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "水稻分蘖期应该如何管理水层？"}
    ],
    tools=[
        {
            "type": "agriwis_knowledge_search",
            "query": "水稻分蘖期水分管理",
            "top_k": 5,
            "min_score": 0.5,
            "use_rerank": True,
        }
    ],
    tool_choice="auto",
)

print(completion.model_dump_json())

curl 示例

curl https://ai.agriwis.com/api/v1/chat/completions \
  -H "Authorization: Bearer $SHUNONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "水稻分蘖期应该如何管理水层？"}
    ],
    "tools": [
      {
        "type": "agriwis_knowledge_search",
        "query": "水稻分蘖期水分管理",
        "top_k": 5,
        "min_score": 0.5,
        "use_rerank": true
      }
    ],
    "tool_choice": "auto"
  }'

请求参数

agriwis_knowledge_search 工具参数

参数	类型	说明
`type`	string	固定为 `"agriwis_knowledge_search"`
`query`	string	必填。检索的问题内容
`kb_code`	string	可选。指定知识库编码，不传则检索全部活跃知识库
`min_score`	number	可选。最低相关度阈值（0-1），低于该值的结果会被过滤，默认为 `0.5`
`top_k`	integer	可选。返回的片段数量，默认为 `5`，上限为 `20`
`use_rerank`	boolean	可选。是否启用重排序，默认为 `false`

tools、tool_choice 等通用参数说明参见 Chat Completions 与工具调用。

响应格式

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "auto",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "根据平台农业知识库，水稻分蘖期应保持 3-5 厘米的浅水层，以促进低位分蘖发生；分蘖后期可适当晒田控蘖……",
        "annotations": [
          {
            "type": "knowledge_citation",
            "kb_id": "kb-crop-1024",
            "title": "水稻分蘖期水分管理要点",
            "summary": "分蘖期宜保持浅水层 3-5 厘米，促进低位分蘖发生；群体过大时晒田控蘖……",
            "category": "crop",
            "score": 0.92
          }
        ],
        "tool_calls": null
      }
    }
  ],
  "usage": {
    "prompt_tokens": 980,
    "completion_tokens": 160,
    "total_tokens": 1140,
    "agriwis_knowledge_search_usage": {
      "tool_usage": 1,
      "chunk_usage": 3
    }
  }
}

响应字段说明

字段	说明
`choices[].message.content`	模型基于知识库检索结果的总结回答
`choices[].message.annotations`	知识条目引用数组，`type` 为 `knowledge_citation`，包含 `kb_id`、`title`、`summary`、`category`、`score`
`choices[].message.tool_calls`	工具调用信息，纯知识库检索场景下通常为 `null`
`usage.agriwis_knowledge_search_usage.tool_usage`	知识库检索工具使用次数
`usage.agriwis_knowledge_search_usage.chunk_usage`	命中的知识片段数量
`finish_reason`	生成结束原因，如 `stop`

计费说明

知识库检索的费用由两部分组成：

检索服务使用次数：按检索调用次数计费，top_k 越大，单次检索消耗的知识片段越多。
模型 Token 消耗：检索到的知识片段会拼接到提示词中，增加输入 Token，按模型标准价格计费。

具体价格与可用额度以控制台展示为准，参见计费说明。

常见问题

检索不到相关知识怎么办？

可能的原因：

问题超出知识库范围：知识库覆盖种植、植保、土肥、农事管理等平台服务领域，领域外的问题可能无匹配结果。
知识库范围不匹配：指定了 kb_code 但该知识库无相关内容时可能漏检，可不传 kb_code 检索全部活跃知识库。
相关性阈值过高：min_score 设置过高会过滤掉相关结果，可适当调低。

use_rerank 什么时候开启？

开启重排序会略微增加响应时间，建议在以下场景开启：

召回片段较多：top_k 较大时，重排序可让更相关的结果排在前面。
跨知识库检索：未指定 kb_code 检索全部知识库时，重排序有助于提升整体相关性。

检索结果可以追溯吗？

可以。返回结果中的 annotations 会附带 kb_id、title、category 等字段，方便在控制台或知识库中定位原始条目。