@fairyhunter13/ai-sdk 6.0.116-fork.1

package/docs/07-reference/01-ai-sdk-core/05-embed.mdx

@@ -0,0 +1,332 @@
+---
+title: embed
+description: API Reference for embed.
+---
+
+# `embed()`
+
+Generate an embedding for a single value using an embedding model.
+
+This is ideal for use cases where you need to embed a single value to e.g. retrieve similar items or to use the embedding in a downstream task.
+
+```ts
+import { embed } from 'ai';
+
+const { embedding } = await embed({
+  model: 'openai/text-embedding-3-small',
+  value: 'sunny day at the beach',
+});
+```
+
+## Import
+
+<Snippet text={`import { embed } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'model',
+      type: 'EmbeddingModel',
+      description:
+        "The embedding model to use. Example: openai.embeddingModel('text-embedding-3-small')",
+    },
+    {
+      name: 'value',
+      type: 'VALUE',
+      description: 'The value to embed. The type depends on the model.',
+    },
+    {
+      name: 'maxRetries',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of retries. Set to 0 to disable retries. Default: 2.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description:
+        'An optional abort signal that can be used to cancel the call.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string>',
+      isOptional: true,
+      description:
+        'Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description:
+        'Provider-specific options that are passed through to the provider.',
+    },
+    {
+      name: 'experimental_telemetry',
+      type: 'TelemetrySettings',
+      isOptional: true,
+      description: 'Telemetry configuration. Experimental feature.',
+      properties: [
+        {
+          type: 'TelemetrySettings',
+          parameters: [
+            {
+              name: 'isEnabled',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable telemetry. Disabled by default while experimental.',
+            },
+            {
+              name: 'recordInputs',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable input recording. Enabled by default.',
+            },
+            {
+              name: 'recordOutputs',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable output recording. Enabled by default.',
+            },
+            {
+              name: 'functionId',
+              type: 'string',
+              isOptional: true,
+              description:
+                'Identifier for this function. Used to group telemetry data by function.',
+            },
+            {
+              name: 'metadata',
+              isOptional: true,
+              type: 'Record<string, string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>>',
+              description:
+                'Additional information to include in the telemetry data.',
+            },
+            {
+              name: 'tracer',
+              type: 'Tracer',
+              isOptional: true,
+              description: 'A custom tracer to use for the telemetry data.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'experimental_onStart',
+      type: '(event: EmbedOnStartEvent) => PromiseLike<void> | void',
+      isOptional: true,
+      description:
+        'Callback that is called when the embed operation begins, before the embedding model is called. Errors thrown in this callback are silently caught and do not break the embedding flow. Experimental (can break in patch releases).',
+      properties: [
+        {
+          type: 'EmbedOnStartEvent',
+          parameters: [
+            {
+              name: 'callId',
+              type: 'string',
+              description: 'Unique identifier for this embed call.',
+            },
+            {
+              name: 'operationId',
+              type: 'string',
+              description: "Identifies the operation type ('ai.embed').",
+            },
+            {
+              name: 'model',
+              type: '{ provider: string; modelId: string }',
+              description: 'The embedding model being used.',
+            },
+            {
+              name: 'value',
+              type: 'string | Array<string>',
+              description: 'The value being embedded.',
+            },
+            {
+              name: 'maxRetries',
+              type: 'number',
+              description: 'Maximum number of retries for failed requests.',
+            },
+            {
+              name: 'abortSignal',
+              type: 'AbortSignal | undefined',
+              description: 'Abort signal for cancelling the operation.',
+            },
+            {
+              name: 'headers',
+              type: 'Record<string, string | undefined> | undefined',
+              description: 'Additional HTTP headers sent with the request.',
+            },
+            {
+              name: 'providerOptions',
+              type: 'ProviderOptions | undefined',
+              description: 'Additional provider-specific options.',
+            },
+            {
+              name: 'functionId',
+              type: 'string | undefined',
+              description:
+                'Identifier from telemetry settings for grouping related operations.',
+            },
+            {
+              name: 'metadata',
+              type: 'Record<string, JSONValue> | undefined',
+              description: 'Additional metadata from telemetry settings.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'experimental_onFinish',
+      type: '(event: EmbedOnFinishEvent) => PromiseLike<void> | void',
+      isOptional: true,
+      description:
+        'Callback that is called when the embed operation completes, after the embedding model returns. Errors thrown in this callback are silently caught and do not break the embedding flow. Experimental (can break in patch releases).',
+      properties: [
+        {
+          type: 'EmbedOnFinishEvent',
+          parameters: [
+            {
+              name: 'callId',
+              type: 'string',
+              description: 'Unique identifier for this embed call.',
+            },
+            {
+              name: 'operationId',
+              type: 'string',
+              description: "Identifies the operation type ('ai.embed').",
+            },
+            {
+              name: 'model',
+              type: '{ provider: string; modelId: string }',
+              description: 'The embedding model that was used.',
+            },
+            {
+              name: 'value',
+              type: 'string | Array<string>',
+              description: 'The value that was embedded.',
+            },
+            {
+              name: 'embedding',
+              type: 'Embedding | Array<Embedding>',
+              description: 'The resulting embedding vector.',
+            },
+            {
+              name: 'usage',
+              type: 'EmbeddingModelUsage',
+              description: 'Token usage for the embedding operation.',
+            },
+            {
+              name: 'warnings',
+              type: 'Array<Warning>',
+              description: 'Warnings from the embedding model.',
+            },
+            {
+              name: 'providerMetadata',
+              type: 'ProviderMetadata | undefined',
+              description: 'Optional provider-specific metadata.',
+            },
+            {
+              name: 'response',
+              type: '{ headers?: Record<string, string>; body?: unknown } | undefined',
+              description: 'Optional response data including headers and body.',
+            },
+            {
+              name: 'functionId',
+              type: 'string | undefined',
+              description:
+                'Identifier from telemetry settings for grouping related operations.',
+            },
+            {
+              name: 'metadata',
+              type: 'Record<string, JSONValue> | undefined',
+              description: 'Additional metadata from telemetry settings.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'value',
+      type: 'VALUE',
+      description: 'The value that was embedded.',
+    },
+    {
+      name: 'embedding',
+      type: 'number[]',
+      description: 'The embedding of the value.',
+    },
+    {
+      name: 'usage',
+      type: 'EmbeddingModelUsage',
+      description: 'The token usage for generating the embeddings.',
+      properties: [
+        {
+          type: 'EmbeddingModelUsage',
+          parameters: [
+            {
+              name: 'tokens',
+              type: 'number',
+              description: 'The number of tokens used in the embedding.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'warnings',
+      type: 'Warning[]',
+      description:
+        'Warnings from the model provider (e.g. unsupported settings).',
+    },
+    {
+      name: 'response',
+      type: 'Response',
+      isOptional: true,
+      description: 'Optional response data.',
+      properties: [
+        {
+          type: 'Response',
+          parameters: [
+            {
+              name: 'headers',
+              isOptional: true,
+              type: 'Record<string, string>',
+              description: 'Response headers.',
+            },
+            {
+              name: 'body',
+              type: 'unknown',
+              isOptional: true,
+              description: 'The response body.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'providerMetadata',
+      type: 'ProviderMetadata | undefined',
+      isOptional: true,
+      description:
+        'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
+    },
+  ]}
+/>

package/docs/07-reference/01-ai-sdk-core/06-embed-many.mdx

@@ -0,0 +1,330 @@
+---
+title: embedMany
+description: API Reference for embedMany.
+---
+
+# `embedMany()`
+
+Embed several values using an embedding model.
+
+`embedMany` automatically splits large requests into smaller chunks if the model
+has a limit on how many embeddings can be generated in a single call.
+
+```ts
+import { embedMany } from 'ai';
+
+const { embeddings } = await embedMany({
+  model: 'openai/text-embedding-3-small',
+  values: [
+    'sunny day at the beach',
+    'rainy afternoon in the city',
+    'snowy night in the mountains',
+  ],
+});
+```
+
+## Import
+
+<Snippet text={`import { embedMany } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'model',
+      type: 'EmbeddingModel',
+      description:
+        "The embedding model to use. Example: openai.embeddingModel('text-embedding-3-small')",
+    },
+    {
+      name: 'values',
+      type: 'Array<string>',
+      description: 'The values to embed.',
+    },
+    {
+      name: 'maxRetries',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of retries. Set to 0 to disable retries. Default: 2.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description:
+        'An optional abort signal that can be used to cancel the call.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string>',
+      isOptional: true,
+      description:
+        'Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description:
+        'Provider-specific options that are passed through to the provider.',
+    },
+    {
+      name: 'maxParallelCalls',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of concurrent requests to the provider. Default: Infinity.',
+    },
+    {
+      name: 'experimental_telemetry',
+      type: 'TelemetrySettings',
+      isOptional: true,
+      description: 'Telemetry configuration. Experimental feature.',
+      properties: [
+        {
+          type: 'TelemetrySettings',
+          parameters: [
+            {
+              name: 'isEnabled',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable telemetry. Disabled by default while experimental.',
+            },
+            {
+              name: 'recordInputs',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable input recording. Enabled by default.',
+            },
+            {
+              name: 'recordOutputs',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable output recording. Enabled by default.',
+            },
+            {
+              name: 'functionId',
+              type: 'string',
+              isOptional: true,
+              description:
+                'Identifier for this function. Used to group telemetry data by function.',
+            },
+            {
+              name: 'metadata',
+              isOptional: true,
+              type: 'Record<string, string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>>',
+              description:
+                'Additional information to include in the telemetry data.',
+            },
+            {
+              name: 'tracer',
+              type: 'Tracer',
+              isOptional: true,
+              description: 'A custom tracer to use for the telemetry data.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'experimental_onStart',
+      type: '(event: EmbedOnStartEvent) => PromiseLike<void> | void',
+      isOptional: true,
+      description:
+        'Callback that is called when the embedMany operation begins, before the embedding model is called. Errors thrown in this callback are silently caught and do not break the embedding flow. Experimental (can break in patch releases).',
+      properties: [
+        {
+          type: 'EmbedOnStartEvent',
+          parameters: [
+            {
+              name: 'callId',
+              type: 'string',
+              description: 'Unique identifier for this embedMany call.',
+            },
+            {
+              name: 'operationId',
+              type: 'string',
+              description: "Identifies the operation type ('ai.embedMany').",
+            },
+            {
+              name: 'model',
+              type: '{ provider: string; modelId: string }',
+              description: 'The embedding model being used.',
+            },
+            {
+              name: 'value',
+              type: 'string | Array<string>',
+              description:
+                'The values being embedded (array of strings for embedMany).',
+            },
+            {
+              name: 'maxRetries',
+              type: 'number',
+              description: 'Maximum number of retries for failed requests.',
+            },
+            {
+              name: 'abortSignal',
+              type: 'AbortSignal | undefined',
+              description: 'Abort signal for cancelling the operation.',
+            },
+            {
+              name: 'headers',
+              type: 'Record<string, string | undefined> | undefined',
+              description: 'Additional HTTP headers sent with the request.',
+            },
+            {
+              name: 'providerOptions',
+              type: 'ProviderOptions | undefined',
+              description: 'Additional provider-specific options.',
+            },
+            {
+              name: 'functionId',
+              type: 'string | undefined',
+              description:
+                'Identifier from telemetry settings for grouping related operations.',
+            },
+            {
+              name: 'metadata',
+              type: 'Record<string, JSONValue> | undefined',
+              description: 'Additional metadata from telemetry settings.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'experimental_onFinish',
+      type: '(event: EmbedOnFinishEvent) => PromiseLike<void> | void',
+      isOptional: true,
+      description:
+        'Callback that is called when the embedMany operation completes, after all embedding model calls return. Errors thrown in this callback are silently caught and do not break the embedding flow. Experimental (can break in patch releases).',
+      properties: [
+        {
+          type: 'EmbedOnFinishEvent',
+          parameters: [
+            {
+              name: 'callId',
+              type: 'string',
+              description: 'Unique identifier for this embedMany call.',
+            },
+            {
+              name: 'operationId',
+              type: 'string',
+              description: "Identifies the operation type ('ai.embedMany').",
+            },
+            {
+              name: 'model',
+              type: '{ provider: string; modelId: string }',
+              description: 'The embedding model that was used.',
+            },
+            {
+              name: 'value',
+              type: 'string | Array<string>',
+              description:
+                'The values that were embedded (array of strings for embedMany).',
+            },
+            {
+              name: 'embedding',
+              type: 'Embedding | Array<Embedding>',
+              description:
+                'The resulting embedding vectors (array of embeddings for embedMany).',
+            },
+            {
+              name: 'usage',
+              type: 'EmbeddingModelUsage',
+              description: 'Token usage for the embedding operation.',
+            },
+            {
+              name: 'warnings',
+              type: 'Array<Warning>',
+              description: 'Warnings from the embedding model.',
+            },
+            {
+              name: 'providerMetadata',
+              type: 'ProviderMetadata | undefined',
+              description: 'Optional provider-specific metadata.',
+            },
+            {
+              name: 'response',
+              type: 'Array<{ headers?: Record<string, string>; body?: unknown } | undefined>',
+              description:
+                'Response data from each embedding call. There may be multiple responses if the request was split into chunks.',
+            },
+            {
+              name: 'functionId',
+              type: 'string | undefined',
+              description:
+                'Identifier from telemetry settings for grouping related operations.',
+            },
+            {
+              name: 'metadata',
+              type: 'Record<string, JSONValue> | undefined',
+              description: 'Additional metadata from telemetry settings.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'values',
+      type: 'Array<string>',
+      description: 'The values that were embedded.',
+    },
+    {
+      name: 'embeddings',
+      type: 'number[][]',
+      description: 'The embeddings. They are in the same order as the values.',
+    },
+    {
+      name: 'usage',
+      type: 'EmbeddingModelUsage',
+      description: 'The token usage for generating the embeddings.',
+      properties: [
+        {
+          type: 'EmbeddingModelUsage',
+          parameters: [
+            {
+              name: 'tokens',
+              type: 'number',
+              description: 'The total number of input tokens.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'warnings',
+      type: 'Warning[]',
+      description:
+        'Warnings from the model provider (e.g. unsupported settings).',
+    },
+    {
+      name: 'providerMetadata',
+      type: 'ProviderMetadata | undefined',
+      isOptional: true,
+      description:
+        'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
+    },
+    {
+      name: 'responses',
+      type: 'Array<{ headers?: Record<string, string>; body?: unknown } | undefined>',
+      isOptional: true,
+      description:
+        'Optional raw response data from each chunk request. There may be multiple responses if the request was split into multiple chunks.',
+    },
+  ]}
+/>