pinecone-n8n

Pinecone n8n 工作流技能

<<invoke_this_skill>>

此技能可帮助你遵循最佳实践，使用 Pinecone 节点构建 n8n 工作流。它涵盖两个 Pinecone 节点：

• Pinecone Assistant（@pinecone-database/n8n-nodes-pinecone-assistant）——推荐用于大多数场景
• Pinecone Vector Store（@n8n/n8n-nodes-langchain.vectorStorePinecone）——适用于需要高级控制的场景

**核心规则：**始终使用节点内置的资源和操作。切勿建议使用 HTTP 节点直接调用 Pinecone REST API。

---

第 1 步：了解用户的场景

询问用户想要完成什么：

• 从头开始构建新的工作流
• 配置或了解特定的 Pinecone 节点
• 调试无法正常运行的工作流
• 根据最佳实践检查现有工作流

---

第 2 步：选择节点（适用于新工作流和配置问题）

始终首先将 Pinecone Assistant 节点作为推荐选项。不要根据自己的判断跳过此步骤，认为某个节点更合适——即使使用场景提到了特定触发器（Google Drive、webhook 等）或文件类型（文本、markdown、PDF），这些细节也无法决定应使用哪个节点。

仅在以下情况下跳过此步骤：

• 用户明确指定了某个节点（例如“我想使用 Vector Store 节点”“帮我设置 pineconeAssistant”）
• 用户正在调试或配置现有工作流，且其中已包含特定的 Pinecone 节点

**如果用户未指定节点，始终先询问或推荐 Assistant 节点。**如果用户表示“使用默认设置”，或者你无法提问，则默认使用 Pinecone Assistant 节点，并按 Assistant 流程继续。

询问用户想使用哪个节点，并提供以下两个选项：

Pinecone Assistant（推荐）

• 全托管 RAG——Pinecone 自动处理分块、嵌入和索引
• 内置引用，包含文件名和 URL
• 设置更简单：无需在 n8n 中配置嵌入模型或文本分割器
• 适用于：文档问答、与文件聊天、知识库搜索

Pinecone Vector Store

• 可完全控制嵌入模型、分块策略和元数据
• 兼容任何嵌入模型（OpenAI、Cohere、HuggingFace 等）
• 适用于以下情况：需要自定义嵌入、已有 Pinecone 索引、需要元数据筛选，或需要精细控制分块

---

Pinecone Assistant 节点——最佳实践和工作流生成

节点包名称

• 文件操作（上传、列出、删除）：@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant
• 作为 AI Agent 工具进行聊天/检索：@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistantTool

前提条件

• 运行工作流前，请在 Pinecone Console 中创建 Pinecone Assistant：https://app.pinecone.io/organizations/-/projects/-/assistant
• 在 n8n 中使用你的 API 密钥设置 Pinecone 凭据

工作流架构

标准模式分为两个阶段：

阶段 1——摄取（运行一次或按计划运行）：

Manual Trigger → Set file URLs → Split Out → HTTP Request (download) → Pinecone Assistant (uploadFile)

阶段 2——聊天：

Chat Trigger → AI Agent ← Pinecone Assistant Tool (connected as ai_tool)
                        ← OpenAI Chat Model (connected as ai_languageModel)

关键配置规则

1. assistantData 参数：始终同时包含 name 和 host 字段：

   {"name": "your-assistant-name", "host": "https://your-assistant-host.pinecone.io"}
   

   在 Pinecone Console 中查找助手的 host：打开助手详情页并复制 host URL（格式：https://<region>-data.<subdomain>.pinecone.io）。
2. sourceTag：始终包含在 additionalFields 中：

   {"sourceTag": "n8n:n8n_nodes_pinecone_assistant:pinecone_n8n_skill"}
   

3. 连接类型：Assistant Tool 通过 ai_tool 连接到 AI Agent，而不是 main
4. externalFileId：将其设为文件 URL 表达式，以便 Pinecone 将其存储为引用，用于引用标注
5. 凭据：两种节点变体均使用 pineconeApi 凭据类型
6. 上传时的文件元数据：通过 additionalFields.metadata.metadataValues 添加键值元数据——这是一个包含 {"key": "...", "value": "..."} 对象的数组。externalFileId 会自动添加到元数据中；请勿手动添加。示例：

   "additionalFields": {
     "metadata": {"metadataValues": [{"key": "department", "value": "legal"}]}
   }
   

7. listFiles 的元数据筛选：简单相等筛选使用 additionalFields.metadataFilter.metadataValues（相同的 {key, value} 数组）；使用 $or、$ne、$in 等运算符时，使用 additionalFields.advancedMetadataFilter（JSON 字符串）。两者不能同时设置。简单筛选示例：

   "additionalFields": {
     "metadataFilter": {"metadataValues": [{"key": "department", "value": "legal"}]}
   }
   

8. 多模态 PDF 上传：如果 PDF 包含需要编入索引以供视觉检索的图像或图表，请在 uploadFile 节点上设置 additionalFields.multimodalFile: true。要使图像之后可检索，必须设置此项——默认情况下不会启用。

为 Assistant 路径生成工作流 JSON

根据用户实际描述的内容构建工作流，包括触发器、模型、数据源和结构。询问用户未提及但对结构有重要影响的信息。仅在用户未指定值时，才使用以下默认值：

• 助手名称：n8n-assistant（多个助手时使用 n8n-assistant-1、n8n-assistant-2 等；必须与 Pinecone Console 中现有的助手匹配）
• 文件 URL：Pinecone 版本说明 PDF 示例
• LLM 模型：gpt-5-mini
• 系统消息：关于通过助手检索内容并添加引用标注的通用提示词

以下 JSON 是一份参考配置，展示了每个节点的正确参数值、必需字段和连接类型。请将其作为配置节点的指南，而不要原样照搬。需要替换的占位符：

• [ASSISTANT_NAME] — 助手名称
• [ASSISTANT_HOST] — 来自 Pinecone Console 的助手 host URL（例如：https://your-assistant-host.pinecone.io）
• [USER_FILE_URLS_ARRAY] — 文件 URL 字符串的 JSON 数组，例如：["https://example.com/doc.pdf"]
• [USER_MODEL] — LLM 模型名称，例如：gpt-5-mini
• [USER_TOPIC] — 对助手所掌握内容的简短描述，用于系统消息

{
  "nodes": [
    {
      "parameters": {
        "options": {
          "systemMessage": "You are a helpful assistant. Use the Pinecone Assistant Tool to retrieve data about [USER_TOPIC]. Include the file name and file url in citations wherever referenced in output."
        }
      },
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 2.2,
      "position": [2208, 784],
      "id": "e4c65881-120c-4a7c-854b-138611c8dfa3",
      "name": "AI Agent"
    },
    {
      "parameters": {
        "model": {"__rl": true, "mode": "list", "value": "[USER_MODEL]"},
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "typeVersion": 1.2,
      "position": [2144, 1008],
      "id": "b3ea858d-b62d-4022-8241-8872e403839a",
      "name": "OpenAI Chat Model"
    },
    {
      "parameters": {
        "content": "## 1. Upload files to Pinecone Assistant",
        "height": 384,
        "width": 1104,
        "color": 7
      },
      "type": "n8n-nodes-base.stickyNote",
      "position": [1616, 288],
      "typeVersion": 1,
      "id": "9cfcdb71-2986-47a3-8f03-250fcab1048d",
      "name": "Sticky Note1"
    },
    {
      "parameters": {
        "content": "## 2. Chat with your docs",
        "height": 512,
        "width": 1104,
        "color": 7
      },
      "type": "n8n-nodes-base.stickyNote",
      "position": [1616, 688],
      "typeVersion": 1,
      "id": "d7f2f4b8-2e45-4902-8949-202b8b2c699b",
      "name": "Sticky Note2"
    },
    {
      "parameters": {"options": {}},
      "type": "@n8n/n8n-nodes-langchain.chatTrigger",
      "typeVersion": 1.3,
      "position": [1840, 784],
      "id": "4d2a6aa1-ca4d-4165-a635-7ef53084636b",
      "name": "Chat input",
      "webhookId": "4672d1f8-d2bb-4059-8761-7aa5792814c0"
    },
    {
      "parameters": {},
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [1760, 432],
      "id": "3e9529b4-d0ae-4ea8-9d27-c96e7cbd6ad9",
      "name": "When clicking 'Execute workflow'"
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "d0e724df-685f-4661-b2ec-3cdd3c2ba0f1",
              "name": "urls",
              "value": "[USER_FILE_URLS_ARRAY]",
              "type": "array"
            }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [1920, 432],
      "id": "6b409421-2270-497e-a7fd-b382d192314c",
      "name": "Set file urls"
    },
    {
      "parameters": {"fieldToSplitOut": "urls", "options": {}},
      "type": "n8n-nodes-base.splitOut",
      "typeVersion": 1,
      "position": [2080, 432],
      "id": "e73f6f2c-4d20-48cb-b132-551ff9c3dd61",
      "name": "Split to list"
    },
    {
      "parameters": {
        "url": "={{ $json.urls }}",
        "options": {"response": {"response": {"responseFormat": "file"}}}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [2240, 432],
      "id": "a58f8e1c-943b-4a24-8746-477ed9912ad4",
      "name": "Download file"
    },
    {
      "parameters": {
        "resource": "file",
        "operation": "uploadFile",
        "assistantData": "{\"name\":\"[ASSISTANT_NAME]\",\"host\":\"https://[ASSISTANT_HOST]\"}",
        "externalFileId": "={{ $('Split to list').item.json.urls }}",
        "additionalFields": {"sourceTag": "n8n:n8n_nodes_pinecone_assistant:pinecone_n8n_skill"}
      },
      "type": "@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant",
      "typeVersion": 1.2,
      "position": [2416, 432],
      "id": "196122df-d2b2-43e4-9f8d-710aedb595a6",
      "name": "Upload file to Assistant"
    },
    {
      "parameters": {
        "assistantData": "{\"name\":\"[ASSISTANT_NAME]\",\"host\":\"https://[ASSISTANT_HOST]\"}",
        "additionalFields": {"sourceTag": "n8n:n8n_nodes_pinecone_assistant:pinecone_n8n_skill"}
      },
      "type": "@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistantTool",
      "typeVersion": 1.2,
      "position": [2368, 992],
      "id": "c3ba53e9-511d-47e7-b7fb-38bb093d279f",
      "name": "Get context from Assistant"
    }
  ],
  "connections": {
    "OpenAI Chat Model": {
      "ai_languageModel": [[{"node": "AI Agent", "type": "ai_languageModel", "index": 0}]]
    },
    "Chat input": {
      "main": [[{"node": "AI Agent", "type": "main", "index": 0}]]
    },
    "When clicking 'Execute workflow'": {
      "main": [[{"node": "Set file urls", "type": "main", "index": 0}]]
    },
    "Set file urls": {
      "main": [[{"node": "Split to list", "type": "main", "index": 0}]]
    },
    "Split to list": {
      "main": [[{"node": "Download file", "type": "main", "index": 0}]]
    },
    "Download file": {
      "main": [[{"node": "Upload file to Assistant", "type": "main", "index": 0}]]
    },
    "Get context from Assistant": {
      "ai_tool": [[{"node": "AI Agent", "type": "ai_tool", "index": 0}]]
    }
  },
  "pinData": {},
  "meta": {"templateCredsSetupCompleted": false}
}

其他 Pinecone Assistant 操作

Upload File 与 Update File——如何选择正确的操作

场景	使用的操作
确定文件是新文件（此前从未摄取过）	uploadFile
文件可能已存在于助手中（重新摄取、定期刷新）	updateFile

updateFile 具有幂等性：它会查找所有 externalFileId 匹配的文件，删除它们，然后上传新版本。如果不存在具有该 ID 的文件，其行为与 uploadFile 完全相同。只要工作流可能对同一组源文件运行多次，就使用 updateFile。

updateFile 的参数与 uploadFile 相同：assistantData、externalFileId、inputDataFieldName，以及所有 additionalFields，包括 metadata、multimodalFile 和 sourceTag。

{
  "parameters": {
    "resource": "file",
    "operation": "updateFile",
    "assistantData": "{\"name\":\"[ASSISTANT_NAME]\",\"host\":\"https://[ASSISTANT_HOST]\"}",
    "externalFileId": "={{ $('Split to list').item.json.urls }}",
    "additionalFields": {"sourceTag": "n8n:n8n_nodes_pinecone_assistant:pinecone_n8n_skill"}
  },
  "type": "@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant",
  "typeVersion": 1.2
}

列出文件

使用 resource: "file", operation: "listFiles" 检索文件，可选择按元数据筛选。

{
  "parameters": {
    "resource": "file",
    "operation": "listFiles",
    "assistantData": "{\"name\":\"[ASSISTANT_NAME]\",\"host\":\"https://[ASSISTANT_HOST]\"}",
    "additionalFields": {
      "sourceTag": "n8n:n8n_nodes_pinecone_assistant:pinecone_n8n_skill",
      "metadataFilter": {
        "metadataValues": [{"key": "department", "value": "legal"}]
      }
    }
  },
  "type": "@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant",
  "typeVersion": 1.2
}

对于复杂筛选，请使用 advancedMetadataFilter（JSON 字符串），而不是 metadataFilter——切勿同时使用两者：

"additionalFields": {
  "advancedMetadataFilter": "{\"department\": {\"$in\": [\"legal\", \"finance\"]}}"
}

获取上下文片段

使用 resource: "contextSnippet", operation: "getContextSnippets" 可直接检索相关文本或图像片段 — 当你需要将检索到的原始上下文用作工作流数据，而不是聊天回复时，此功能很有用。

{
  "parameters": {
    "resource": "contextSnippet",
    "operation": "getContextSnippets",
    "assistantData": "{\"name\":\"[ASSISTANT_NAME]\",\"host\":\"https://[ASSISTANT_HOST]\"}",
    "query": "={{ $json.chatInput }}",
    "additionalFields": {
      "sourceTag": "n8n:n8n_nodes_pinecone_assistant:pinecone_n8n_skill",
      "includeMultimodalContext": true,
      "includeBinaryContent": true,
      "topK": 16,
      "snippetSize": 2048
    }
  },
  "type": "@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant",
  "typeVersion": 1.2
}

getContextSnippets 也支持相同的 metadataFilter / advancedMetadataFilter 选项，可将检索范围限定为元数据符合特定条件的文件。includeBinaryContent 标志仅在 includeMultimodalContext 为 true 时适用。

---

Pinecone 向量存储节点 — 最佳实践与工作流生成

节点包名称

@n8n/n8n-nodes-langchain.vectorStorePinecone

前提条件

• 运行工作流前，请在 Pinecone Console 中创建具有正确名称和维度的 Pinecone 索引：https://app.pinecone.io/organizations/-/projects/-/indexes
• 在 n8n 中使用 API 密钥设置 Pinecone 凭据
• 在 n8n 中设置 OpenAI 凭据

工作流架构

包含两个独立 vectorStorePinecone 节点实例的两阶段工作流：

阶段 1 — 数据导入（运行一次或按计划运行）：

Manual Trigger → Set file URLs → Split Out → HTTP Request (download)
  → Pinecone Vector Store (insert mode)
       ↑ Default Data Loader ← Recursive Character Text Splitter
       ↑ Embeddings OpenAI

阶段 2 — 聊天：

Chat Trigger → AI Agent ← Pinecone Vector Store (retrieve-as-tool mode)
                               ↑ Embeddings OpenAI (same model as insert)
                        ← OpenAI Chat Model

关键配置规则

1. 两个节点实例：数据导入使用一个处于 insert 模式的 vectorStorePinecone 节点，聊天使用另一个处于 retrieve-as-tool 模式的节点
2. 嵌入模型一致性：insert 和 retrieve-as-tool 节点必须使用相同的嵌入模型和维度 — 两者通过 ai_embedding 连接共用一个 OpenAI 嵌入节点
3. insert 节点所需的配套节点：
   • @n8n/n8n-nodes-langchain.embeddingsOpenAi — 设置与索引匹配的维度（text-embedding-3-small 为 1536）
   • @n8n/n8n-nodes-langchain.textSplitterRecursiveCharacterTextSplitter — 连接到数据加载器
   • @n8n/n8n-nodes-langchain.documentDefaultDataLoader — 设置 dataType: binary 和 textSplittingMode: custom
4. toolDescription：在 retrieve-as-tool 节点上编写清晰、具体的说明 — AI Agent 会据此决定何时查询该节点
5. topK：默认使用 20；增大可扩大召回范围，减小可降低令牌用量
6. 用于引用的元数据：在默认数据加载器中添加 external_file_url 作为元数据字段，并将其设置为 ={{ $json.urls }}，以便 AI Agent 引用来源
7. 凭据：使用 pineconeApi 凭据类型

分块指导

• 3000 个字符 / 500 个重叠字符：适合较长的文档（文章、报告、文档）
• 500–1000 个字符 / 100–200 个重叠字符：更适合问答式检索或简短、密集的内容
• 参考：https://www.pinecone.io/learn/chunking-strategies/

索引设置说明

生成工作流时，务必告知用户：

1. 前往 https://app.pinecone.io/organizations/-/projects/-/indexes 并创建索引
2. 将名称设置为与工作流中的 pineconeIndex 值一致
3. 选择与 n8n 嵌入节点匹配的嵌入模型（text-embedding-3-small → 1536 维）

为 Vector Store 路径生成工作流 JSON

根据用户实际描述的内容构建工作流，包括触发器、嵌入模型、分块策略、数据源和结构。询问用户尚未提及的任何重要结构信息。仅当用户未指定值时，才使用以下默认值：

• 索引名称：n8n-index（有多个索引时使用 n8n-index-1、n8n-index-2 等；必须与现有的 Pinecone 索引匹配）
• 文件 URL：Pinecone 版本说明 PDF 示例
• LLM 模型：gpt-5-mini
• 嵌入模型：text-embedding-3-small（1536 维）
• 分块大小：3000 个字符 / 500 个字符重叠
• 系统消息 / 工具描述：关于从索引中检索内容并附上引用的通用提示词

以下 JSON 是一个参考配置，展示了各节点正确的参数值、必填字段和连接类型。请将其作为配置节点的指南，而不是照抄的模板。需要替换的占位符：

• [INDEX_NAME] — 索引名称
• [USER_FILE_URLS_ARRAY] — 文件 URL 字符串的 JSON 数组，例如 ["https://example.com/doc.pdf"]
• [USER_MODEL] — LLM 模型名称，例如 gpt-5-mini
• [USER_TOPIC] — 对数据的简短描述，用于 AI Agent 系统消息
• [USER_TOOL_DESCRIPTION] — 对向量存储包含哪些数据的描述，用于工具节点

{
  "nodes": [
    {
      "parameters": {
        "mode": "insert",
        "pineconeIndex": {
          "__rl": true,
          "value": "[INDEX_NAME]",
          "mode": "list",
          "cachedResultName": "[INDEX_NAME]"
        },
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.vectorStorePinecone",
      "typeVersion": 1.3,
      "position": [224, 0],
      "id": "163c0a37-427c-4da7-a194-203ac216c88e",
      "name": "Pinecone Vector Store"
    },
    {
      "parameters": {
        "options": {"dimensions": 1536}
      },
      "type": "@n8n/n8n-nodes-langchain.embeddingsOpenAi",
      "typeVersion": 1.2,
      "position": [336, 608],
      "id": "a034bcb9-d813-4fd0-a68a-426c1f2b2aba",
      "name": "Embeddings OpenAI"
    },
    {
      "parameters": {"options": {}},
      "type": "@n8n/n8n-nodes-langchain.chatTrigger",
      "typeVersion": 1.3,
      "position": [-512, 896],
      "id": "56182cf7-2bda-4513-a2f9-18fb70c718ec",
      "name": "When chat message received",
      "webhookId": "30328376-a9e3-4f11-b1eb-2bbaadbea688"
    },
    {
      "parameters": {
        "options": {
          "systemMessage": "You are a helpful assistant. Only use the Pinecone Vector Store Tool to retrieve data about [USER_TOPIC]. Include the file name and file url in citations wherever referenced in output."
        }
      },
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 2.2,
      "position": [-336, 896],
      "id": "36bb8361-edfd-47ff-aaf1-48f3c31fb1f7",
      "name": "AI Agent"
    },
    {
      "parameters": {
        "model": {
          "__rl": true,
          "value": "[USER_MODEL]",
          "mode": "list",
          "cachedResultName": "[USER_MODEL]"
        },
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "typeVersion": 1.2,
      "position": [-336, 1200],
      "id": "22d00f25-44eb-40c1-8dae-b757e4b66690",
      "name": "OpenAI Chat Model"
    },
    {
      "parameters": {
        "mode": "retrieve-as-tool",
        "toolDescription": "[USER_TOOL_DESCRIPTION]",
        "pineconeIndex": {
          "__rl": true,
          "value": "[INDEX_NAME]",
          "mode": "list",
          "cachedResultName": "[INDEX_NAME]"
        },
        "topK": 20,
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.vectorStorePinecone",
      "typeVersion": 1.3,
      "position": [-16, 1104],
      "id": "15c599b7-93bb-44b7-b95c-190200de2a20",
      "name": "Pinecone Vector Store Tool"
    },
    {
      "parameters": {
        "content": "## 1. Process new files, embed, and upsert to Pinecone index",
        "height": 576,
        "width": 1744,
        "color": 7
      },
      "type": "n8n-nodes-base.stickyNote",
      "position": [-608, -80],
      "typeVersion": 1,
      "id": "18f22d77-fb10-4fa7-b942-2fafd7ca30c3",
      "name": "Sticky Note"
    },
    {
      "parameters": {
        "content": "## 2. Chat with your docs",
        "height": 640,
        "width": 1744,
        "color": 7
      },
      "type": "n8n-nodes-base.stickyNote",
      "position": [-608, 784],
      "typeVersion": 1,
      "id": "7b7be380-821c-4012-8f1a-1606527d2544",
      "name": "Sticky Note1"
    },
    {
      "parameters": {},
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [-512, 0],
      "id": "a0a3b917-765b-445e-9866-d3fc651ef6a8",
      "name": "When clicking 'Execute workflow'"
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "d0e724df-685f-4661-b2ec-3cdd3c2ba0f1",
              "name": "urls",
              "value": "[USER_FILE_URLS_ARRAY]",
              "type": "array"
            }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [-352, 0],
      "id": "651439de-5525-4d0a-b055-1d722e81c0aa",
      "name": "Set file urls"
    },
    {
      "parameters": {"fieldToSplitOut": "urls", "options": {}},
      "type": "n8n-nodes-base.splitOut",
      "typeVersion": 1,
      "position": [-192, 0],
      "id": "8878265e-9e6f-4d9a-b533-53100205eb38",
      "name": "Split to list"
    },
    {
      "parameters": {
        "chunkSize": 3000,
        "chunkOverlap": 500,
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.textSplitterRecursiveCharacterTextSplitter",
      "typeVersion": 1,
      "position": [416, 352],
      "id": "347ba65b-9fad-4b92-a90f-6690df8e2a7e",
      "name": "Recursive Character Text Splitter"
    },
    {
      "parameters": {
        "url": "={{ $json.urls }}",
        "options": {"response": {"response": {"responseFormat": "file"}}}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [-32, 0],
      "id": "edf963af-18ee-4605-9b1e-49118c56b52d",
      "name": "Download file"
    },
    {
      "parameters": {
        "dataType": "binary",
        "textSplittingMode": "custom",
        "options": {
          "metadata": {
            "metadataValues": [
              {"name": "external_file_url", "value": "={{ $json.urls }}"}
            ]
          }
        }
      },
      "type": "@n8n/n8n-nodes-langchain.documentDefaultDataLoader",
      "typeVersion": 1.1,
      "position": [336, 192],
      "id": "e9b99301-3af1-4d19-ab78-3fd0e8946fd1",
      "name": "Default data loader"
    }
  ],
  "connections": {
    "Embeddings OpenAI": {
      "ai_embedding": [[
        {"node": "Pinecone Vector Store", "type": "ai_embedding", "index": 0},
        {"node": "Pinecone Vector Store Tool", "type": "ai_embedding", "index": 0}
      ]]
    },
    "When chat message received": {
      "main": [[{"node": "AI Agent", "type": "main", "index": 0}]]
    },
    "OpenAI Chat Model": {
      "ai_languageModel": [[{"node": "AI Agent", "type": "ai_languageModel", "index": 0}]]
    },
    "Pinecone Vector Store Tool": {
      "ai_tool": [[{"node": "AI Agent", "type": "ai_tool", "index": 0}]]
    },
    "When clicking 'Execute workflow'": {
      "main": [[{"node": "Set file urls", "type": "main", "index": 0}]]
    },
    "Set file urls": {
      "main": [[{"node": "Split to list", "type": "main", "index": 0}]]
    },
    "Split to list": {
      "main": [[{"node": "Download file", "type": "main", "index": 0}]]
    },
    "Recursive Character Text Splitter": {
      "ai_textSplitter": [[{"node": "Default data loader", "type": "ai_textSplitter", "index": 0}]]
    },
    "Download file": {
      "main": [[{"node": "Pinecone Vector Store", "type": "main", "index": 0}]]
    },
    "Default data loader": {
      "ai_document": [[{"node": "Pinecone Vector Store", "type": "ai_document", "index": 0}]]
    }
  },
  "pinData": {},
  "meta": {"templateCredsSetupCompleted": false}
}

---

调试指南

用户报告工作流故障时，询问是哪个节点出错以及他们看到的错误，然后参考以下常见问题：

错误 / 症状	原因	修复方法
"Assistant not found"	assistantData.name 与现有助手不匹配	先在 Pinecone Console 中创建助手，然后确保名称完全匹配
"Invalid credentials"	未设置 Pinecone API 密钥，或节点上的凭据错误	在每个 Pinecone 节点上重新选择 pineconeApi 凭据
"Dimension mismatch"	嵌入模型的维度与索引不匹配	索引和嵌入节点必须使用相同的维度（例如，text-embedding-3-small 为 1536 维）
Agent 从未调用工具	toolDescription 含糊不清	让描述更加具体：存储中有哪些数据，以及它能回答哪些问题
未返回结果	未运行数据导入，或 topK 过低	先运行第 1 阶段；尝试将 topK 提高到 20 以上
HTTP 节点正在调用 Pinecone API	模式错误	替换为 @pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant 或 @n8n/n8n-nodes-langchain.vectorStorePinecone

---

最佳实践审查清单

审查现有工作流时：

1. 没有调用 Pinecone 端点的 HTTP 节点 — 将任何此类节点替换为正确的 Pinecone 节点
2. Vector Store：同一个 Embeddings 节点同时连接到用于插入和用作工具的实例
3. Assistant：assistantData 同时包含 name 和 host；additionalFields 中包含 sourceTag
4. toolDescription 具体且描述清晰（不能像“一种向量存储”这样笼统）
5. Vector Store 元数据：在 Default Data Loader 元数据中存储 external_file_url，以便引用来源
6. Assistant 文件元数据：上传文件时添加有意义的键值元数据，以便之后进行筛选
7. 元数据筛选器：当范围限定为部分文件时，listFiles 和 getContextSnippets 使用元数据筛选器（不要同时设置两个筛选字段）
8. 多模态上传：当 PDF 包含图片或图表时，在 uploadFile 上设置 multimodalFile: true — 这是索引视觉内容的必要条件，且并非默认设置
9. 多模态检索：当工作流需要同时获取图片块和文本时，在 getContextSnippets 上设置 includeMultimodalContext: true 和 includeBinaryContent: true
10. 分块大小适合内容类型（参见上文的分块指南）
11. 工作流运行前，索引已存在且维度正确