Bases de conocimiento

¿Qué opción debo elegir?

• Local knowledge base: best for PDF, Word, Markdown, files, and web pages that should be indexed on this machine without an extra service.
• External knowledge base: best when you already have an HTTP search API, Dify / FastGPT, enterprise search, or a read-only MCP query tool.
• External connections are read-only: HiRocky stores configuration and reads search results during Q&A. It does not write to or modify remote content.
• You can use both together. Keep their responsibilities clear, such as product manuals locally and tickets or CRM in an external source.

Base de conocimiento local

Create and manage local libraries on the Knowledge page. Files and indexes stay on this machine.

1. Create a library

   Click New, then enter a name and description such as Product docs or Personal notes, so the library is easy to recognize when binding it to an agent.

2. Import content

   Supports TXT, Markdown, PDF, Word, PPT, Excel, RTF, and web import. HiRocky extracts text and builds a local search index after import.

3. Back up and export

   Export a library from the Knowledge page when you need backup or migration. Local libraries are suitable for stable documents that you want to manage offline.

Añadir una base de conocimiento externa en HiRocky

1. Create the connection

   Open Knowledge → External knowledge → Add external knowledge. Enter a name and description, choose HTTP search or MCP Tool, then save.

2. Configure HTTP, if selected

   Enter the full endpoint URL, adapter type, result limit, and timeout in seconds. Optional fields include API Key, Headers JSON, and Filters JSON. Save, then click Test to verify sample results.

3. Configure MCP, if selected

   First add the MCP server in Settings → MCP, test the connection, refresh tools, and enable the target tool. Then return to External knowledge, choose MCP Tool, and select that server/tool.

Conceptos básicos de HTTP

All HTTP external knowledge bases use POST with Content-Type: application/json. The endpoint must return JSON with a 2xx HTTP status. HiRocky parses a result array and text fields from each item.

Authentication: when API Key is filled, HiRocky adds Authorization: Bearer <API_KEY>. If your endpoint needs other headers, put them in Headers JSON:

{
  "X-API-Key": "your-api-key",
  "X-Workspace-ID": "workspace_001"
}

If both API Key and Headers JSON are filled, HiRocky sends both the Bearer token and the custom headers.

API de búsqueda estándar

When you select Standard search, HiRocky sends this JSON request body to your URL:

{
  "query": "user question",
  "limit": 6,
  "filters": {}
}

Recommended response: return a results array. Include full metadata so HiRocky can keep source, URL, and score information.

{
  "results": [
    {
      "id": "chunk_001",
      "title": "Refund policy",
      "content": "Users can request a refund within 7 days after payment.",
      "source": "Support handbook",
      "url": "https://example.com/docs/refund",
      "score": 0.91,
      "metadata": {
        "section": "billing"
      }
    }
  ]
}

A raw JSON array is also supported, without the results wrapper. Each item must still contain readable content.

[
  {
    "title": "Refund policy",
    "content": "Users can request a refund within 7 days after payment."
  }
]

Adaptador Dify

When you select Dify adapter, HiRocky adds top_k to the standard fields:

{
  "query": "user question",
  "limit": 6,
  "top_k": 6,
  "filters": {}
}

HiRocky looks for result arrays in this order: records → documents → data.records → data.documents → data → results. Example:

{
  "data": {
    "records": [
      {
        "id": "dify_001",
        "segment": {
          "content": "SLA uptime is 99.9%."
        },
        "document": {
          "name": "SLA.md",
          "url": "https://example.com/sla"
        },
        "metadata": {
          "score": 0.73
        }
      }
    ]
  }
}

Content is usually read from segment.content; titles can be read from document.name. If no result array is found, the test shows: Knowledge source response must include a result array.

Adaptador FastGPT

When you select FastGPT adapter, HiRocky sends topK, with this exact casing:

{
  "query": "user question",
  "limit": 6,
  "topK": 6,
  "filters": {}
}

HiRocky looks for result arrays in this order: data.list → data.records → data → results → list. Example:

{
  "data": {
    "list": [
      {
        "id": "fg_001",
        "q": "How do I reset my password?",
        "a": "Open Settings and click Send reset email.",
        "sourceName": "FAQ",
        "similarity": 0.82
      }
    ]
  }
}

If an item has no content but has both q and a, HiRocky combines them as: Q: How do I reset my password? A: Open Settings and click Send reset email.

Mapeo de campos de respuesta HTTP

All three adapters share the same field mapping. Each result item must provide a parseable content field, otherwise that item is ignored.

Ejemplo HTTP personalizado mínimo

This minimal Node.js + Express service accepts the standard request and returns results:

import express from "express";

const app = express();
app.use(express.json());

app.post("/v1/knowledge/search", async (req, res) => {
  const { query, limit = 6, filters = {} } = req.body;

  const results = [
    {
      id: "doc_001_chunk_001",
      title: "Sample knowledge",
      content: `This is sample content related to "${query}".`,
      source: "internal-handbook",
      url: "https://example.com/handbook/doc_001",
      score: 0.88,
      metadata: { filters }
    }
  ].slice(0, limit);

  res.json({ results });
});

app.listen(3000, () => {
  console.log("Knowledge API listening on http://localhost:3000");
});

Integración MCP Tool

MCP is suitable for internal read-only system queries, database reads, document services, or enterprise APIs exposed by an MCP server. Access scope is controlled by the MCP server; prefer read-only permissions.

1. Enable MCP in Settings

   Open Settings → MCP → add or enable an MCP server → test the connection → refresh tools → confirm the target tool is enabled.

2. Create the external knowledge connection

   Go to Knowledge → External knowledge → Add external knowledge → choose MCP Tool → select the synced server/tool → save.

3. Bind to an agent

   Enable knowledge on the agent and select this connection. MCP external knowledge is tool-only: it does not POST on every message like HTTP, but is available to the agent when a knowledge query or MCP intent is detected.

Vinculación con agentes y parámetros recomendados

• For focused business agents, bind only the knowledge sources needed by that scenario to reduce irrelevant retrieval noise.
• If local and external knowledge overlap, define clear roles, such as local product manuals and external ticket or CRM knowledge.
• HTTP external knowledge: choose Auto retrieve so HiRocky automatically requests your endpoint during chat.
• MCP external knowledge: keep tool-call mode and let the conversation flow trigger it by intent.
• Result limit: start with 4-6. Increase for short chunks and decrease for long chunks to avoid filling the context.
• Timeout: start with 3-8 seconds. Slow enterprise networks can use more, but keep it no higher than 30 seconds.

Seguridad y límites de datos

• External knowledge is read-only; HiRocky does not write remote knowledge content.
• Connection settings such as URL, Headers, Filters, retrieval mode, result limit, and timeout are stored locally.
• API Key is removed from the normal config JSON, written to knowledge_source_secrets, and encrypted with the local app key.
• Headers JSON is stored as local configuration. Do not put highly sensitive secrets there unless this storage model is acceptable.
• When HTTP Auto retrieve is enabled, user questions are sent to enabled and bound external endpoints. Do not enable it if this violates your compliance requirements.
• MCP tool permissions and data access are controlled by the corresponding MCP server; prefer read-only access.

Vincular a un agente

Local and external knowledge bases only take effect after they are explicitly selected on an agent.

1. Enable and select knowledge sources

   Open the agent settings, enable knowledge, and select the local libraries or external connections to use. For fixed business scenarios, bind only the sources required for that scenario.

2. Verify in chat

   Ask a question after binding. HiRocky retrieves relevant chunks and includes them in context. Expert view shows retrieval steps, tool calls, and failure reasons.

FAQ y solución de problemas

Connection test fails

• Make sure the endpoint is reachable from the machine running HiRocky, including localhost or internal IP considerations.
• The endpoint must accept POST with Content-Type: application/json.
• Check whether API Key and Headers JSON match your service authentication method.
• Ensure the endpoint returns within the configured timeout and uses a 2xx HTTP status.

Test succeeds but no sample appears

• The JSON response must include a parseable result array.
• Standard adapter: prefer a results array.
• Dify adapter: prefer data.records or records.
• FastGPT adapter: prefer data.list or list.
• Each item must include content, text, segment.content, chunk.content, answer, or both q and a.

Agent answers without using external knowledge

• The external connection must be enabled, and the agent must have knowledge enabled and this source selected.
• HTTP: retrieval mode must be Auto retrieve.
• MCP: the target tool must be enabled in Settings, and the question should express a clear query intent.
• Open expert view to check whether external knowledge retrieval ran and whether any error occurred.

• Local import issues: try TXT / Markdown, or check whether the file is corrupted.
• Bind only the knowledge sources needed by the scenario to reduce noise.
• If local and external sources overlap, define clear roles for each source.