检索增强生成

创建/删除仓库

client->documents_store

请求参数

名称	类型	是否必须	说明
tenant	String	Y	所属租户

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常，其他错误
message	String	Y	正确-success，错误-返回错误消息

获取所有租户

client->documents_store

请求参数-None

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常, 其他错误
message	String	Y	正确-success，错误-返回错误消息
tenants	StringArray	N	所有租户名称数组-发生错误就没有

提取文档

client->documents_store

请求参数

名称	类型	是否必须	说明
documents	ObjectArray	Y	文档数组
+name	String	Y	文档名
+url	String	Y	文档url地址
+doc_type	String	Y	文档类型，支持pdf, doc, txt, docx
+split_method	String	Y	文档分段方式-目前支持两种 -chunk 根据最大字符数自动分段 -semantic 根据语义相似性分段
indexers	StringArray	N	当指定indexers表示为当前文档新增索引方式，目前默认支持["summary", "keywords", "elasticsearch"] 单独新增支持["qa"] 默认不填写该字段，或者indexers=[]
tenant	String	Y	所属租户

响应参数(流式text/event-stream)

名称	类型	是否必须	说明
name	String	Y	文档名
status	String	Y	running/finish/error
words_num	Int	Y	返回提取的字符
file_size	Int	Y	文档大小(字节数)
message	String	Y	当前进展消息

删除文档

client->documents_store

请求参数

名称	类型	是否必须	说明
ids	StringArray	Y	文档id数组-id可通过文档名从knowledge.documents中查询
tenant	String	Y	所属租户

响应参数

名称	类型	是否必须	说明
results	ObjectArray	Y	结果数组
+id	String	Y	文档id
+status	Bool	Y	成功/失败

修改文档名字

client->documents_store

请求参数

名称	类型	是否必须	说明
id	String	Y	文档id
name	String	Y	文档新名字
tenant	String	Y	所属租户

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常, 其他错误
message	String	Y	正确-success，错误-返回错误消息

获取文档细节

client->documents_store

请求参数

名称	类型	是否必须	说明
id	String	Y	待获取文档id
tenant	String	Y	所属租户

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常，其他错误
message	String	Y	正确-success，错误-返回错误消息
details	Object	Y	返回查询文档细节
+split_method	String	Y	文档分段方式-目前支持两种 -chunk 根据最大字符数自动分段 -semantic 根据语义相似性分段
+chunk_count	Int	Y	文档分段数
+qa_count	Int	Y	问答对数
+chunks	StringArray	Y	返回请求指定数量的前N段分段文本

获取问答对

client->documents_store

请求参数

名称	类型	是否必须	说明
id	String	Y	待获取文档id
tenant	String	Y	所属租户

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常，其他错误
message	String	Y	正确-success，错误-返回错误消息
data	ObjectArray	Y	问答对数组
+pk	String	Y	一个问答对的唯一id
+chunk_id	String	Y	问答关联文档分段的id，如果人工该字段为human
+status	String	Y	当前状态 enable-已生效 uncleared-待确认
+text	String	Y	问答对文本-"问: xxxxx\n答: abcd..."

更新问答对

client->documents_store

请求参数

名称	类型	是否必须	说明
qas	ObjectArray	Y	待更新的问答对数据
+pk	String	Y	要更新的问答对id, 如果是新增则生成一个uuid
+question	String	Y	问题
+answer	String	Y	答案
+chunk_id	String	Y	关联相关段落的id,如果是手动添加的固定为human
+status	String	Y	问答对状态: enable - 生效, uncleared - 待确认
document	String	Y	问答对所属文档id
tenant	String	Y	所属租户

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常，其他错误
message	String	Y	正确-success，错误-返回错误消息

删除问答对

client->documents_store

请求参数

名称	类型	是否必须	说明
pks	StringArray	Y	待删除问答对主键id数组
tenant	String	Y	所属租户

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常，其他错误
message	String	Y	正确-success，错误-返回错误消息

检索生成

client->retrieval_gpt

请求参数

名称	类型	是否必须	说明
chatId	String	Y	聊天会话id
images	String	N	图片资源url地址
tenant	String	Y	所属租户
content	String	Y	用户聊天内容
recommend	Bool	Y	是否为推荐问题,用户选择的都为推荐问题.recommendQuestion
documentType	String	N	当前选择文档类型"category"(分类)或"recommend"(推荐)
documentIds	StringArray	N	选择文档的id
session_config	Object	N	启用临时配置参数,参考设置检索配置的"config"字段

响应参数(流式text/event-stream)

名称	类型	是否必须	说明
choices	ObjArray	Y
+delta	Object	Y
++step/content/intentQuestion/(documents, [recommendQuestion], [recommendDocuments])	String/StringArray/ObjectArray	Y	step/content是字符串-指示步骤和模型的回答, documents是字符数组-标识引用的文档名 intentQuestion-非必须, 当意图不明确时由意图识别构建推荐问题 recommendQuestion-推荐问题与documents一起，非必须字段 recommendDocuments[{"id": "abc", "document": "name"}...]

纯检索

client->retrieval_gpt

请求参数

名称	类型	是否必须	说明
text	String	Y	检索问题
topk	Int	Y	最多条数
score	Float	Y	最低分数
tenant	String	Y	所属租户

响应参数

名称	类型	是否必须	说明
status	Int	Y	返回状态
message	String	Y	状态消息
data	ObjectArray	Y	结果数组
+text	String	Y	检索内容
+source	String	Y	检索引用文档

设置检索配置

client->retrieval_gpt

请求参数

名称	类型	是否必须	说明
tenant	String	Y	租户
config	Object	Y	配置项
+model_name	String	Y	问答模型
+reference_context	Bool	Y	启用上下文对象识别true, false
+reference_documents	Object	Y	引用文档配置项
++topk	Int	Y	检索出来给模型总结的topk的参考资料
++recommend	Object	Y	推荐文档配置
+++enable	Bool	Y	是否启用文档推荐
+++max_count	Int	Y	最多推荐文档数
+recommend_questions	Bool	Y	是否推荐问题
+retrieval_engines	StringArray	Y	选用的搜索引擎配置-["summary", "keywords", "qa", "elasticsearch"]

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常，其他错误
message	String	Y	正确-success，错误-返回错误消息

查询检索配置

client->retrieval_gpt

请求参数

名称	类型	是否必须	说明
tenant	String	Y	租户

响应参数

名称	类型	是否必须	说明
status	Int	Y	200正常，其他错误
message	String	Y	正确-success，错误-返回错误消息
data	Object	N	检索配置参数,参考设置检索配置的"config"字段

RESTFUL

创建仓库

client->documents_store

POST http://{ip:port}/uran/mm/repositories

请求示例

{
    "tenant":"development"
}

响应示例

{
    "status" : 200,
    "message": "success"
}

删除仓库

client->documents_store

DELETE http://{ip:port}/uran/mm/repositories

请求示例

{
    "tenant":"development"
}

响应示例

{
    "status" : 200,
    "message": "success"
}

获取所有租户

client->documents_store

GET http://{ip:port}/uran/mm/tenants

响应示例

{
    "status" : 200,
    "message": "success",
    "tenants": ["development"]
}

提取文档

client->documents_store

POST http://{ip:port}/uran/mm/document

请求示例

{
    "documents": [
        {
            "name": "交通拥堵情况报告",
            "url": "http://10.10.1.7:32300/storage/files/1735075252571697154.docx",
            "doc_type": "docx",
            "split_method": "chunk"
        },
        {
            "name": "算法白皮书",
            "url": "http://10.10.1.7:32300/storage/files/1736898577165938690.pdf",
            "doc_type": "pdf",
            "split_method": "semantic"
        }
    ],
    "indexers" : [], //默认，["qa"]表示当前文档提取qa对索引
    "tenant": "development"
}

响应示例

data: {"name": "算法白皮书", "status": "running", "words_num": 0, "file_size": 6481613, "message": "提取字符"}

data: {"name": "算法白皮书", "status": "running", "words_num": 115295, "file_size": 6481613, "message": "分割字符"}

data: {"name": "算法白皮书", "status": "running", "words_num": 115295, "file_size": 6481613, "message": "文档入库"}

data: {"name": "算法白皮书", "status": "finish", "words_num": 115295, "file_size": 6481613, "message": "导入完成"}

......

删除文档

client->documents_store

DELETE http://{ip:port}/uran/mm/document_ids

请求示例

{
    "ids": ["080c36c062adafb7dd57664d3191f6ff", "31f8ddb6cee2612e7c099f421e4dcf1c"],
    "tenant" : "development"
}

响应示例

{
    "results":[
    {
        "id":"080c36c062adafb7dd57664d3191f6ff",
            "status": true
    },
    {
        "id":"31f8ddb6cee2612e7c099f421e4dcf1c",
            "status": true
    }
}

修改文档名字

client->documents_store

PATCH http://{ip:port}/uran/mm/document_name

请求示例

{
    "id" : "0155ab7052424f62180a284233df5789",
    "name" : "企业门户操作手册+",
    "tenant" : "1761827704702742529"
}

响应示例

{
    "status": 0,
    "message": "success"
}

获取文档细节

client->documents_store

GET http://{ip:port}/uran/mm/document_details?tenat=xxx&id=xxx&chunk_count=x

请求示例

GET http://10.10.1.189:8184/uran/mm/document_details?tenant=1761827704702742529&id=b64ad8f405ee3f43269bddf8899a604f&chunk_count=3

响应示例

{
    "status": 200,
    "message": "success",
    "details": {
        "split_method": "chunk",
        "chunk_count": 5,
        "qa_count": 27,
        "chunks": ["abc....", "ddd....", "...."]
    }
}

获取问答对

client->documents_store

GET http://{ip:port}/uran/mm/document_qas?tenant=xxx&id=xxx

请求示例

GET http://10.10.1.189:8184/uran/mm/document_qas?tenant=1761827704702742529&id=b64ad8f405ee3f43269bddf8899a604f

响应示例

{
    "status": 200,
    "message": "success",
    "data": [
        {
            "pk": "02a604b983f4469581797a7d30d5b6e7",
            "chunk_id": "0aa010e5ddee11f24d5929c6499e9aaa",
            "status": "enable",
            "text": "问: 公路增设或改造平面交叉道口的监督投诉方式是什么？\n答: 投诉电话：0831-12345;"
        },
        {
            "pk": "07dfc2b37d0f4c9c8ee29cd8a0664ccc",
            "chunk_id": "0aa010e5ddee11f24d5929c6499e9aaa",
            "status": "enable",
            "text": "问: 公路增设或改造平面交叉道口的设定依据是什么？\n答: 设定依据包括《公路安全保护条例》第二十七条和《中华人民共和国公路法》第五十五条。"
        },
        ...
      ]
}

更新问答对

client->documents_store

PATCH http://{ip:port}/uran/mm/document_qas

请求示例

{
    "qas" : [
          {
            "pk": "02a604b983f4469581797a7d30d5b6e7",
            "chunk_id": "0aa010e5ddee11f24d5929c6499e9aaa",
            "question": "公路增设或改造平面交叉道口的监督投诉方式是什么？",
            "answer": "投诉电话：0831-12315",
        "status" : "enable"
        },
        {
            "pk": "07dfc2b37d0f4c9c8ee29cd8a0664ccbb",
            "chunk_id": "human",
            "qeustion": "公路维修的周期是多长？",
            "answer": "公路维修周期一般是3-5年",
        "status" : "enable"
        }
    ],
    "document" : "b64ad8f405ee3f43269bddf8899a604f",
    "tenant" : "1761827704702742529"
}

响应示例

{
    "status": 200,
    "message": "success"
}

删除问答对

client->documents_store

DELETE http://{ip:port}/uran/mm/document_qas

请求示例

{
    "pks" : ["080c37dda31f4690b62d08b73aa8e2b3"],
    "tenant" : "1761827704702742529"
}

响应示例

{
    "status": 200,
    "message": "success"
}

检索生成

client->retrieval_gpt

POST http://{ip:port}/uran/mm/retrieve

请求示例

{
    "chatId": "a134",
    "tenant": "development",
    "documentType" : "category",
    "documentIds" : [],
    "session_config": {
        "model_name": "deepseek-chat",
        "reference_context": true,
        "reference_documents": {
            "topk": 1,
            "recommend": {
                "enable": true,
                "max_count": 3
            }
        },
        "recommend_questions": true,
        "retrieval_engines": [
            "summary"
        ]
    },
    "content": "折多山交通拥堵情况如何", 
    "recommend" : false
}

响应示例

data: {"choices": [{"delta": {"step": "正在检索知识库"}}]}

data: {"choices": [{"delta": {"step": "正在组织解决方案"}}]}

data: { "choices": [{"delta": {"content": "针对"}}]}

data: { "choices": [{"delta": {"content": "折多山"}}]}

data: { "choices": [{"delta": {"content": "交通"}}]}

......

data: { "choices": [{"delta": {"documents": ["折多山交通报告"], "recommendQuestion": ["则多山大车经过情况？",...], "recommendDocuments": [{"id": "954faa687ece5746bd9a0167b68b12b4", "document": "折多山气候灾害报告"}]}]}

意图分类示例

{
    "chatId": "a134",
    "tenant": "development",
    "documentType" : "category",
    "documentIds" : [],
    "session_config": {
        "model_name": "deepseek-chat",
        "reference_context": true,
        "reference_documents": {
            "topk": 1,
            "recommend": {
                "enable": true,
                "max_count": 3
            }
        },
        "recommend_questions": true,
        "retrieval_engines": [
            "summary"
        ]
    },
    "content": "公积金提取",
    "recommend" : false
}

响应示例

data: { "choices": [{"delta": {"content": "您好，您的问题看起来不够明确，你是否想要咨询以下相关问题。"}}]}

data: { "choices": [{"delta": {"intentQuestion": ["租房公积金怎么提取？", "离职公积金怎么提取？"...]}]}

纯检索

client->retrieval_gpt

POST http://{ip:port}/uran/mm/search

请求示例

{
    "text":"交通报告时间范围是多少",
    "topk":10,
    "score":0.1,
    "tenant" : "development"
}

响应示例

{
    "statu": 200,
    "message": "success",
    "data": [
        {
            "text": "总体情况总结和建议...",
            "source": "交通拥堵情况报告"
        },
        {
            "text": "分布情况：...",
            "source": "交通拥堵情况报告"
        },
        {
            "text": "折多山垭口路口...",
            "source": "交通拥堵情况报告"
        },
        {
            "text": "交通异常事件监控...",
            "source": "交通拥堵情况报告"
        }
    ]
}

设置检索配置

client->retrieval_gpt

POST http://{ip:port}/uran/mm/configuration

请求示例

{
    "tenant": "1761827704702742529",
    "config": {
        "model_name": "deepseek-chat",
        "reference_context": true,
        "reference_documents": {
            "topk": 1,
            "recommend": {
                "enable": true,
                "max_count": 3
            }
        },
        "recommend_questions": true,
        "retrieval_engines": [
            "keywords",
            "elasticsearch"
        ]
    }
}

响应示例

{
    "status": 200,
    "message": "success"
}

查询检索配置

client->retrieval_gpt

GET http://{ip:port}/uran/mm/configuration?tenant=xxxx

请求示例

GET http://10.10.1.189:8186/uran/mm/configuration?tenant=1761827704702742529

响应示例

{
    "status": 200,
    "message": "success",
    "data": {
        "model_name": "deepseek-chat",
        "reference_context": true,
        "retrieval_engines": [
            "qa"
        ],
        "recommend_questions": true,
        "reference_documents": {
            "topk": 1,
            "recommend": {
                "enable": true,
                "max_count": 3
            }
        }
    }
}

gRPC

syntax = "proto3";

service ChatBot {
    rpc chat(ChatSession) returns (stream ChatChunk) {}
}

message ChatSession {
    string chatId = 1; //会话id
    string images = 2; //图片地址，如:http://xxxxxx.jpg
    string content = 3; //用户对话
}

message Delta {
    string role = 1; //角色assistant
    string content = 2; //大模型回答内容
    repeated string documents = 3; //引用文档数组
}

message Choices {
    Delta delta = 1;
}

message ChatChunk {
    repeated Choices choices = 1;
}