Suggestion for endpoints (#138)

Co-authored-by: coyotte508 <[email protected]>

Author: vvmnnnkv

README.md

@@ -14,7 +14,7 @@
 This is a collection of JS libraries to interact with the Hugging Face API, with TS types included.
 
 - [@huggingface/hub](packages/hub/README.md): Interact with huggingface.co to create or delete repos and commit / download files
-- [@huggingface/inference](packages/inference/README.md): Use the Inference API to make calls to 100,000+ Machine Learning models!
+- [@huggingface/inference](packages/inference/README.md): Use the Inference API to make calls to 100,000+ Machine Learning models, or to your own [inference endpoints](https://hf.co/docs/inference-endpoints/)!
 
 With more to come, like `@huggingface/endpoints` to manage your HF Endpoints!
 
@@ -102,6 +102,10 @@ await inference.imageToText({
   data: await (await fetch('https://picsum.photos/300/300')).blob(),
   model: 'nlpconnect/vit-gpt2-image-captioning',  
 })
+
+// Using your own inference endpoint: https://hf.co/docs/inference-endpoints/
+const gpt2 = hf.endpoint('https://xyz.eu-west-1.aws.endpoints.huggingface.cloud/gpt2');
+const { generated_text } = await gpt2.textGeneration({inputs: 'The answer to the universe is'});
 ```
 
 There are more features of course, check each library's README!

packages/inference/README.md

@@ -1,8 +1,10 @@
 # 🤗 Hugging Face Inference API
 
-A Typescript powered wrapper for the Hugging Face Inference API. Learn more about the Inference API at [Hugging Face](https://huggingface.co/docs/api-inference/index).
+A Typescript powered wrapper for the Hugging Face Inference API. Learn more about the Inference API at [Hugging Face](https://huggingface.co/docs/api-inference/index). It also works with [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index).
 
-Check out the [full documentation](https://huggingface.co/docs/huggingface.js/inference/README) or try out a live [interactive notebook](https://observablehq.com/@huggingface/hello-huggingface-js-inference).
+Check out the [full documentation](https://huggingface.co/docs/huggingface.js/inference/README).
+
+You can also try out a live [interactive notebook](https://observablehq.com/@huggingface/hello-huggingface-js-inference) or see some demos on [hf.co/huggingfacejs](https://huggingface.co/huggingfacejs).
 
 ## Install
 
@@ -16,16 +18,16 @@ pnpm add @huggingface/inference
 
 ## Usage
 
-❗**Important note:** Using an API key is optional to get started, however you will be rate limited eventually. Join [Hugging Face](https://huggingface.co/join) and then visit [access tokens](https://huggingface.co/settings/tokens) to generate your API key for **free**.
+❗**Important note:** Using an access token is optional to get started, however you will be rate limited eventually. Join [Hugging Face](https://huggingface.co/join) and then visit [access tokens](https://huggingface.co/settings/tokens) to generate your access token for **free**.
 
-Your API key should be kept private. If you need to protect it in front-end applications, we suggest setting up a proxy server that stores the API key.
+Your access token should be kept private. If you need to protect it in front-end applications, we suggest setting up a proxy server that stores the access token.
 
 ### Basic examples
 
 ```typescript
 import { HfInference } from '@huggingface/inference'
 
-const hf = new HfInference('your api key')
+const hf = new HfInference('your access token')
 
 // Natural Language
 
@@ -167,6 +169,10 @@ await hf.imageToText({
   data: readFileSync('test/cats.png'),
   model: 'nlpconnect/vit-gpt2-image-captioning'
 })
+
+// Using your own inference endpoint: https://hf.co/docs/inference-endpoints/
+const gpt2 = hf.endpoint('https://xyz.eu-west-1.aws.endpoints.huggingface.cloud/gpt2');
+const { generated_text } = await gpt2.textGeneration({inputs: 'The answer to the universe is'});
 ```
 
 ## Supported Tasks

packages/inference/src/HfInference.ts

@@ -29,7 +29,10 @@ export interface Options {
 }
 
 export interface Args {
-	model: string;
+	/**
+	 * The model to use. Optional for endpoints.
+	 */
+	model?: string;
 }
 
 export type FillMaskArgs = Args & {
@@ -639,10 +642,19 @@ export interface ImageToTextReturn {
 export class HfInference {
 	private readonly apiKey: string;
 	private readonly defaultOptions: Options;
+	private readonly endpointUrl?: string;
 
-	constructor(apiKey = "", defaultOptions: Options = {}) {
+	constructor(apiKey = "", defaultOptions: Options = {}, endpointUrl?: string) {
 		this.apiKey = apiKey;
 		this.defaultOptions = defaultOptions;
+		this.endpointUrl = endpointUrl;
+	}
+
+	/**
+	 * Returns copy of HfInference tied to a specified endpoint.
+	 */
+	public endpoint(endpointUrl: string): HfInference {
+		return new HfInference(this.apiKey, this.defaultOptions, endpointUrl);
 	}
 
 	/**
@@ -1063,7 +1075,10 @@ export class HfInference {
 			}
 		}
 
-		const url = `${HF_INFERENCE_API_BASE_URL}${model}`;
+		if (!model && !this.endpointUrl) {
+			throw new Error("Model is required for Inference API");
+		}
+		const url = this.endpointUrl ? this.endpointUrl : `${HF_INFERENCE_API_BASE_URL}${model}`;
 		const info: RequestInit = {
 			headers,
 			method: "POST",

packages/inference/test/HfInference.spec.ts

@@ -397,6 +397,20 @@ describe.concurrent(
 				generated_text: "a large brown and white giraffe standing in a field ",
 			});
 		});
+		it("endpoint - makes request to specified endpoint", async () => {
+			const ep = hf.endpoint("https://api-inference.huggingface.co/models/google/flan-t5-xxl");
+			const { generated_text } = await ep.textGeneration({
+				inputs: "one plus two equals",
+			});
+			expect(generated_text).toEqual("three");
+		});
+		it("error when the model is not set", () => {
+			expect(
+				hf.textGeneration({
+					inputs: "one plus two equals",
+				})
+			).rejects.toThrowError("Model is required for Inference API");
+		});
 	},
 	TIMEOUT
 );

packages/inference/test/tapes.json

@@ -447,6 +447,26 @@
       }
     }
   },
+  "e64d5b8d2371f0706f29b4e27cac68b3f1e9fe3b10013a7f008ddbe005d7eb8f": {
+    "url": "https://api-inference.huggingface.co/models/google/flan-t5-xxl",
+    "init": {
+      "headers": {
+        "Content-Type": "application/json"
+      },
+      "method": "POST"
+    },
+    "response": {
+     "body": "[{\"generated_text\":\"three\"}]",
+      "status": 200,
+      "statusText": "OK",
+      "headers": {
+        "access-control-allow-credentials": "true",
+        "connection": "keep-alive",
+        "content-type": "application/json",
+        "vary": "Origin, Access-Control-Request-Method, Access-Control-Request-Headers"
+      }
+    }
+  },
   "7364916c1dcc1aaf643027e0c86abcf22e3b963dd5876fce23ffa7604465899e": {
     "url": "https://api-inference.huggingface.co/models/sentence-transformers/distilbert-base-nli-mean-tokens",
     "init": {