[Inference] request() returns a request context to avoid redundant makeRequestOptions calls (#1314)

Related to @SBrandeis's comment here
#1292 (comment).
This PR addresses the original concern about redundant
`makeRequestOptions` calls introduced in #1292.The solution implemented
here updates the `request` function to return both the response and a
_request context_ when needed, allowing provider-specific polling code
to reuse this context without redundant calls to `makeRequestOptions`.

This differs from the initial suggestion in the comment as each provider
implements polling differently with different parameters / response
formats. Making a generic `.poll` property would require mixing
provider-specific logic into the core request function (we don't want
that, right? 😄 ).
In the end, we want to keep provider-specific logic isolated in their
respective provider files (PR coming today to push that further!).

Author: hanouticelina

packages/inference/README.md

@@ -572,31 +572,6 @@ await hf.tabularClassification({
 })
 ```
 
-## Custom Calls
-
-For models with custom parameters / outputs.
-
-```typescript
-await hf.request({
-  model: 'my-custom-model',
-  inputs: 'hello world',
-  parameters: {
-    custom_param: 'some magic',
-  }
-})
-
-// Custom streaming call, for models with custom parameters / outputs
-for await (const output of hf.streamingRequest({
-  model: 'my-custom-model',
-  inputs: 'hello world',
-  parameters: {
-    custom_param: 'some magic',
-  }
-})) {
-  ...
-}
-```
-
 You can use any Chat Completion API-compatible provider with the `chatCompletion` method.
 
 ```typescript

packages/inference/src/tasks/audio/audioClassification.ts

@@ -1,7 +1,7 @@
 import type { AudioClassificationInput, AudioClassificationOutput } from "@huggingface/tasks";
 import { InferenceOutputError } from "../../lib/InferenceOutputError";
 import type { BaseArgs, Options } from "../../types";
-import { request } from "../custom/request";
+import { innerRequest } from "../../utils/request";
 import type { LegacyAudioInput } from "./utils";
 import { preparePayload } from "./utils";
 
@@ -16,7 +16,7 @@ export async function audioClassification(
 	options?: Options
 ): Promise<AudioClassificationOutput> {
 	const payload = preparePayload(args);
-	const res = await request<AudioClassificationOutput>(payload, {
+	const { data: res } = await innerRequest<AudioClassificationOutput>(payload, {
 		...options,
 		task: "audio-classification",
 	});

packages/inference/src/tasks/audio/audioToAudio.ts

@@ -1,6 +1,6 @@
 import { InferenceOutputError } from "../../lib/InferenceOutputError";
 import type { BaseArgs, Options } from "../../types";
-import { request } from "../custom/request";
+import { innerRequest } from "../../utils/request";
 import type { LegacyAudioInput } from "./utils";
 import { preparePayload } from "./utils";
 
@@ -37,7 +37,7 @@ export interface AudioToAudioOutput {
  */
 export async function audioToAudio(args: AudioToAudioArgs, options?: Options): Promise<AudioToAudioOutput[]> {
 	const payload = preparePayload(args);
-	const res = await request<AudioToAudioOutput>(payload, {
+	const { data: res } = await innerRequest<AudioToAudioOutput>(payload, {
 		...options,
 		task: "audio-to-audio",
 	});

packages/inference/src/tasks/audio/automaticSpeechRecognition.ts

@@ -2,10 +2,10 @@ import type { AutomaticSpeechRecognitionInput, AutomaticSpeechRecognitionOutput
 import { InferenceOutputError } from "../../lib/InferenceOutputError";
 import type { BaseArgs, Options, RequestArgs } from "../../types";
 import { base64FromBytes } from "../../utils/base64FromBytes";
-import { request } from "../custom/request";
+import { omit } from "../../utils/omit";
+import { innerRequest } from "../../utils/request";
 import type { LegacyAudioInput } from "./utils";
 import { preparePayload } from "./utils";
-import { omit } from "../../utils/omit";
 
 export type AutomaticSpeechRecognitionArgs = BaseArgs & (AutomaticSpeechRecognitionInput | LegacyAudioInput);
 /**
@@ -17,7 +17,7 @@ export async function automaticSpeechRecognition(
 	options?: Options
 ): Promise<AutomaticSpeechRecognitionOutput> {
 	const payload = await buildPayload(args);
-	const res = await request<AutomaticSpeechRecognitionOutput>(payload, {
+	const { data: res } = await innerRequest<AutomaticSpeechRecognitionOutput>(payload, {
 		...options,
 		task: "automatic-speech-recognition",
 	});

packages/inference/src/tasks/audio/textToSpeech.ts

@@ -2,7 +2,7 @@ import type { TextToSpeechInput } from "@huggingface/tasks";
 import { InferenceOutputError } from "../../lib/InferenceOutputError";
 import type { BaseArgs, Options } from "../../types";
 import { omit } from "../../utils/omit";
-import { request } from "../custom/request";
+import { innerRequest } from "../../utils/request";
 type TextToSpeechArgs = BaseArgs & TextToSpeechInput;
 
 interface OutputUrlTextToSpeechGeneration {
@@ -22,7 +22,7 @@ export async function textToSpeech(args: TextToSpeechArgs, options?: Options): P
 					text: args.inputs,
 			  }
 			: args;
-	const res = await request<Blob | OutputUrlTextToSpeechGeneration>(payload, {
+	const { data: res } = await innerRequest<Blob | OutputUrlTextToSpeechGeneration>(payload, {
 		...options,
 		task: "text-to-speech",
 	});

packages/inference/src/tasks/custom/request.ts

@@ -1,8 +1,9 @@
 import type { InferenceTask, Options, RequestArgs } from "../../types";
-import { makeRequestOptions } from "../../lib/makeRequestOptions";
+import { innerRequest } from "../../utils/request";
 
 /**
  * Primitive to make custom calls to the inference provider
+ * @deprecated Use specific task functions instead. This function will be removed in a future version.
  */
 export async function request<T>(
 	args: RequestArgs,
@@ -13,35 +14,9 @@ export async function request<T>(
 		chatCompletion?: boolean;
 	}
 ): Promise<T> {
-	const { url, info } = await makeRequestOptions(args, options);
-	const response = await (options?.fetch ?? fetch)(url, info);
-
-	if (options?.retry_on_error !== false && response.status === 503) {
-		return request(args, options);
-	}
-
-	if (!response.ok) {
-		const contentType = response.headers.get("Content-Type");
-		if (["application/json", "application/problem+json"].some((ct) => contentType?.startsWith(ct))) {
-			const output = await response.json();
-			if ([400, 422, 404, 500].includes(response.status) && options?.chatCompletion) {
-				throw new Error(
-					`Server ${args.model} does not seem to support chat completion. Error: ${JSON.stringify(output.error)}`
-				);
-			}
-			if (output.error || output.detail) {
-				throw new Error(JSON.stringify(output.error ?? output.detail));
-			} else {
-				throw new Error(output);
-			}
-		}
-		const message = contentType?.startsWith("text/plain;") ? await response.text() : undefined;
-		throw new Error(message ?? "An error occurred while fetching the blob");
-	}
-
-	if (response.headers.get("Content-Type")?.startsWith("application/json")) {
-		return await response.json();
-	}
-
-	return (await response.blob()) as T;
+	console.warn(
+		"The request method is deprecated and will be removed in a future version of huggingface.js. Use specific task functions instead."
+	);
+	const result = await innerRequest<T>(args, options);
+	return result.data;
 }

packages/inference/src/tasks/custom/streamingRequest.ts

@@ -1,10 +1,8 @@
 import type { InferenceTask, Options, RequestArgs } from "../../types";
-import { makeRequestOptions } from "../../lib/makeRequestOptions";
-import type { EventSourceMessage } from "../../vendor/fetch-event-source/parse";
-import { getLines, getMessages } from "../../vendor/fetch-event-source/parse";
-
+import { innerStreamingRequest } from "../../utils/request";
 /**
  * Primitive to make custom inference calls that expect server-sent events, and returns the response through a generator
+ * @deprecated Use specific task functions instead. This function will be removed in a future version.
  */
 export async function* streamingRequest<T>(
 	args: RequestArgs,
@@ -15,86 +13,8 @@ export async function* streamingRequest<T>(
 		chatCompletion?: boolean;
 	}
 ): AsyncGenerator<T> {
-	const { url, info } = await makeRequestOptions({ ...args, stream: true }, options);
-	const response = await (options?.fetch ?? fetch)(url, info);
-
-	if (options?.retry_on_error !== false && response.status === 503) {
-		return yield* streamingRequest(args, options);
-	}
-	if (!response.ok) {
-		if (response.headers.get("Content-Type")?.startsWith("application/json")) {
-			const output = await response.json();
-			if ([400, 422, 404, 500].includes(response.status) && options?.chatCompletion) {
-				throw new Error(`Server ${args.model} does not seem to support chat completion. Error: ${output.error}`);
-			}
-			if (typeof output.error === "string") {
-				throw new Error(output.error);
-			}
-			if (output.error && "message" in output.error && typeof output.error.message === "string") {
-				/// OpenAI errors
-				throw new Error(output.error.message);
-			}
-		}
-
-		throw new Error(`Server response contains error: ${response.status}`);
-	}
-	if (!response.headers.get("content-type")?.startsWith("text/event-stream")) {
-		throw new Error(
-			`Server does not support event stream content type, it returned ` + response.headers.get("content-type")
-		);
-	}
-
-	if (!response.body) {
-		return;
-	}
-
-	const reader = response.body.getReader();
-	let events: EventSourceMessage[] = [];
-
-	const onEvent = (event: EventSourceMessage) => {
-		// accumulate events in array
-		events.push(event);
-	};
-
-	const onChunk = getLines(
-		getMessages(
-			() => {},
-			() => {},
-			onEvent
-		)
+	console.warn(
+		"The streamingRequest method is deprecated and will be removed in a future version of huggingface.js. Use specific task functions instead."
 	);
-
-	try {
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) {
-				return;
-			}
-			onChunk(value);
-			for (const event of events) {
-				if (event.data.length > 0) {
-					if (event.data === "[DONE]") {
-						return;
-					}
-					const data = JSON.parse(event.data);
-					if (typeof data === "object" && data !== null && "error" in data) {
-						const errorStr =
-							typeof data.error === "string"
-								? data.error
-								: typeof data.error === "object" &&
-								    data.error &&
-								    "message" in data.error &&
-								    typeof data.error.message === "string"
-								  ? data.error.message
-								  : JSON.stringify(data.error);
-						throw new Error(`Error forwarded from backend: ` + errorStr);
-					}
-					yield data as T;
-				}
-			}
-			events = [];
-		}
-	} finally {
-		reader.releaseLock();
-	}
+	yield* innerStreamingRequest(args, options);
 }

packages/inference/src/tasks/cv/imageClassification.ts

@@ -1,7 +1,7 @@
 import type { ImageClassificationInput, ImageClassificationOutput } from "@huggingface/tasks";
 import { InferenceOutputError } from "../../lib/InferenceOutputError";
 import type { BaseArgs, Options } from "../../types";
-import { request } from "../custom/request";
+import { innerRequest } from "../../utils/request";
 import { preparePayload, type LegacyImageInput } from "./utils";
 
 export type ImageClassificationArgs = BaseArgs & (ImageClassificationInput | LegacyImageInput);
@@ -15,7 +15,7 @@ export async function imageClassification(
 	options?: Options
 ): Promise<ImageClassificationOutput> {
 	const payload = preparePayload(args);
-	const res = await request<ImageClassificationOutput>(payload, {
+	const { data: res } = await innerRequest<ImageClassificationOutput>(payload, {
 		...options,
 		task: "image-classification",
 	});

packages/inference/src/tasks/cv/imageSegmentation.ts

@@ -1,7 +1,7 @@
 import type { ImageSegmentationInput, ImageSegmentationOutput } from "@huggingface/tasks";
 import { InferenceOutputError } from "../../lib/InferenceOutputError";
 import type { BaseArgs, Options } from "../../types";
-import { request } from "../custom/request";
+import { innerRequest } from "../../utils/request";
 import { preparePayload, type LegacyImageInput } from "./utils";
 
 export type ImageSegmentationArgs = BaseArgs & (ImageSegmentationInput | LegacyImageInput);
@@ -15,7 +15,7 @@ export async function imageSegmentation(
 	options?: Options
 ): Promise<ImageSegmentationOutput> {
 	const payload = preparePayload(args);
-	const res = await request<ImageSegmentationOutput>(payload, {
+	const { data: res } = await innerRequest<ImageSegmentationOutput>(payload, {
 		...options,
 		task: "image-segmentation",
 	});

packages/inference/src/tasks/cv/imageToImage.ts

@@ -2,7 +2,7 @@ import type { ImageToImageInput } from "@huggingface/tasks";
 import { InferenceOutputError } from "../../lib/InferenceOutputError";
 import type { BaseArgs, Options, RequestArgs } from "../../types";
 import { base64FromBytes } from "../../utils/base64FromBytes";
-import { request } from "../custom/request";
+import { innerRequest } from "../../utils/request";
 
 export type ImageToImageArgs = BaseArgs & ImageToImageInput;
 
@@ -26,7 +26,7 @@ export async function imageToImage(args: ImageToImageArgs, options?: Options): P
 			),
 		};
 	}
-	const res = await request<Blob>(reqArgs, {
+	const { data: res } = await innerRequest<Blob>(reqArgs, {
 		...options,
 		task: "image-to-image",
 	});