DataStax

Bundles 按提供方对组件进行分组，这些组件可将第三方服务与 SkillFlaw 集成。

本页介绍 DataStax bundle 中可用的组件，其中包括可对 Astra DB 数据库执行读写的组件。

Astra DB

注意

建议你在配置 Astra DB 组件之前，先创建好所需的数据库、keyspace 和 collection。

你可以通过此组件创建新的数据库和 collection，但这仅能在 SkillFlaw 可视化编辑器中完成（运行时不支持），而且在继续配置 flow 之前，必须等待数据库或 collection 初始化完成。 此外，并非所有数据库和 collection 配置选项都可通过 Astra DB 组件进行设置，例如混合搜索选项、PCU 组、vectorize 集成管理以及多区域部署。

Astra DB 组件使用 AstraDBVectorStore 实例调用 Data API 和 DevOps API，对 Astra DB Serverless 数据库进行读写。

关于向量存储实例

由于 SkillFlaw 基于 LangChain，向量存储组件会使用一个 LangChain 向量存储 实例来驱动底层的读写功能。 这些实例具有提供商特定性，并根据组件参数进行配置，例如连接字符串、索引名称和 schema。

在组件代码中，这通常会被实例化为 vector_store，但某些向量存储组件会使用其他名称，例如提供商名称。

有些 LangChain 类不会将所有可选项都暴露为组件参数。 根据提供商不同，这些选项可能使用默认值，或者在 SkillFlaw 支持的情况下通过环境变量进行修改。 有关具体选项，请参阅 LangChain API 参考和向量存储提供商文档。

Astra DB 参数

你可以查看向量存储组件的参数，以了解它可接受的输入、支持的功能以及配置方式。

有些参数在可视化编辑器中默认处于隐藏状态。 你可以通过组件标题栏菜单中的 控件 来修改全部参数。

有些参数是条件参数，只有在你设置了其他参数，或为其他参数选择了特定选项之后才会显示。 在满足所需依赖之前，条件参数可能不会出现在 控件 面板中。

有关可接受值和功能的信息，请参见 Astra DB Serverless documentation 或查看组件代码。

Name	Display Name	Info
token	Astra DB Application Token	输入参数。Astra application token，用于访问你的向量数据库。连接验证成功后，系统会用你现有的数据库和 collection 填充其他字段。如果你希望通过此组件创建数据库，则该 application token 必须具备 Organization Administrator 权限。
environment	Environment	输入参数。Astra DB API endpoint 所处的环境。通常始终为 prod。
database_name	Database	输入参数。此组件要连接的数据库名称。或者，你也可以选择 New Database 创建新数据库，然后等待数据库初始化完成后再设置其余参数。
endpoint	Astra DB API Endpoint	输入参数。对于多区域数据库，选择距离你最近的数据中心所对应的 API endpoint。要获取多区域数据库的区域列表，请参见 List database regions。选择数据库后，此字段会自动填充，默认使用主区域的 endpoint。
keyspace	Keyspace	输入参数。数据库中包含 collection_name 指定 collection 的 keyspace。默认值：default_keyspace。
collection_name	Collection	输入参数。此 flow 要使用的 collection 名称。或者，选择 New Collection 创建一个配置选项有限的新 collection。为了确保 collection 使用正确的 embedding provider 和搜索能力，建议你在配置此组件之前，先在 Astra Portal 或通过 Data API 创建 collection。有关更多信息，请参见 Manage collections in Astra DB Serverless。
embedding_model	Embedding Model	输入参数。连接一个 embedding model 组件 以生成 embeddings。仅当指定 collection 不具有 vectorize integration 时可用。如果存在 vectorize integration，组件会自动使用该 collection 集成的模型。
ingest_data	Ingest Data	输入参数。要加载到指定 collection 中的文档。接受 Data 或 DataFrame 输入。
search_query	Search Query	输入参数。用于向量搜索的查询字符串。
cache_vector_store	Cache Vector Store	输入参数。是否将向量存储缓存到 SkillFlaw 内存中以加快读取速度。默认值：启用（true）。
search_method	Search Method	输入参数。要使用的搜索方式，可选 Hybrid Search 或 Vector Search。你的 collection 必须已配置为支持所选选项，默认值取决于 collection 的支持能力。Astra DB Serverless（vector）数据库中所有启用向量的 collection 都支持向量搜索，但混合搜索要求你在创建 collection 时设置特定的 collection 配置。这些选项仅在以编程方式创建 collection 时可用。有关更多信息，请参见 Ways to find data in Astra DB Serverless 和 Create a collection that supports hybrid search。
reranker	Reranker	输入参数。用于混合搜索的 re-ranker 模型，具体取决于 collection 的配置。此参数仅适用于支持混合搜索的 collection。要判断 collection 是否支持混合搜索，请先获取 collection metadata，然后检查 lexical 和 rerank 是否都具有 "enabled": true。
lexical_terms	Lexical Terms	输入参数。用于混合搜索的空格分隔关键词字符串，例如 features, data, attributes, characteristics。此参数仅在 collection 支持混合搜索时可用。有关更多信息，请参见混合搜索示例。
number_of_results	Number of Search Results	输入参数。返回的搜索结果数。默认值：4。
search_type	Search Type	输入参数。要使用的搜索类型，可选 Similarity（默认）、Similarity with score threshold 和 MMR (Max Marginal Relevance)。
search_score_threshold	Search Score Threshold	输入参数。当搜索类型为 Similarity with score threshold 时，向量搜索结果允许的最小相似度分数阈值。默认值：0。
advanced_search_filter	Search Metadata Filter	输入参数。可选的 metadata filter 字典，会在向量搜索或混合搜索之外额外应用。
autodetect_collection	Autodetect Collection	输入参数。提供 application token 和 API endpoint 后，是否自动获取可用 collection 列表。
content_field	Content Field	输入参数。对于写入操作，此参数指定文档中包含文本字符串的字段名，这些文本将用于生成 embeddings。
deletion_field	Deletion Based On Field	输入参数。提供该参数后，目标 collection 中 metadata 字段值与输入 metadata 字段值匹配的文档，会在加载新记录前先被删除。将该设置用于支持 upsert（覆盖写入）的写操作。
ignore_invalid_documents	Ignore Invalid Documents	输入参数。写入过程中是否忽略无效文档。如果禁用（false），遇到无效文档时会抛出错误。默认值：启用（true）。
astradb_vectorstore_kwargs	AstraDBVectorStore Parameters	输入参数。传递给 AstraDBVectorStore 实例的附加参数，可选字典。

Astra DB 示例

示例：Vector RAG

提示

有关在流程中使用向量数据的教程，请参阅创建向量 RAG 聊天机器人。

下面的示例演示了如何在流程中将向量存储组件与嵌入模型、语言模型等相关组件配合使用。 这些步骤会说明重要的配置细节、功能要点以及高效使用这些组件的最佳实践。 这只是一个示例，并不是对所有可能用例或配置方式的唯一规范。

1. 使用 Vector Store RAG 模板创建一个流程。

   该模板包含两个子流程。 Load Data 子流程会将嵌入和内容加载到向量数据库中，而 Retriever 子流程会运行向量搜索，根据用户查询检索相关上下文。

2. 为两组 Astra DB 组件 配置数据库连接，或者将它们替换为你选择的另一组向量存储组件。 确保这些组件连接到同一个向量存储，并且 Retriever 子流程中的组件能够执行相似度搜索。

   你在每个向量存储组件中设置的参数，取决于该组件在流程中的角色。 在这个示例中，Load Data 子流程负责向向量存储中 写入 数据，而 Retriever 子流程负责从向量存储中 读取 数据。 因此，与搜索相关的参数只与 Retriever 子流程中的 Vector Search 组件有关。

   有关具体参数，请参阅你所选向量存储组件的文档。

3. 配置嵌入模型时，可以执行以下任一操作：

   • 使用 OpenAI 模型：在两个 OpenAI Embeddings 组件中输入你的 OpenAI API 密钥。 你可以使用默认模型，也可以选择其他 OpenAI 嵌入模型。

   • 使用其他提供商：将两个 OpenAI Embeddings 组件替换为你选择的另一组嵌入模型组件，然后相应地配置参数和凭据。

   • 使用 Astra DB vectorize：如果你使用的 Astra DB 向量存储已启用 vectorize 集成，则可以移除两个 OpenAI Embeddings 组件。 这样一来，vectorize 集成会自动根据 Ingest Data（位于 Load Data 子流程）和 Search Query（位于 Retriever 子流程）生成嵌入。

   提示

   如果你的向量存储中已经存在嵌入，请确保当前嵌入模型组件使用的模型与之前生成这些嵌入时使用的模型一致。 在同一个向量存储中混用不同的嵌入模型，可能会导致搜索结果不准确。

4. 推荐：在 Split Text 组件 中，根据嵌入模型优化分块设置。 例如，如果你的嵌入模型 token 限制为 512，那么 Chunk Size 参数就不能超过这个上限。

   此外，由于 Retriever 子流程会将聊天输入直接传给向量存储组件执行向量搜索，请确保聊天输入字符串不要超过嵌入模型的限制。 在本示例中，你可以直接输入一个符合限制的查询；但在生产环境中，你可能需要增加额外检查或预处理步骤，以确保满足这些约束。 例如，可以在执行向量搜索之前，用其他组件先处理聊天输入，或者在应用代码中强制限制聊天输入长度。

5. 在 Language Model 组件中输入你的 OpenAI API 密钥，或者选择其他提供商和模型来处理流程中的聊天部分。

6. 运行 Load Data 子流程，将数据写入你的向量存储。 在 Read File 组件中选择一个或多个文件，然后在 Load Data 子流程中的向量存储组件上点击 运行组件。

   Load Data 子流程会从本地机器加载文件，对其分块，为各个分块生成嵌入，然后将分块及其嵌入写入向量数据库。

   

   Load Data 子流程之所以与 Retriever 子流程分开，是因为你通常不会在每次聊天时都重新运行它。 你可以按需运行 Load Data 子流程，为向量存储预加载或更新数据。 之后，聊天交互只需使用执行聊天所必需的那些组件。

   如果你的向量存储中已经包含可用于向量搜索的数据，那么你就不需要运行 Load Data 子流程。

7. 打开 Playground 并开始聊天，以运行 Retriever 子流程。

   Retriever 子流程会根据聊天输入生成嵌入，执行向量搜索以从向量存储中检索相似内容，将搜索结果解析为 LLM 的补充上下文，然后由 LLM 根据你的查询生成自然语言回复。 LLM 会结合向量搜索结果、自身内部训练数据以及其他工具（例如基础网页搜索和日期时间信息）来生成响应。

   

   为了避免把整块原始搜索结果直接传给 LLM，Parser 组件会从搜索结果的 Data 对象中提取 text 字符串，并以 Message 格式传给 Prompt Template 组件。 然后，这些字符串和其他模板内容会被整理成给 LLM 的自然语言指令。

   你也可以使用其他组件来完成这种转换，例如 Data Operations 组件，具体取决于你希望如何使用搜索结果。

   如果你想查看原始搜索结果，请在运行 Retriever 子流程后，点击向量存储组件上的 检查输出。

示例：混合搜索

Astra DB 组件支持 Data API 的混合搜索功能。 混合搜索会同时执行向量相似性搜索和词法搜索，比较两者的结果，然后整体返回最相关的结果。

要通过 Astra DB 组件使用混合搜索，请执行以下操作：

1. 如果你还没有支持混合搜索的 collection，请先使用 Data API create a collection that supports hybrid search。

   虽然你也可以通过 Astra DB 组件创建 collection，但使用 Data API 执行此操作时，你可以对 collection 设置获得更多控制和可见性。

2. 基于 Hybrid Search RAG 模板创建一个 flow，其中已经包含一个为混合搜索预先配置好的 Astra DB 组件。

   加载模板后，检查各组件上是否有 Upgrade available 提示。 如果有任何组件正在等待升级，请在继续之前先升级并重新连接它们。

3. 在 Language Model 组件中，添加你的 OpenAI API key。 如果你想使用其他 provider 或 model，请参见语言模型组件。

4. 删除连接到 Structured Output 组件 Input Message 端口的 Language Model 组件，然后将 Chat Input 组件连接到该端口。

5. 配置 Astra DB 向量存储组件：

   1. 输入你的 Astra DB application token。
   2. 在 Database 字段中，选择你的数据库。
   3. 在 Collection 字段中，选择你已启用混合搜索的 collection。

   一旦你选择了支持混合搜索的 collection，其他参数会自动更新，以提供混合搜索选项。

6. 将第一个 Parser 组件的 Parsed Text 输出连接到 Astra DB 组件的 Lexical Terms 输入。 只有在连接到支持带 reranking 的混合搜索 collection 之后，该输入才会出现。

7. 更新 Structured Output 模板：

   1. 点击 Structured Output 组件以显示组件标题菜单，然后点击 Controls。

   2. 找到 Format Instructions 行，点击 Expand，然后将 prompt 替换为以下文本：

      
      

      _10

      You are a database query planner that takes a user's requests, and then converts to a search against the subject matter in question.

      _10

      You should convert the query into:

      _10

      1. A list of keywords to use against a Lucene text analyzer index, no more than 4. Strictly unigrams.

      _10

      2. A question to use as the basis for a QA embedding engine.

      _10

      Avoid common keywords associated with the user's subject matter.

      
      

   3. 点击 Finish Editing，然后点击 Close，将更改保存到该组件。

8. 打开 Playground，然后输入一个你会向数据库提出的自然语言问题。

   在此示例中，你的输入会同时发送到 Astra DB 和 Structured Output 组件：

   • 直接发送到 Astra DB 组件 Search Query 端口的输入，会作为字符串用于相似性搜索。 查询字符串会使用 collection 的 Astra DB vectorize integration 生成 embedding。

   • 发送到 Structured Output 组件的输入，会由 Structured Output、Language Model 和 Parser 组件处理，以提取用于混合搜索词法部分的空格分隔 keywords。

   完整的混合搜索查询会通过 Data API 的 find_and_rerank 命令在你的数据库上执行。 API 的响应会作为 DataFrame 输出，然后再由另一个 Parser 组件转换为文本字符串 Message。 最后，Chat Output 组件会将 Message 响应打印到 Playground。

9. 可选：退出 Playground，然后点击每个单独组件上的 Inspect Output，以了解词法关键词是如何构造的，并查看 Data API 的原始响应。 这对于调试某个组件未按预期从另一个组件接收输入的 flow 很有帮助。

   • Structured Output component：输出是将输出 schema 应用于 LLM 对输入消息和格式说明的响应后得到的 Data 对象。 以下示例基于前述的关键词提取说明：

     
     

     _10

     1. Keywords: features, data, attributes, characteristics

     _10

     2. Question: What characteristics can be identified in my data?

     
     

   • Parser component：输出是从结构化输出 Data 中提取出的关键词字符串，随后将其用作混合搜索的词法项。

   • Astra DB component：输出是 DataFrame，其中包含由 Data API 返回的混合搜索结果。

Astra DB 输出

如果你使用向量存储组件查询向量数据库，它会生成搜索结果，你可以将这些结果作为 Data 对象列表或表格形式的 DataFrame 传递给流程中的下游组件。 如果同时支持这两种类型，你可以在可视化编辑器中、向量存储组件输出端口附近设置输出格式。

Vector Store Connection 端口

Astra DB 组件额外提供一个 Vector Store Connection 输出。 该输出只能连接到 VectorStore 输入端口，原本用于专门的 Graph RAG 组件。

唯一支持此输入的非 legacy 组件是 Graph RAG 组件，它可以作为 Astra DB 组件的 Graph RAG 扩展。 不过，建议改用同时包含向量存储连接与 Graph RAG 功能的 Astra DB Graph 组件。

Astra DB CQL

Astra DB CQL 组件允许代理查询 Astra DB 中 CQL 表的数据。

输出是包含 Astra DB CQL 表查询结果的 Data 对象列表。每个 Data 对象都包含由 projection fields 指定的文档字段，结果数量受 number_of_results 参数限制。

Astra DB CQL 参数

有些参数在可视化编辑器中默认处于隐藏状态。 你可以通过组件标题栏菜单中的 控件 来修改全部参数。

Name	Type	Description
Tool Name	String	输入参数。在代理 prompt 中引用该工具时使用的名称。
Tool Description	String	输入参数。该工具的简要描述，用于指导模型如何使用它。
Keyspace	String	输入参数。keyspace 的名称。
Table Name	String	输入参数。要查询的 Astra DB CQL 表名。
Token	SecretString	输入参数。Astra DB 的身份验证 token。
API Endpoint	String	输入参数。Astra DB API endpoint。
Projection Fields	String	输入参数。要返回的属性，以逗号分隔。默认值："*"。
Partition Keys	Dict	输入参数。模型必须填写的必填参数，以便查询该工具。
Clustering Keys	Dict	输入参数。模型可填写的可选参数，用于细化查询。必填参数应使用感叹号标记，例如 !customer_id。
Static Filters	Dict	输入参数。用于筛选查询结果的属性-值对。
Limit	String	输入参数。要返回的记录数。

Graph RAG

Graph RAG 组件使用 GraphRetriever 实例进行 Graph RAG 遍历，从而在 Astra DB 向量存储中启用基于图的文档检索。 有关更多信息，请参见 DataStax Graph RAG documentation。

Graph RAG 参数

你可以查看向量存储组件的参数，以了解它可接受的输入、支持的功能以及配置方式。

有些参数在可视化编辑器中默认处于隐藏状态。 你可以通过组件标题栏菜单中的 控件 来修改全部参数。

有些参数是条件参数，只有在你设置了其他参数，或为其他参数选择了特定选项之后才会显示。 在满足所需依赖之前，条件参数可能不会出现在 控件 面板中。

Name	Display Name	Info
embedding_model	Embedding Model	输入参数。指定要使用的 embedding model。如果已连接的向量存储具有 vectorize integration，则不是必需项。
vector_store	Vector Store Connection	输入参数。从Astra DB 组件的 Vector Store Connection 输出继承而来的 AstraDbVectorStore 实例。
edge_definition	Edge Definition	输入参数。用于图遍历的 Edge definition。
strategy	Traversal Strategies	输入参数。图遍历所使用的策略。策略选项会根据可用策略动态加载。
search_query	Search Query	输入参数。要在向量存储中搜索的查询。
graphrag_strategy_kwargs	Strategy Parameters	输入参数。用于检索策略的附加参数，可选字典。
search_results	Search Results or DataFrame	输出参数。基于图的文档检索结果，可输出为 Data 对象列表或表格形式的 DataFrame。你可以在组件输出端口附近设置所需的输出类型。

Hyper-Converged Database (HCD)

Hyper-Converged Database (HCD) 组件使用你集群的 Data API server 对 HCD 向量存储进行读写。 由于底层函数调用的是源自 Astra DB 的 Data API，因此该组件使用 AstraDBVectorStore 实例。

关于向量存储实例

由于 SkillFlaw 基于 LangChain，向量存储组件会使用一个 LangChain 向量存储 实例来驱动底层的读写功能。 这些实例具有提供商特定性，并根据组件参数进行配置，例如连接字符串、索引名称和 schema。

在组件代码中，这通常会被实例化为 vector_store，但某些向量存储组件会使用其他名称，例如提供商名称。

有些 LangChain 类不会将所有可选项都暴露为组件参数。 根据提供商不同，这些选项可能使用默认值，或者在 SkillFlaw 支持的情况下通过环境变量进行修改。 有关具体选项，请参阅 LangChain API 参考和向量存储提供商文档。

如果你使用向量存储组件查询向量数据库，它会生成搜索结果，你可以将这些结果作为 Data 对象列表或表格形式的 DataFrame 传递给流程中的下游组件。 如果同时支持这两种类型，你可以在可视化编辑器中、向量存储组件输出端口附近设置输出格式。

有关 HCD 的更多信息，请参见 Get started with HCD 1.2 和 Get started with the Data API in HCD 1.2。

HCD 参数

你可以查看向量存储组件的参数，以了解它可接受的输入、支持的功能以及配置方式。

有些参数在可视化编辑器中默认处于隐藏状态。 你可以通过组件标题栏菜单中的 控件 来修改全部参数。

有些参数是条件参数，只有在你设置了其他参数，或为其他参数选择了特定选项之后才会显示。 在满足所需依赖之前，条件参数可能不会出现在 控件 面板中。

Name	Display Name	Info
collection_name	Collection Name	输入参数。HCD 中某个向量存储 collection 的名称。对于写入操作，如果 collection 不存在，则会创建一个新的。必填。
username	HCD Username	输入参数。用于对 HCD 部署进行身份验证的用户名。默认值：hcd-superuser。必填。
password	HCD Password	输入参数。用于对 HCD 部署进行身份验证的密码。必填。
api_endpoint	HCD API Endpoint	输入参数。你的部署所使用的 HCD Data API endpoint，格式为 http[s]://CLUSTER_HOST:GATEWAY_PORT，其中 CLUSTER_HOST 是集群中任意节点的 IP 地址，GATEWAY_PORT 是 API gateway service 的端口号。例如 http://192.0.2.250:8181。必填。
ingest_data	Ingest Data	输入参数。要加载到向量存储中的记录。仅在写入时相关。
search_input	Search Input	输入参数。用于相似性搜索的查询字符串。仅在读取时相关。
namespace	Namespace	输入参数。HCD 中包含或将包含 collection_name 指定 collection 的 namespace。默认值：default_namespace。
ca_certificate	CA Certificate	输入参数。用于连接到 HCD 的 TLS 可选 CA 证书。
metric	Metric	输入参数。用于相似性搜索计算的 metric，可选 cosine、dot_product 或 euclidean。这是 collection 级设置。如果调用现有 collection，请留空以使用该 collection 的 metric。如果写操作会创建新 collection，请指定所需的相似度 metric 设置。
batch_size	Batch Size	输入参数。单批处理记录的数量，可选。
bulk_insert_batch_concurrency	Bulk Insert Batch Concurrency	输入参数。批量写操作的并发级别，可选。
bulk_insert_overwrite_concurrency	Bulk Insert Overwrite Concurrency	输入参数。允许 upsert（覆盖已有记录）的批量写操作并发级别，可选。
bulk_delete_concurrency	Bulk Delete Concurrency	输入参数。批量删除操作的并发级别，可选。
setup_mode	Setup Mode	输入参数。用于设置向量存储的配置模式，可选 Sync（默认）、Async 或 Off。
pre_delete_collection	Pre Delete Collection	输入参数。在创建新 collection 之前是否先删除该 collection。
metadata_indexing_include	Metadata Indexing Include	输入参数。如果你希望仅在创建 collection 时启用选择性索引，可通过该参数提供需要建立索引的 metadata 字段列表。对现有 collection 不生效。每个 collection 只能设置一个 *_indexing_* 参数。如果所有 *_indexing_* 参数都未设置，则会为所有字段建立索引（默认索引）。
metadata_indexing_exclude	Metadata Indexing Exclude	输入参数。如果你希望仅在创建 collection 时启用选择性索引，可通过该参数提供需要排除索引的 metadata 字段列表。对现有 collection 不生效。每个 collection 只能设置一个 *_indexing_* 参数。如果所有 *_indexing_* 参数都未设置，则会为所有字段建立索引（默认索引）。
collection_indexing_policy	Collection Indexing Policy	输入参数。如果你希望仅在创建 collection 时启用选择性索引，可通过字典定义索引策略。对现有 collection 不生效。每个 collection 只能设置一个 *_indexing_* 参数。如果所有 *_indexing_* 参数都未设置，则会为所有字段建立索引（默认索引）。当你需要对字段的子字段建立索引，或需要列表形式不兼容的复杂索引定义时，可使用 collection_indexing_policy 字典。
embedding	Embedding or Astra Vectorize	输入参数。通过连接 Embedding Model 组件来指定要使用的 embedding model。该组件不支持附加的 vectorize 身份验证 header，因此即使你已在现有 HCD collection 上启用了 vectorize integration，也无法在此组件中使用它。
number_of_results	Number of Results	输入参数。返回的搜索结果数。默认值：4。仅在读取时相关。
search_type	Search Type	输入参数。要使用的搜索类型，可选 Similarity（默认）、Similarity with score threshold 或 MMR (Max Marginal Relevance)。仅在读取时相关。
search_score_threshold	Search Score Threshold	输入参数。当 search_type 为 Similarity with score threshold 时，搜索结果允许的最小相似度分数阈值。默认值：0。
search_filter	Search Metadata Filter	输入参数。可选的 metadata filter 字典，会在向量搜索之外额外应用。

其他 DataStax 组件

以下组件也包含在 DataStax bundle 中。

Astra DB Chat Memory

Astra DB Chat Memory 组件使用 Astra DB 数据库来检索和存储聊天消息。

聊天记忆会以 Memory 数据类型在记忆存储组件之间传递。 具体来说，该组件会创建 AstraDBChatMessageHistory 实例，这是一个使用 Astra DB 进行存储的 LangChain 聊天消息历史类。

注意

对于大多数记忆存储场景，不推荐使用 Astra DB Chat Memory 组件，因为记忆通常是较长的 JSON 对象或字符串，经常会超出 Astra DB 所支持的单个文档或对象最大大小。

不过，SkillFlaw 的 Agent 组件内置了聊天记忆，并且默认启用。 你的代理型 flow 不需要外部数据库来存储聊天记忆。 有关更多信息，请参见记忆管理选项。

有关在 flow 中使用外部聊天记忆的更多信息，请参见 Message History 组件。

Astra DB Chat Memory 参数

有些参数在可视化编辑器中默认处于隐藏状态。 你可以通过组件标题栏菜单中的 控件 来修改全部参数。

Name	Type	Description
collection_name	String	输入参数。用于存储消息的 Astra DB collection 名称。必填。
token	SecretString	输入参数。用于访问 Astra DB 的身份验证 token。必填。
api_endpoint	SecretString	输入参数。Astra DB service 的 API endpoint URL。必填。
namespace	String	输入参数。Astra DB 中该 collection 所在的可选 namespace。
session_id	MessageText	输入参数。聊天会话的唯一标识符。如果未提供，则使用当前会话 ID。

Legacy DataStax 组件

遗留组件已不再作为当前受支持能力的一部分，未来版本中可能会被移除。 你仍然可以在已有流程中继续使用它们，但建议尽快替换为当前受支持的组件。 若存在明确替代项，通常会在流程中组件卡片上的 遗留 标记、发布说明或 SkillFlaw 文档中给出说明。

如果你暂时不确定该如何替换某个遗留组件，可以先通过 Search 按提供商、服务或组件名称查找。 某些组件可能已经被全新的组件、相似组件，或其他分类下的同类新版本替代。

如果没有直接可见的替代项，也可以判断是否能用其他组件适配你的场景。 例如，许多 流程组件 提供的是可复用于多种提供商和业务场景的通用能力，例如 API Request 组件。

如果上述方式都不适用，你也可以参考遗留组件的实现代码自行封装自定义组件，或前往发起讨论反馈该遗留组件的替代需求。

为了避免在新流程中继续使用这些组件，系统默认会隐藏遗留组件。 在可视化编辑器中，你可以点击 组件设置，切换 遗留 过滤项的显示状态。

以下 DataStax 组件处于 legacy 状态：

Astra DB Tool

请使用Astra DB 组件替代 Astra DB Tool 组件。

Astra DB Tool 组件支持在 Astra DB collection 中搜索数据，包括混合搜索、向量搜索和常规基于 filter 的搜索。 特定搜索类型要求 collection 已预先配置好所需参数。

输出为 Data 对象列表，其中包含从 Astra DB 返回的查询结果。每个 Data 对象都包含 projection attributes 指定的文档字段。结果数量受 number_of_results 参数以及 Astra DB Data API 的上限约束，具体取决于搜索类型。

你可以将该组件作为 flow 中的独立步骤直接执行查询，或者将其作为代理工具连接给代理，使代理能够在需要响应用户查询时按需查询 Astra DB collection 中的数据。

Collection Name、Astra DB Application Token 和 Astra DB API Endpoint 的值可在你的 Astra DB 部署中找到。有关更多信息，请参见 Astra DB Serverless documentation。

Name	Type	Description
Tool Name	String	输入参数。在代理 prompt 中引用该工具时使用的名称。
Tool Description	String	输入参数。工具的简要描述。这有助于模型判断何时使用它。
Keyspace Name	String	输入参数。Astra DB 中 keyspace 的名称。默认值：default_keyspace
Collection Name	String	输入参数。要查询的 Astra DB collection 名称。
Token	SecretString	输入参数。用于访问 Astra DB 的身份验证 token。
API Endpoint	String	输入参数。Astra DB API endpoint。
Projection Fields	String	输入参数。要从匹配文档中返回的属性列表，以逗号分隔。默认值为默认投影 *，它会返回除 $vector 等保留字段之外的所有属性。
Tool Parameters	Dict	输入参数。可作为代理工具使用的 Astra DB Data API find filters。如果代理选择了这些 Filters，它们_可能_会在搜索中使用。
Static Filters	Dict	输入参数。用于筛选查询结果的属性-值对。等同于 Astra DB Data API find filters。Static Filters 会随_每一次_查询一并使用。若不结合语义搜索而仅使用 Static Filters，则执行的是常规 filter 搜索。
Number of Results	Int	输入参数。要返回的最大文档数。
Semantic Search	Boolean	输入参数。是否通过从聊天输入生成向量 embedding 并遵循 Semantic Search Instruction 来执行相似性搜索。默认值：false。如果为 true，你必须连接一个 embedding model 组件，或确保你的 collection 已预先启用 vectorize。
Use Astra DB Vectorize	Boolean	输入参数。运行语义搜索时，是否使用 Astra DB vectorize 功能生成 embeddings。默认值：false。如果为 true，你的 collection 必须已预先启用 vectorize。
Embedding Model	Embedding	输入参数。用于连接 embedding model 组件的端口，以便在语义搜索时从输入文本生成向量。该方式可在 Semantic Search 为 true 时使用，无论是否启用 vectorize。请确保所用模型与 collection 中已有 embeddings 的维度一致。
Semantic Search Instruction	String	输入参数。用于相似性搜索的查询说明。默认值："Find documents similar to the query."。该说明用于指导模型执行语义搜索。

Astra DB Graph

请使用Graph RAG 组件替代 Astra DB Graph 组件。

Astra DB Graph 组件使用 AstraDBGraphVectorStore，这是一个 LangChain graph vector store 实例，用于在 Astra DB collection 中执行图遍历和基于图的文档检索。它还支持向向量存储写入数据。 有关更多信息，请参见 Build a Graph RAG system with LangChain and GraphRetriever。

你可以查看向量存储组件的参数，以了解它可接受的输入、支持的功能以及配置方式。

有些参数在可视化编辑器中默认处于隐藏状态。 你可以通过组件标题栏菜单中的 控件 来修改全部参数。

有些参数是条件参数，只有在你设置了其他参数，或为其他参数选择了特定选项之后才会显示。 在满足所需依赖之前，条件参数可能不会出现在 控件 面板中。

有关可接受值和功能的信息，请参见 Astra DB Serverless documentation 或查看组件代码。

Name	Display Name	Info
token	Astra DB Application Token	输入参数。Astra application token，用于访问你的向量数据库。连接验证成功后，系统会用你现有的数据库和 collection 填充其他字段。如果你希望通过此组件创建数据库，则该 application token 必须具备 Organization Administrator 权限。
api_endpoint	API Endpoint	输入参数。你的数据库 API endpoint。
keyspace	Keyspace	输入参数。数据库中包含 collection_name 指定 collection 的 keyspace。默认值：default_keyspace。
collection_name	Collection	输入参数。此 flow 要使用的 collection 名称。对于写入操作，如果不存在匹配的 collection，则会创建一个新的。
metadata_incoming_links_key	Metadata Incoming Links Key	输入参数。向量存储中 incoming links 使用的 metadata key。
ingest_data	Ingest Data	输入参数。要加载到向量存储中的记录。仅在写入时相关。
search_input	Search Query	输入参数。用于相似性搜索的查询字符串。仅在读取时相关。
cache_vector_store	Cache Vector Store	输入参数。是否将向量存储缓存到 SkillFlaw 内存中以加快读取速度。默认值：启用（true）。
embedding_model	Embedding Model	输入参数。连接一个 embedding model 组件 以生成 embeddings。如果 collection 已具备 vectorize integration，则不要连接 embedding model 组件。
metric	Metric	输入参数。用于相似性搜索计算的 metric，可选 cosine（默认）、dot_product 或 euclidean。这是 collection 级设置。
batch_size	Batch Size	输入参数。单批处理记录的数量，可选。
bulk_insert_batch_concurrency	Bulk Insert Batch Concurrency	输入参数。批量写操作的并发级别，可选。
bulk_insert_overwrite_concurrency	Bulk Insert Overwrite Concurrency	输入参数。允许 upsert（覆盖已有记录）的批量写操作并发级别，可选。
bulk_delete_concurrency	Bulk Delete Concurrency	输入参数。批量删除操作的并发级别，可选。
setup_mode	Setup Mode	输入参数。用于设置向量存储的配置模式，可选 Sync（默认）或 Off。
pre_delete_collection	Pre Delete Collection	输入参数。在创建新 collection 之前是否先删除该 collection。默认值：禁用（false）。
metadata_indexing_include	Metadata Indexing Include	输入参数。如果你希望仅在创建 collection 时启用选择性索引，可通过该参数提供需要建立索引的 metadata 字段列表。对现有 collection 不生效。每个 collection 只能设置一个 *_indexing_* 参数。如果所有 *_indexing_* 参数都未设置，则会为所有字段建立索引（默认索引）。
metadata_indexing_exclude	Metadata Indexing Exclude	输入参数。如果你希望仅在创建 collection 时启用选择性索引，可通过该参数提供需要排除索引的 metadata 字段列表。对现有 collection 不生效。每个 collection 只能设置一个 *_indexing_* 参数。如果所有 *_indexing_* 参数都未设置，则会为所有字段建立索引（默认索引）。
collection_indexing_policy	Collection Indexing Policy	输入参数。如果你希望仅在创建 collection 时启用选择性索引，可通过字典定义索引策略。对现有 collection 不生效。每个 collection 只能设置一个 *_indexing_* 参数。如果所有 *_indexing_* 参数都未设置，则会为所有字段建立索引（默认索引）。当你需要对字段的子字段建立索引，或需要列表形式不兼容的复杂索引定义时，可使用 collection_indexing_policy 字典。
number_of_results	Number of Results	输入参数。返回的搜索结果数。默认值：4。仅在读取时相关。
search_type	Search Type	输入参数。要使用的搜索类型，可选 Similarity、Similarity with score threshold、MMR (Max Marginal Relevance)、Graph Traversal 或 MMR (Max Marginal Relevance) Graph Traversal（默认）。仅在读取时相关。
search_score_threshold	Search Score Threshold	输入参数。当搜索类型为 Similarity with score threshold 时，搜索结果允许的最小相似度分数阈值。默认值：0。
search_filter	Search Metadata Filter	输入参数。可选的 metadata filter 字典，会在向量搜索之外额外应用。

Assistants API 组件

以下 DataStax 组件曾用于在 flow 中创建和管理 Assistants API 功能：

• Astra Assistant Agent
• Create Assistant
• Create Assistant Thread
• Get Assistant Name
• List Assistants
• Run Assistant

这些组件属于 legacy，应替换为 SkillFlaw 原生 agent 组件。

环境变量组件

以下 DataStax 组件曾用于在 flow 中加载和获取环境变量：

• Dotenv：从 .env 文件加载环境变量
• Get Environment Variable：获取环境变量的值

这些组件属于 legacy。请改用 SkillFlaw 内置的环境变量支持或全局变量。

Astra Vectorize

该组件在更早版本中已被弃用。 请使用Astra DB 组件替代。

Astra DB Vectorize 组件曾与 Astra DB 组件配合使用，通过 Astra DB 的 vectorize 功能生成 embeddings。

vectorize 功能现已内置到 Astra DB 组件中。 你不再需要单独的组件来进行 vectorize embedding 生成。

另请参见

• Cassandra bundle
• 创建向量 RAG 聊天机器人