Plugin de AI Search

Consulta índices de Databricks Vector Search con búsqueda híbrida, reranking y paginación por cursor desde tu aplicación AppKit.

Funcionalidades principales:

• Alias con nombre para múltiples índices de Vector Search
• Modos de query híbrido, ANN y de texto completo
• Reranking opcional con control a nivel de columna
• Paginación basada en cursor para grandes conjuntos de resultados
• Autenticación mediante service principal (predeterminada) y on-behalf-of-user
• Índices con embeddings autogestionados mediante una embeddingFn personalizada

Uso básico

import { createApp, server } from "@databricks/appkit";
import { aiSearch } from "@databricks/appkit/beta";

await createApp({
  plugins: [
    server(),
    aiSearch({
      indexes: {
        products: {
          indexName: "catalog.schema.products_idx",
          columns: ["id", "name", "description"],
          queryType: "hybrid",
          numResults: 20,
        },
      },
    }),
  ],
});

Opciones de configuración

Alias de índice

Los alias de índice te permiten hacer referencia por nombre a varios índices de Vector Search. El alias se usa en las rutas de la API y en las llamadas programáticas:

aiSearch({
  indexes: {
    products: {
      indexName: "catalog.schema.products_idx",
      columns: ["id", "name", "description"],
    },
    docs: {
      indexName: "catalog.schema.docs_idx",
      columns: ["id", "title", "content", "url"],
      queryType: "full_text",
    },
  },
});

IndexConfig

Tipos de query

• hybrid — Combina similitud vectorial y búsqueda por palabras clave. Ideal para recuperación de propósito general.
• ann — Búsqueda de vecinos más cercanos aproximados usando únicamente embeddings. Ideal para similitud semántica.
• full_text — Búsqueda basada en palabras clave, sin necesidad de embeddings.

Reranking

El reranking mejora la relevancia de los resultados al ejecutar un modelo de segunda etapa sobre los candidatos iniciales:

aiSearch({
  indexes: {
    products: {
      indexName: "catalog.schema.products_idx",
      columns: ["id", "name", "description", "category"],
      reranker: { columnsToRerank: ["name", "description"] },
    },
  },
});

Pasa reranker: true para reordenar los resultados en función de todas las columnas devueltas.

Autenticación on-behalf-of-user

De forma predeterminada, las queries se ejecutan con el service principal de la app. Define auth: "on-behalf-of-user" para ejecutarlas con la identidad del usuario que inició sesión:

aiSearch({
  indexes: {
    documents: {
      indexName: "catalog.schema.documents_idx",
      columns: ["id", "title", "body"],
      auth: "on-behalf-of-user",
    },
  },
});

Paginación

Habilita la paginación por cursor para recorrer grandes conjuntos de resultados:

aiSearch({
  indexes: {
    products: {
      indexName: "catalog.schema.products_idx",
      columns: ["id", "name", "description"],
      pagination: true,
      endpointName: "my-vector-search-endpoint",
    },
  },
});

endpointName es obligatorio cuando pagination es true. Usa la ruta /:alias/next-page para obtener las páginas siguientes.

Índices con embeddings autogestionados

Para los índices que gestionan sus propios embeddings, proporciona una función embeddingFn que reciba una cadena de query y devuelva un vector:

import { embed } from "./my-embedding-client";

aiSearch({
  indexes: {
    products: {
      indexName: "catalog.schema.products_idx",
      columns: ["id", "name", "description"],
      queryType: "ann",
      embeddingFn: (text) => embed(text),
    },
  },
});

Rutas HTTP

Las rutas se montan en /api/ai-search.

Hacer un query a un índice

Respuesta:

{
  "results": [
    {
      "score": 0.87,
      "data": { "id": "42", "name": "Intro to ML", "description": "..." }
    }
  ],
  "totalCount": 1,
  "queryTimeMs": 35,
  "queryType": "hybrid",
  "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
}

Cada resultado incluye su score de relevancia y las columnas devueltas en data. nextPageToken es null salvo que pagination esté habilitado y haya más resultados disponibles.

Obtener la siguiente página

Obtener la configuración del índice

Devuelve el IndexConfig resuelto para el alias (sin incluir embeddingFn).

Acceso programático

El plugin expone un método query para uso en el servidor:

import { createApp, server } from "@databricks/appkit";
import { aiSearch } from "@databricks/appkit/beta";

const AppKit = await createApp({
  plugins: [
    server(),
    aiSearch({
      indexes: {
        products: {
          indexName: "catalog.schema.products_idx",
          columns: ["id", "name", "description"],
        },
      },
    }),
  ],
});

const result = await AppKit.aiSearch.query("products", {
  queryText: "machine learning guide",
});

console.log(result.results);

Pasa valores de sobrescritura opcionales como segundo argumento a query para ajustar numResults u otras opciones por llamada.

Almacenamiento en caché

Los resultados de las queries se almacenan en caché con un TTL corto (60 s), de modo que las queries idénticas repetidas —incluido un componente que se vuelve a renderizar o se monta dos veces— reutilizan una única llamada a Vector Search en lugar de acceder al índice cada vez. La ruta de la página siguiente no se almacena en caché: un token de página es un cursor de un solo uso y ya identifica la página exacta.

La clave de caché abarca todo lo que altera los resultados: el índice resuelto, queryText, queryVector (con hash), queryType, numResults, las columns resueltas, los filters y si el reranking está activado. Dos queries que difieran en cualquiera de estos elementos se almacenan en caché por separado.

Aislamiento por usuario

En los índices con auth: "on-behalf-of-user", la identidad de quien realiza la llamada forma parte de la clave de caché, por lo que ningún usuario ve los resultados en caché de otro usuario, y una query on-behalf-of-user nunca lee una entrada generada por un service principal. Los índices de service principal comparten una única entrada de caché entre todas las llamadas.

React hook

useAiSearchQuery lee los índices configurados en la configuración de cliente del plugin y envía la petición a la ruta /:alias/query correspondiente, de modo que la UI nunca codifica un alias de forma fija. Con un solo índice configurado no necesita argumentos; pasa { alias } para apuntar a uno concreto.

import { useAiSearchQuery } from "@databricks/appkit-ui/react/beta";

function Search() {
  const { search, data, loading, error } = useAiSearchQuery();

  return (
    <>
      <input onKeyDown={(e) => e.key === "Enter" && search(e.currentTarget.value)} />
      {error && <p>{error}</p>}
      {data?.results.map((r, i) => (
        <div key={i}>{JSON.stringify(r.data)}</div>
      ))}
    </>
  );
}

search también acepta un objeto de solicitud completo ({ queryText, numResults, filters, ... }) para controlar cada llamada de forma individual. El campo indexes del hook enumera todos los índices configurados, que puedes usar para crear un selector de índices.