从 scipy.special 导入 kwargs--- 侧边栏位置: 2 slug: /python_api_reference​

Python API 参考

RAGFlow的Python API完整参考。在继续之前，请确保您已准备好RAGFlow API密钥以进行身份验证。

pip install ragflow-sdk

数据集管理​

创建数据集​

RAGFlow.create_dataset(
    name: str,
    avatar: str = "",
    description: str = "",
    embedding_model: str = "BAAI/bge-zh-v1.5",
    language: str = "English",
    permission: str = "me", 
    chunk_method: str = "naive",
    parser_config: DataSet.ParserConfig = None
) -> DataSet

创建一个数据集。

参数​

名称: str, 必填​

要创建的数据集的唯一名称。它必须符合以下要求：

• 允许的字符包括：
  • 英文字母 (a-z, A-Z)
  • 数字 (0-9)
  • "_" (下划线)
• 必须以英文字母或下划线开头。
• 最多65,535个字符。
• 不区分大小写。

头像: str​

头像的Base64编码。默认为 ""

描述: str​

要创建的数据集的简要描述。默认为 ""。

语言: str​

要创建的数据集的语言设置。可用选项：

• "English" (默认)
• "Chinese"

权限​

指定谁可以访问要创建的数据集。可用选项：

• "me": （默认）只有你可以管理数据集。
• "team": 所有团队成员都可以管理数据集。

chunk_method, str​

用于创建数据集的分块方法。可用选项：

• "naive": 通用（默认）
• "manual: 手动
• "qa": 问答
• "table": 表格
• "paper": 纸张
• "book": 书籍
• "laws": 法律
• "presentation": 演示
• "picture": 图片
• "one": 一
• "knowledge_graph": 知识图谱
  在选择此选项之前，请确保您的LLM在设置页面上已正确配置。请注意，知识图谱会消耗大量的Token！
• "email": 电子邮件

解析器配置​

数据集的解析器配置。一个ParserConfig对象的属性根据所选的chunk_method而变化：

• chunk_method="naive":
  {"chunk_token_num":128,"delimiter":"\\n!?;。；！？","html4excel":False,"layout_recognize":True,"raptor":{"user_raptor":False}}.
• chunk_method="qa":
  {"raptor": {"user_raptor": False}}
• chunk_method="manuel":
  {"raptor": {"user_raptor": False}}
• chunk_method="table":
  None
• chunk_method="paper":
  {"raptor": {"user_raptor": False}}
• chunk_method="book":
  {"raptor": {"user_raptor": False}}
• chunk_method="laws":
  {"raptor": {"user_raptor": False}}
• chunk_method="picture":
  None
• chunk_method="presentation":
  {"raptor": {"user_raptor": False}}
• chunk_method="one":
  None
• chunk_method="knowledge-graph":
  {"chunk_token_num":128,"delimiter":"\\n!?;。；！？","entity_types":["organization","person","location","event","time"]}
• chunk_method="email":
  None

返回​

• 成功：一个 dataset 对象。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.create_dataset(name="kb_1")

删除数据集​

RAGFlow.delete_datasets(ids: list[str] = None)

通过ID删除数据集。

参数​

ids: list[str], 必填​

要删除的数据集的ID。默认为None。如果未指定，将删除所有数据集。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

rag_object.delete_datasets(ids=["id_1","id_2"])

列出数据集​

RAGFlow.list_datasets(
    page: int = 1, 
    page_size: int = 30, 
    orderby: str = "create_time", 
    desc: bool = True,
    id: str = None,
    name: str = None
) -> list[DataSet]

列出数据集。

参数​

页码: int​

指定数据集将显示的页面。默认为 1。

页面大小: int​

每页的数据集数量。默认为 30。

排序依据: str​

数据集应排序的字段。可用选项：

• "create_time" (默认)
• "update_time"

描述: bool​

指示检索的数据集是否应按降序排序。默认为True。

id: str​

要检索的数据集的ID。默认为None。

名称: str​

要检索的数据集的名称。默认为None。

返回​

• 成功：返回一个DataSet对象的列表。
• 失败：Exception。

示例​

列出所有数据集​

for dataset in rag_object.list_datasets():
    print(dataset)

通过ID检索数据集​

dataset = rag_object.list_datasets(id = "id_1")
print(dataset[0])

更新数据集​

DataSet.update(update_message: dict)

更新当前数据集的配置。

参数​

update_message: dict[str, str|int], 必填​

表示要更新的属性的字典，包含以下键：

• "name": str 数据集的修订名称。
• "embedding_model": str 更新后的嵌入模型名称。
  • 在更新"embedding_model"之前，请确保"chunk_count"为0。
• "chunk_method": str 数据集的切分方法。可用选项：
  • "naive": 通用
  • "manual: 手动
  • "qa": 问答
  • "table": 表格
  • "paper": 论文
  • "book": 书籍
  • "laws": 法律
  • "presentation": 演示文稿
  • "picture": 图片
  • "one": 单一
  • "email": 电子邮件
  • "knowledge_graph": 知识图谱
    在选择此选项之前，请确保您的LLM在设置页面中已正确配置。请注意，知识图谱会消耗大量的Tokens！

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets(name="kb_name")
dataset.update({"embedding_model":"BAAI/bge-zh-v1.5", "chunk_method":"manual"})

数据集内的文件管理​

上传文档​

DataSet.upload_documents(document_list: list[dict])

将文档上传到当前数据集。

参数​

文档列表: list[dict], 必填​

表示要上传的文档的字典列表，每个字典包含以下键：

• "display_name": （可选）要在数据集中显示的文件名。
• "blob": (可选) 要上传的文件的二进制内容。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

dataset = rag_object.create_dataset(name="kb_name")
dataset.upload_documents([{"display_name": "1.txt", "blob": "<BINARY_CONTENT_OF_THE_DOC>"}, {"display_name": "2.pdf", "blob": "<BINARY_CONTENT_OF_THE_DOC>"}])

更新文档​

Document.update(update_message:dict)

更新当前文档的配置。

参数​

update_message: dict[str, str|dict[]], 必填​

表示要更新的属性的字典，包含以下键：

• "display_name": str 要更新的文档名称。
• "chunk_method": str 应用于文档的解析方法。
  • "naive": 通用
  • "manual: 手动
  • "qa": 问答
  • "table": 表格
  • "paper": 论文
  • "book": 书籍
  • "laws": 法律
  • "presentation": 演示
  • "picture": 图片
  • "one": 单一
  • "knowledge_graph": 知识图谱
    在选择此选项之前，请确保您的LLM在设置页面中已正确配置。请注意，知识图谱会消耗大量的Token！
  • "email": 电子邮件
• "parser_config": dict[str, Any] 文档的解析配置。其属性根据所选的 "chunk_method" 不同而变化：
  • "chunk_method"="naive":
    {"chunk_token_num":128,"delimiter":"\\n!?;。；！？","html4excel":False,"layout_recognize":True,"raptor":{"user_raptor":False}}.
  • chunk_method"="qa":
    {"raptor": {"user_raptor": False}}
  • chunk_method"="manuel":
    {"raptor": {"user_raptor": False}}
  • chunk_method"="table":
    None
  • chunk_method"="paper":
    {"raptor": {"user_raptor": False}}
  • chunk_method"="book":
    {"raptor": {"user_raptor": False}}
  • chunk_method"="laws":
    {"raptor": {"user_raptor": False}}
  • chunk_method"="presentation":
    {"raptor": {"user_raptor": False}}
  • chunk_method"="picture":
    None
  • chunk_method"="one":
    None
  • chunk_method"="knowledge-graph":
    {"chunk_token_num":128,"delimiter":"\\n!?;。；！？","entity_types":["organization","person","location","event","time"]}
  • chunk_method"="email":
    None

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets(id='id')
dataset = dataset[0]
doc = dataset.list_documents(id="wdfxb5t547d")
doc = doc[0]
doc.update([{"parser_config": {"chunk_token_count": 256}}, {"chunk_method": "manual"}])

下载文档​

Document.download() -> bytes

下载当前文档。

返回​

下载的文档以字节为单位。

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets(id="id")
dataset = dataset[0]
doc = dataset.list_documents(id="wdfxb5t547d")
doc = doc[0]
open("~/ragflow.txt", "wb+").write(doc.download())
print(doc)

列出文档​

Dataset.list_documents(id:str =None, keywords: str=None, page: int=1, page_size:int = 30, order_by:str = "create_time", desc: bool = True) -> list[Document]

列出当前数据集中的文档。

参数​

id: str​

要检索的文档的ID。默认为None。

关键词: str​

用于匹配文档标题的关键词。默认为None。

页码: int​

指定显示文档的页面。默认为 1。

页面大小: int​

每页的最大文档数。默认为 30。

排序依据: str​

用于排序文档的字段。可用选项：

• "create_time" (默认)
• "update_time"

描述: bool​

指示检索到的文档是否应按降序排序。默认为True。

返回​

• 成功：一个Document对象的列表。
• 失败：Exception。

一个Document对象包含以下属性：

• id: 文档ID。默认为 ""。
• name: 文档名称。默认为 ""。
• thumbnail: 文档的缩略图。默认为 None。
• dataset_id: 与文档关联的数据集ID。默认为None。
• chunk_method 分块方法的名称。默认为 "naive"。
• source_type: 文档的源类型。默认为 "local"。
• type: 文档的类型或类别。默认为 ""。保留供将来使用。
• created_by: str 文档的创建者。默认为 ""。
• size: int 文档大小，以字节为单位。默认为 0。
• token_count: int 文档中的标记数量。默认为 0。
• chunk_count: int 文档中的块数。默认为 0。
• progress: float 当前处理进度，以百分比表示。默认为 0.0。
• progress_msg: str 表示当前进度状态的消息。默认为 ""。
• process_begin_at: datetime 文档处理的开始时间。默认为 None。
• process_duation: float 处理持续时间，单位为秒。默认为 0.0。
• run: str 文档的处理状态:
  • "UNSTART" (默认)
  • "RUNNING"
  • "CANCEL"
  • "DONE"
  • "FAIL"
• status: str 保留供将来使用。
• parser_config: ParserConfig 解析器的配置对象。其属性根据所选的chunk_method而有所不同：
  • chunk_method="naive":
    {"chunk_token_num":128,"delimiter":"\\n!?;。；！？","html4excel":False,"layout_recognize":True,"raptor":{"user_raptor":False}}.
  • chunk_method="qa":
    {"raptor": {"user_raptor": False}}
  • chunk_method="manuel":
    {"raptor": {"user_raptor": False}}
  • chunk_method="table":
    None
  • chunk_method="paper":
    {"raptor": {"user_raptor": False}}
  • chunk_method="book":
    {"raptor": {"user_raptor": False}}
  • chunk_method="laws":
    {"raptor": {"user_raptor": False}}
  • chunk_method="presentation":
    {"raptor": {"user_raptor": False}}
  • chunk_method="picure":
    None
  • chunk_method="one":
    None
  • chunk_method="knowledge-graph":
    {"chunk_token_num":128,"delimiter": "\\n!?;。；！？","entity_types":["organization","person","location","event","time"]}
  • chunk_method="email":
    None

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.create_dataset(name="kb_1")

filename1 = "~/ragflow.txt"
blob = open(filename1 , "rb").read()
dataset.upload_documents([{"name":filename1,"blob":blob}])
for doc in dataset.list_documents(keywords="rag", page=0, page_size=12):
    print(doc)

删除文档​

DataSet.delete_documents(ids: list[str] = None)

按ID删除文档。

参数​

ids: list[list]​

要删除的文档的ID。默认为None。如果未指定，将删除数据集中的所有文档。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets(name="kb_1")
dataset = dataset[0]
dataset.delete_documents(ids=["id_1","id_2"])

解析文档​

DataSet.async_parse_documents(document_ids:list[str]) -> None

解析当前数据集中的文档。

参数​

文档ID: list[str], 必填​

要解析的文档的ID。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.create_dataset(name="dataset_name")
documents = [
    {'display_name': 'test1.txt', 'blob': open('./test_data/test1.txt',"rb").read()},
    {'display_name': 'test2.txt', 'blob': open('./test_data/test2.txt',"rb").read()},
    {'display_name': 'test3.txt', 'blob': open('./test_data/test3.txt',"rb").read()}
]
dataset.upload_documents(documents)
documents = dataset.list_documents(keywords="test")
ids = []
for document in documents:
    ids.append(document.id)
dataset.async_parse_documents(ids)
print("Async bulk parsing initiated.")

停止解析文档​

DataSet.async_cancel_parse_documents(document_ids:list[str])-> None

停止解析指定的文档。

参数​

document_ids: list[str], 必填​

应停止解析的文档的ID。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.create_dataset(name="dataset_name")
documents = [
    {'display_name': 'test1.txt', 'blob': open('./test_data/test1.txt',"rb").read()},
    {'display_name': 'test2.txt', 'blob': open('./test_data/test2.txt',"rb").read()},
    {'display_name': 'test3.txt', 'blob': open('./test_data/test3.txt',"rb").read()}
]
dataset.upload_documents(documents)
documents = dataset.list_documents(keywords="test")
ids = []
for document in documents:
    ids.append(document.id)
dataset.async_parse_documents(ids)
print("Async bulk parsing initiated.")
dataset.async_cancel_parse_documents(ids)
print("Async bulk parsing cancelled.")

添加块​

Document.add_chunk(content:str, important_keywords:list[str] = []) -> Chunk

向当前文档添加一个块。

参数​

内容: str, 必填​

块的文本内容。

重要关键词: list[str]​

用于标记块的关键术语或短语。

返回​

• 成功：一个Chunk对象。
• 失败：Exception。

一个 Chunk 对象包含以下属性：

• id: str: 块ID。
• content: str 文本块的内容。
• important_keywords: list[str] 标记有该块的术语或短语的列表。
• create_time: str 块创建的时间（添加到文档的时间）。
• create_timestamp: float 表示块创建时间的时间戳，以自1970年1月1日以来的秒数表示。
• dataset_id: str 关联数据集的ID。
• document_name: str 关联文档的名称。
• document_id: str 关联文档的ID。
• available: bool 数据集中块的可用状态。值选项：
  • False: 不可用
  • True: 可用（默认）

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets(id="123")
dtaset = dataset[0]
doc = dataset.list_documents(id="wdfxb5t547d")
doc = doc[0]
chunk = doc.add_chunk(content="xxxxxxx")

列出块​

Document.list_chunks(keywords: str = None, page: int = 1, page_size: int = 30, id : str = None) -> list[Chunk]

列出当前文档中的块。

参数​

关键词: str​

用于匹配块内容的关键字。默认为 None

页码: int​

指定将显示块的页面。默认为 1。

页面大小: int​

每页的最大块数。默认为 30。

id: str​

要检索的块的ID。默认值：None

返回​

• 成功：一个Chunk对象的列表。
• 失败：Exception。

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets("123")
dataset = dataset[0]
dataset.async_parse_documents(["wdfxb5t547d"])
for chunk in doc.list_chunks(keywords="rag", page=0, page_size=12):
    print(chunk)

删除块​

Document.delete_chunks(chunk_ids: list[str])

按ID删除块。

参数​

chunk_ids: list[str]​

要删除的块的ID。默认为None。如果未指定，将删除当前文档的所有块。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets(id="123")
dataset = dataset[0]
doc = dataset.list_documents(id="wdfxb5t547d")
doc = doc[0]
chunk = doc.add_chunk(content="xxxxxxx")
doc.delete_chunks(["id_1","id_2"])

更新数据块​

Chunk.update(update_message: dict)

更新当前块的内容或配置。

参数​

update_message: dict[str, str|list[str]|int] 必填​

表示要更新的属性的字典，包含以下键：

• "content": str 文本块的内容。
• "important_keywords": list[str] 一个关键术语或短语的列表，用于标记该块。
• "available": bool 数据集中块的可用状态。值选项：
  • False: 不可用
  • True: 可用（默认）

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets(id="123")
dataset = dataset[0]
doc = dataset.list_documents(id="wdfxb5t547d")
doc = doc[0]
chunk = doc.add_chunk(content="xxxxxxx")
chunk.update({"content":"sdfx..."})

检索块​

RAGFlow.retrieve(question:str="", dataset_ids:list[str]=None, document_ids=list[str]=None, page:int=1, page_size:int=30, similarity_threshold:float=0.2, vector_similarity_weight:float=0.3, top_k:int=1024,rerank_id:str=None,keyword:bool=False,higlight:bool=False) -> list[Chunk]

从指定的数据集中检索块。

参数​

问题: str, 必填​

用户查询或查询关键词。默认为 ""。

数据集ID: list[str], 必填​

要搜索的数据集的ID。默认为None。如果不设置此参数，请确保设置了document_ids。

文档ID: list[str]​

要搜索的文档的ID。默认为None。您必须确保所有选定的文档使用相同的嵌入模型。否则，将会发生错误。如果您不设置此参数，请确保您设置了dataset_ids。

页码: int​

检索文档的起始索引。默认为 1。

页面大小: int​

要检索的最大块数。默认为30。

相似度阈值: float​

最小相似度分数。默认为 0.2。

vector_similarity_weight: float​

向量余弦相似度的权重。默认为0.3。如果x表示向量余弦相似度，则(1 - x)是术语相似度权重。

top_k: int​

参与向量余弦计算的块数。默认为1024。

rerank_id: str​

重新排序模型的ID。默认为None。

关键词: bool​

指示是否启用基于关键字的匹配：

• True: 启用基于关键词的匹配。
• False: 禁用基于关键字的匹配（默认）。

高亮: bool​

指定是否在结果中启用匹配项的高亮显示：

• True: 启用匹配项的高亮显示。
• False: 禁用匹配项的高亮显示（默认）。

返回​

• 成功：表示文档块的Chunk对象列表。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
dataset = rag_object.list_datasets(name="ragflow")
dataset = dataset[0]
name = 'ragflow_test.txt'
path = './test_data/ragflow_test.txt'
rag_object.create_document(dataset, name=name, blob=open(path, "rb").read())
doc = dataset.list_documents(name=name)
doc = doc[0]
dataset.async_parse_documents([doc.id])
for c in rag_object.retrieve(question="What's ragflow?", 
             dataset_ids=[dataset.id], document_ids=[doc.id], 
             page=1, page_size=30, similarity_threshold=0.2, 
             vector_similarity_weight=0.3,
             top_k=1024
             ):
    print(c)

聊天助手管理​

创建聊天助手​

RAGFlow.create_chat(
    name: str, 
    avatar: str = "", 
    dataset_ids: list[str] = [], 
    llm: Chat.LLM = None, 
    prompt: Chat.Prompt = None
) -> Chat

创建一个聊天助手。

参数​

名称: str, 必填​

聊天助手的名称。

头像: str​

头像的Base64编码。默认为""。

数据集ID列表: list[str]​

关联数据集的ID。默认为[""]。

llm: Chat.LLM​

聊天助手创建的LLM设置。默认为None。当值为None时，将生成一个包含以下值的字典作为默认值。一个LLM对象包含以下属性：

• model_name: str
  聊天模型的名称。如果为None，将使用用户的默认聊天模型。
• temperature: float
  控制模型预测的随机性。较低的温度会导致更保守的响应，而较高的温度会产生更具创造性和多样性的响应。默认为0.1。
• top_p: float
  也称为“核采样”，此参数设置一个阈值以选择较小的单词集进行采样。它专注于最可能的单词，剔除不太可能的单词。默认为 0.3
• presence_penalty: float
  这通过惩罚已经在对话中出现过的单词来阻止模型重复相同的信息。默认值为0.2。
• frequency penalty: float
  类似于存在惩罚，这减少了模型频繁重复相同单词的倾向。默认值为 0.7。
• max_token: int
  模型输出的最大长度，以令牌（单词或单词片段）的数量衡量。默认为512。如果禁用，您将取消最大令牌限制，允许模型确定其响应中的令牌数量。

提示: Chat.Prompt​

LLM 遵循的说明。一个 Prompt 对象包含以下属性：

• similarity_threshold: float RAGFlow 在检索过程中使用加权关键词相似度和加权向量余弦相似度的组合，或者加权关键词相似度和加权重排序分数的组合。如果相似度分数低于此阈值，相应的块将从结果中排除。默认值为 0.2。
• keywords_similarity_weight: float 此参数设置关键词相似度在混合相似度分数中的权重，与向量余弦相似度或重新排序模型相似度结合使用。通过调整此权重，您可以控制关键词相似度相对于其他相似度度量的影响。默认值为 0.7。
• top_n: int 此参数指定了相似度分数高于similarity_threshold的前N个块的数量，这些块将被输入到LLM中。LLM将仅访问这些“前N个”块。默认值为8。
• variables: list[dict[]] 此参数列出了要在聊天配置的'System'字段中使用的变量。请注意：
  • knowledge 是一个保留变量，表示检索到的块。
  • 'System'中的所有变量都应使用大括号括起来。
  • 默认值为 [{"key": "knowledge", "optional": True}]。
• rerank_model: str 如果未指定，将使用向量余弦相似度；否则，将使用重新排序分数。默认为 ""。
• empty_response: str 如果在数据集中没有检索到用户问题的内容，将使用此作为响应。为了让LLM在未找到内容时即兴发挥，请将此留空。默认为None。
• opener: str 用户的开场问候语。默认为 "Hi! I am your assistant, can I help you?"。
• show_quote: bool 表示是否应显示文本的来源。默认为 True。
• prompt: str 提示内容。

返回​

• 成功：一个代表聊天助手的Chat对象。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
datasets = rag_object.list_datasets(name="kb_1")
dataset_ids = []
for dataset in datasets:
    dataset_ids.append(dataset.id)
assistant = rag_object.create_chat("Miss R", dataset_ids=dataset_ids)

更新聊天助手​

Chat.update(update_message: dict)

更新当前聊天助手的配置。

参数​

update_message: dict[str, str|list[str]|dict[]], 必填​

表示要更新的属性的字典，包含以下键：

• "name": str 聊天助手的修订名称。
• "avatar": str 头像的Base64编码。默认为 ""
• "dataset_ids": list[str] 要更新的数据集。
• "llm": dict LLM设置:
  • "model_name", str 聊天模型名称。
  • "temperature", float 控制模型预测的随机性。较低的温度会导致更保守的响应，而较高的温度会产生更具创造性和多样性的响应。
  • "top_p", float 也称为“核采样”，此参数设置一个阈值以选择较小的单词集进行采样。
  • "presence_penalty", float 这通过惩罚对话中已经出现的单词来阻止模型重复相同的信息。
  • "frequency penalty", float 类似于存在惩罚，这减少了模型重复相同单词的倾向。
  • "max_token", int 模型输出的最大长度，以令牌（单词或单词片段）的数量衡量。默认为512。如果禁用，您将取消最大令牌限制，允许模型确定其响应中的令牌数量。
• "prompt" : 给LLM的指令。
  • "similarity_threshold": float RAGFlow在检索时使用加权关键词相似度和加权向量余弦相似度的组合，或者加权关键词相似度和加权重排分数的组合。此参数设置用户查询与块之间相似度的阈值。如果相似度分数低于此阈值，相应的块将从结果中排除。默认值为0.2。
  • "keywords_similarity_weight": float 此参数设置关键词相似度在与向量余弦相似度或重排模型相似度的混合相似度分数中的权重。通过调整此权重，您可以控制关键词相似度相对于其他相似度度量的影响。默认值为0.7。
  • "top_n": int 此参数指定相似度分数高于similarity_threshold的前N个块，这些块将被输入到LLM中。LLM将仅访问这些“前N个”块。默认值为8。
  • "variables": list[dict[]] 此参数列出了在聊天配置的“系统”字段中使用的变量。请注意：
    • knowledge 是一个保留变量，表示检索到的块。
    • “系统”中的所有变量都应使用大括号括起来。
    • 默认值为[{"key": "knowledge", "optional": True}]。
  • "rerank_model": str 如果未指定，将使用向量余弦相似度；否则，将使用重排分数。默认为""。
  • "empty_response": str 如果数据集中没有检索到用户问题的内容，将使用此作为响应。如果希望在未检索到内容时让LLM即兴发挥，请将此留空。默认为None。
  • "opener": str 用户的开场问候语。默认为"Hi! I am your assistant, can I help you?"。
  • "show_quote: bool 指示是否应显示文本来源。默认为True。
  • "prompt": str 提示内容。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
datasets = rag_object.list_datasets(name="kb_1")
dataset_id = datasets[0].id
assistant = rag_object.create_chat("Miss R", dataset_ids=[dataset_id])
assistant.update({"name": "Stefan", "llm": {"temperature": 0.8}, "prompt": {"top_n": 8}})

删除聊天助手​

RAGFlow.delete_chats(ids: list[str] = None)

通过ID删除聊天助手。

参数​

ids: list[str]​

要删除的聊天助手的ID。默认为None。如果为空或未指定，将删除系统中的所有聊天助手。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
rag_object.delete_chats(ids=["id_1","id_2"])

列出聊天助手​

RAGFlow.list_chats(
    page: int = 1, 
    page_size: int = 30, 
    orderby: str = "create_time", 
    desc: bool = True,
    id: str = None,
    name: str = None
) -> list[Chat]

列出聊天助手。

参数​

页码: int​

指定显示聊天助手的页面。默认为 1。

页面大小: int​

每页的聊天助手数量。默认为 30。

排序依据: str​

用于排序结果的属性。可用选项：

• "create_time" (默认)
• "update_time"

描述: bool​

指示检索的聊天助手是否应按降序排序。默认为True。

id: str​

要检索的聊天助手的ID。默认为None。

名称: str​

要检索的聊天助手的名称。默认为 None。

返回​

• 成功：返回一个Chat对象的列表。
• 失败：Exception。

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
for assistant in rag_object.list_chats():
    print(assistant)

会话管理​

创建与聊天助手的会话​

Chat.create_session(name: str = "New session") -> Session

创建一个与当前聊天助手的会话。

参数​

名称: str​

要创建的聊天会话的名称。

返回​

• 成功：一个包含以下属性的Session对象：
  • id: str 自动生成的唯一标识符，用于创建的会话。
  • name: str 创建的会话的名称。
  • message: list[Message] 创建的会话的初始消息。默认值：[{"role": "assistant", "content": "Hi! I am your assistant，can I help you?"}]
  • chat_id: str 关联的聊天助手的ID。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
assistant = rag_object.list_chats(name="Miss R")
assistant = assistant[0]
session = assistant.create_session()

更新聊天助手的会话​

Session.update(update_message: dict)

更新当前聊天助手的当前会话。

参数​

update_message: dict[str, Any], 必填​

表示要更新的属性的字典，只有一个键：

• "name": str 会话的修订名称。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
assistant = rag_object.list_chats(name="Miss R")
assistant = assistant[0]
session = assistant.create_session("session_name")
session.update({"name": "updated_name"})

列出聊天助手的会话​

Chat.list_sessions(
    page: int = 1, 
    page_size: int = 30, 
    orderby: str = "create_time", 
    desc: bool = True,
    id: str = None,
    name: str = None
) -> list[Session]

列出与当前聊天助手相关的会话。

参数​

页码: int​

指定将显示会话的页面。默认为 1。

页面大小: int​

每个页面的会话数。默认为 30。

排序依据: str​

会话应排序的字段。可用选项：

• "create_time" (默认)
• "update_time"

描述: bool​

指示检索到的会话是否应按降序排序。默认为True。

id: str​

要检索的聊天会话的ID。默认为None。

名称: str​

要检索的聊天会话的名称。默认为 None。

返回​

• 成功：与当前聊天助手关联的Session对象列表。
• 失败：Exception。

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
assistant = rag_object.list_chats(name="Miss R")
assistant = assistant[0]
for session in assistant.list_sessions():
    print(session)

删除聊天助手的会话​

Chat.delete_sessions(ids:list[str] = None)

通过ID删除当前聊天助手的会话。

参数​

ids: list[str]​

要删除的会话ID。默认为None。如果未指定，将删除与当前聊天助手关联的所有会话。

返回​

• 成功：没有返回值。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
assistant = rag_object.list_chats(name="Miss R")
assistant = assistant[0]
assistant.delete_sessions(ids=["id_1","id_2"])

与聊天助手对话​

Session.ask(question: str = "", stream: bool = False, **kwargs) -> Optional[Message, iter[Message]]

向指定的聊天助手提问以启动AI驱动的对话。

参数​

问题: str, 必填​

启动AI对话的问题。默认为""

流: bool​

指示是否以流式方式输出响应：

• True: 启用流式传输（默认）。
• False: 禁用流式传输。

**kwargs​

提示（系统）中的参数。

返回​

• 如果stream设置为False，则包含问题响应的Message对象。
• 如果stream设置为True，则包含多个message对象的迭代器（iter[Message]）

以下显示了一个Message对象的属性：

id: str​

自动生成的消息ID。

内容: str​

消息的内容。默认为 "Hi! I am your assistant, can I help you?"。

参考: list[Chunk]​

表示消息引用的Chunk对象列表，每个对象包含以下属性：

• id str
  块ID。
• content str
  块的内容。
• img_id str
  快照的ID。仅当块的来源是图像、PPT、PPTX或PDF文件时适用。
• document_id str
  引用文档的ID。
• document_name str
  引用的文档名称。
• position list[str]
  块在引用文档中的位置信息。
• dataset_id str
  引用的文档所属的数据集的ID。
• similarity float
  一个综合相似度评分，范围从0到1，值越高表示相似度越大。它是vector_similarity和term_similarity的加权和。
• vector_similarity float
  一个向量相似度分数，范围从0到1，值越高表示向量嵌入之间的相似度越大。
• term_similarity float
  一个关键词相似度评分，范围从0到1，值越高表示关键词之间的相似度越大。

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
assistant = rag_object.list_chats(name="Miss R")
assistant = assistant[0]
session = assistant.create_session()    

print("\n==================== Miss R =====================\n")
print("Hello. What can I do for you?")

while True:
    question = input("\n==================== User =====================\n> ")
    print("\n==================== Miss R =====================\n")
    
    cont = ""
    for ans in session.ask(question, stream=True):
        print(ans.content[len(cont):], end='', flush=True)
        cont = ans.content

创建与代理的会话​

Agent.create_session(id,rag, **kwargs) -> Session

使用当前代理创建一个会话。

参数​

id: str, 必填​

代理的ID

rag:RAGFlow object​

RAGFlow 对象

**kwargs​

begin 组件中的参数。

返回​

• 成功：一个包含以下属性的Session对象：
  • id: str 自动生成的唯一标识符，用于创建的会话。
  • message: list[Message] 创建的会话助手的消息。默认值：[{"role": "assistant", "content": "Hi! I am your assistant，can I help you?"}]
  • agent_id: str 关联代理的ID。
• 失败: Exception

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
AGENT_ID = "AGENT_ID"
session = create_session(AGENT_ID,rag_object)

与代理对话​

Session.ask(question: str="", stream: bool = False) -> Optional[Message, iter[Message]]

向指定的代理提出问题以启动AI驱动的对话。

参数​

问题: str​

启动一个由AI驱动的对话的问题。如果begin组件接受参数，则不需要问题。

流：bool​

指示是否以流式方式输出响应：

• True: 启用流式传输（默认）。
• False: 禁用流式传输。

返回​

• 一个包含问题响应的Message对象，如果stream设置为False
• 如果stream设置为True，则包含多个message对象的迭代器（iter[Message]）

以下显示了一个Message对象的属性：

id: str​

自动生成的消息ID。

内容: str​

消息的内容。默认为 "Hi! I am your assistant, can I help you?"。

参考: list[Chunk]​

表示消息引用的Chunk对象列表，每个对象包含以下属性：

• id str
  块ID。
• content str
  块的内容。
• image_id str
  分块快照的ID。仅当分块的来源是图像、PPT、PPTX或PDF文件时适用。
• document_id str
  引用文档的ID。
• document_name str
  引用的文档名称。
• position list[str]
  块在引用文档中的位置信息。
• dataset_id str
  引用的文档所属的数据集的ID。
• similarity float
  一个综合相似度评分，范围从0到1，值越高表示相似度越大。它是vector_similarity和term_similarity的加权和。
• vector_similarity float
  一个向量相似度得分，范围从0到1，值越高表示向量嵌入之间的相似度越大。
• term_similarity float
  一个关键词相似度评分，范围从0到1，值越高表示关键词之间的相似度越大。

示例​

from ragflow_sdk import RAGFlow,Agent

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
AGENT_id = "AGENT_ID"
session = Agent.create_session(AGENT_id,rag_object)    

print("\n===== Miss R ====\n")
print("Hello. What can I do for you?")

while True:
    question = input("\n===== User ====\n> ")
    print("\n==== Miss R ====\n")
    
    cont = ""
    for ans in session.ask(question, stream=True):
        print(ans.content[len(cont):], end='', flush=True)
        cont = ans.content

列出代理会话​

Agent.list_sessions(
    agent_id,
    rag
    page: int = 1, 
    page_size: int = 30, 
    orderby: str = "update_time", 
    desc: bool = True,
    id: str = None
) -> List[Session]

列出与当前代理关联的会话。

参数​

页码: int​

指定会话将显示的页面。默认为 1。

页面大小: int​

每个页面的会话数。默认为 30。

排序依据: str​

用于排序会话的字段。可用选项：

• "create_time"
• "update_time"（默认）

描述: bool​

指示检索到的会话是否应按降序排序。默认为True。

id: str​

要检索的代理会话的ID。默认为None。

返回​

• 成功：与当前代理关联的Session对象列表。
• 失败：Exception。

示例​

from ragflow_sdk import RAGFlow

rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
agent_id = "2710f2269b4611ef8fdf0242ac120006"
sessions=Agent.list_sessions(agent_id,rag_object)
for session in sessions:
    print(session)

代理管理​

列出代理​

RAGFlow.list_agents(
    page: int = 1, 
    page_size: int = 30, 
    orderby: str = "create_time", 
    desc: bool = True,
    id: str = None,
    title: str = None
) -> List[Agent]

列出代理。

参数​

页码: int​

指定显示代理的页面。默认为 1。

页面大小: int​

每页上的代理数量。默认为 30。

排序依据: str​

用于排序结果的属性。可用选项：

• "create_time" (默认)
• "update_time"

描述: bool​

指示检索到的代理是否应按降序排序。默认为 True。

id: str​

要检索的代理的ID。默认为None。

名称: str​

要检索的代理名称。默认为 None。

返回​

• 成功：返回一个Agent对象的列表。
• 失败：Exception。

示例​

from ragflow_sdk import RAGFlow
rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
for agent in rag_object.list_agents():
    print(agent)