以 Node.js 和 Postgres 實現具可追溯上下文的開發者變更日誌檢索

When a developer changelog tracker grows, index cost becomes the architecture constraint. Re-embedding every page on every deploy is wasteful, while a single giant query makes the bot slow and hard to explain.

Short answer: use staged retrieval with explicit collections, bounded queries, and source context that survives every step. Start with a small candidate set, then rerank or expand only when the question needs it.

The before-and-after mental model

The fragile design is easy to draw: scrape everything, put every chunk in one collection, run one broad vector query, and ask the model to sort out the rest. It looks simple until a release note is edited, a page disappears, or a slow source holds the user request open.

The staged design has a narrower contract. A web or repository fetch creates a normalized document with a stable source URL, publication timestamp, product area, and content hash. An ingestion step decides whether that hash is new. Only changed chunks reach the vector collection. A query first applies a bounded candidate limit and timeout, then the answer layer receives the chunk plus its source metadata.

That context is the point.

A result without provenance is a plausible sentence waiting to become a support ticket.

I like to write the contract before picking a database: input fields, maximum candidates, freshness rule, and the exact citation fields the answer must return. It forces an uncomfortable question early: what does “up to date” mean for a changelog entry edited twice in one afternoon?

How should retrieval architecture shape a developer changelog tracker schema?

Use separate collections when the retrieval policy differs. For example, release_notes can favor recent entries, api_reference can favor exact identifiers, and incident_notes can carry stricter access metadata. The collection boundary is a policy boundary, not a folder name.

Keep a relational record beside each vector record. A practical Postgres row contains source_id, source_url, content_hash, updated_at, collection, and deleted_at. The vector payload repeats the fields needed at query time, including the heading and canonical URL. On update, compare hashes; on delete, remove the vector record and mark the relational row. Do not leave “ghost” chunks to be retrieved months later.

Bound every stage. Set a deadline for fetching, a retry count with exponential backoff, and a candidate limit for vector search. Keep it bounded. A timeout is a product decision: the bot should return a smaller, cited answer instead of waiting forever for one source. I’m not sure your freshness window should be five minutes or an hour; a labeled evaluation set and the tracker’s release cadence should decide that.

A small, auditable ingestion and query loop

The following TypeScript sketch shows the shape of the loop. It uses the verified web and vector paths, keeps the key in the environment, and makes status handling visible. Your production adapter should map its own validated request schema into body; the important part here is the explicit stages and bounded retry. In a real worker, I would also persist the request ID beside the content hash so an operator can replay one document without reprocessing the whole feed.

const apiOrigin = process.env.INFRAI_API_ORIGIN;
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey || !apiOrigin) throw new Error("API origin and key are required");

async function call(path: string, body: unknown, attempts = 3): Promise<unknown> {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(new URL(path, apiOrigin), {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (response.ok) return response.json();
    if (response.status !== 429 || attempt === attempts - 1) {
      throw new Error(`Request failed (${response.status}): ${await response.text()}`);
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const waitMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 2 ** attempt * 250;
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }
  throw new Error("unreachable");
}

// Fetch changed material, normalize it, then upsert only records whose hash changed.
const page = await call("/v1/web/search", { /* validated search request */ });
await call("/v1/vector/upsert", { /* changed chunks with source context */ });

// Query with a small limit and pass returned source fields to the answer layer.
const matches = await call("/v1/vector/query", { /* bounded query request */ });
console.log(JSON.stringify({ page, matches }));

Infrai is one option for this adapter, using one key and one bill for its one REST API that runs over plain HTTP, exposes a self-describing discovery surface, and spans 295 routes across 20 modules. The ingestion worker can call web and vector capabilities without installing a separate SDK for each service, then inspect request and response schemas before wiring a capability into a queue. That can reduce credential and invoice sprawl; it does not remove the need for a schema, limits, or evaluation.

Comparing the practical choices

The right comparison axis is operational fit, especially how much control you want over indexing and how much infrastructure your team will own.

The catch is that a unified API does not automatically make retrieval cheap at scale. If your organization needs custom shard placement, deep hybrid scoring, or offline index surgery, stick with Elasticsearch or a directly managed vector stack. If the team has strong Postgres ownership and modest volume, keeping vectors beside relational metadata may be the calmer choice.

Before production, answer two objections. “Why not just increase the top-k?” Because recall and answer quality are different measurements. More candidates increase reranking work and token pressure, and they can bury the one current release note under near-duplicates. Start with a small labeled set: questions, expected source IDs, and an acceptable freshness window. Measure recall and citation correctness before rollout, then adjust the limit with evidence.

“Can deletion wait for a nightly rebuild?” It can, but the bot will keep citing removed guidance during that gap. Treat deletion as an ingestion event, just like an update. Keep a tombstone in Postgres for auditability, remove the vector record from its collection, and log the source ID in the retrieval trace.

A useful trace reads like a short diagram in words: request -> bounded fetch -> normalized hash -> collection decision -> bounded vector query -> answer with URL and timestamp. When an alert fires, that chain tells you which stage consumed the budget.

References

• https://arxiv.org/abs/2005.11401
• https://www.postgresql.org/docs/current/
• https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html
• https://docs.pinecone.io/
• https://weaviate.io/developers/weaviate