Buckets:

hf-doc-build
/

doc-dev

Files

xet

hf-doc-build/doc-dev / text-generation-inference /pr_2965 /en /basic_tutorials /using_guidance.html

rtrm

about 2 months ago

download

raw

71.1 kB

	<meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"Guidance","local":"guidance","sections":[{"title":"How it works","local":"how-it-works","sections":[],"depth":2},{"title":"Table of Contents 📚","local":"table-of-contents-","sections":[{"title":"Grammar and Constraints","local":"grammar-and-constraints","sections":[],"depth":3},{"title":"Tools and Functions","local":"tools-and-functions","sections":[],"depth":3}],"depth":2},{"title":"Grammar and Constraints 🛣️","local":"grammar-and-constraints-","sections":[{"title":"The Grammar Parameter","local":"the-grammar-parameter","sections":[],"depth":3},{"title":"Hugging Face Hub Python Library","local":"hugging-face-hub-python-library","sections":[],"depth":3},{"title":"Constrain with Pydantic","local":"constrain-with-pydantic","sections":[],"depth":3}],"depth":2},{"title":"Tools and Functions 🛠️","local":"tools-and-functions-","sections":[{"title":"The Tools Parameter","local":"the-tools-parameter","sections":[],"depth":3},{"title":"Chat Completion with Tools","local":"chat-completion-with-tools","sections":[],"depth":3},{"title":"OpenAI integration","local":"openai-integration","sections":[],"depth":3},{"title":"Tool Choice Configuration","local":"tool-choice-configuration","sections":[],"depth":3}],"depth":2}],"depth":1}">
	<link href="/docs/text-generation-inference/pr_2965/en/_app/immutable/assets/0.e3b0c442.css" rel="modulepreload">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/entry/start.6569fc45.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/chunks/scheduler.362310b7.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/chunks/singletons.189677f5.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/chunks/index.7f53ec41.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/chunks/paths.323159e8.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/entry/app.98c60904.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/chunks/index.57dfc70d.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/nodes/0.69e98ac5.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/chunks/each.e59479a4.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/nodes/12.4c91dda4.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/chunks/CodeBlock.d3c47f83.js">
	<link rel="modulepreload" href="/docs/text-generation-inference/pr_2965/en/_app/immutable/chunks/EditOnGithub.9633c464.js"><!-- HEAD_svelte-u9bgzb_START --><meta name="hf:doc:metadata" content="{"title":"Guidance","local":"guidance","sections":[{"title":"How it works","local":"how-it-works","sections":[],"depth":2},{"title":"Table of Contents 📚","local":"table-of-contents-","sections":[{"title":"Grammar and Constraints","local":"grammar-and-constraints","sections":[],"depth":3},{"title":"Tools and Functions","local":"tools-and-functions","sections":[],"depth":3}],"depth":2},{"title":"Grammar and Constraints 🛣️","local":"grammar-and-constraints-","sections":[{"title":"The Grammar Parameter","local":"the-grammar-parameter","sections":[],"depth":3},{"title":"Hugging Face Hub Python Library","local":"hugging-face-hub-python-library","sections":[],"depth":3},{"title":"Constrain with Pydantic","local":"constrain-with-pydantic","sections":[],"depth":3}],"depth":2},{"title":"Tools and Functions 🛠️","local":"tools-and-functions-","sections":[{"title":"The Tools Parameter","local":"the-tools-parameter","sections":[],"depth":3},{"title":"Chat Completion with Tools","local":"chat-completion-with-tools","sections":[],"depth":3},{"title":"OpenAI integration","local":"openai-integration","sections":[],"depth":3},{"title":"Tool Choice Configuration","local":"tool-choice-configuration","sections":[],"depth":3}],"depth":2}],"depth":1}"><!-- HEAD_svelte-u9bgzb_END --> <p></p> <h1 class="relative group"><a id="guidance" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#guidance"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Guidance</span></h1> <p data-svelte-h="svelte-kbjeep">Text Generation Inference (TGI) now supports <a href="#grammar-and-constraints">JSON and regex grammars</a> and <a href="#tools-and-functions">tools and functions</a> to help developers guide LLM responses to fit their needs.</p> <p data-svelte-h="svelte-fq1iv3">These feature are available starting from version <code>1.4.3</code>. They are accessible via the <a href="https://pypi.org/project/huggingface-hub/" rel="nofollow"><code>huggingface_hub</code></a> library. The tool support is compatible with OpenAI’s client libraries. The following guide will walk you through the new features and how to use them!</p> <p data-svelte-h="svelte-bfgv2a"><em>note: guidance is supported as grammar in the <code>/generate</code> endpoint and as tools in the <code>v1/chat/completions</code> endpoint.</em></p> <h2 class="relative group"><a id="how-it-works" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#how-it-works"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>How it works</span></h2> <p data-svelte-h="svelte-wsp0l4">TGI leverages the <a href="https://github.com/outlines-dev/outlines" rel="nofollow">outlines</a> library to efficiently parse and compile the grammatical structures and tools specified by users. This integration transforms the defined grammars into an intermediate representation that acts as a framework to guide and constrain content generation, ensuring that outputs adhere to the specified grammatical rules.</p> <p data-svelte-h="svelte-15m2t7v">If you are interested in the technical details on how outlines is used in TGI, you can check out the <a href="../conceptual/guidance">conceptual guidance documentation</a>.</p> <h2 class="relative group"><a id="table-of-contents-" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#table-of-contents-"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Table of Contents 📚</span></h2> <h3 class="relative group"><a id="grammar-and-constraints" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#grammar-and-constraints"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Grammar and Constraints</span></h3> <ul data-svelte-h="svelte-12576sd"><li><a href="#the-grammar-parameter">The Grammar Parameter</a>: Shape your AI’s responses with precision.</li> <li><a href="#constrain-with-pydantic">Constrain with Pydantic</a>: Define a grammar using Pydantic models.</li> <li><a href="#json-schema-integration">JSON Schema Integration</a>: Fine-grained control over your requests via JSON schema.</li> <li><a href="#using-the-client">Using the client</a>: Use TGI’s client libraries to shape the AI’s responses.</li></ul> <h3 class="relative group"><a id="tools-and-functions" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#tools-and-functions"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Tools and Functions</span></h3> <ul data-svelte-h="svelte-18ofpvb"><li><a href="#the-tools-parameter">The Tools Parameter</a>: Enhance the AI’s capabilities with predefined functions.</li> <li><a href="#text-generation-inference-client">Via the client</a>: Use TGI’s client libraries to interact with the Messages API and Tool functions.</li> <li><a href="#openai-integration">OpenAI integration</a>: Use OpenAI’s client libraries to interact with TGI’s Messages API and Tool functions.</li></ul> <h2 class="relative group"><a id="grammar-and-constraints-" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#grammar-and-constraints-"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Grammar and Constraints 🛣️</span></h2> <h3 class="relative group"><a id="the-grammar-parameter" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#the-grammar-parameter"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>The Grammar Parameter</span></h3> <p data-svelte-h="svelte-yoqu28">In TGI <code>1.4.3</code>, we’ve introduced the grammar parameter, which allows you to specify the format of the response you want from the LLM.</p> <p data-svelte-h="svelte-1vsv0tm">Using curl, you can make a request to TGI’s Messages API with the grammar parameter. This is the most primitive way to interact with the API and using <a href="#constrain-with-pydantic">Pydantic</a> is recommended for ease of use and readability.</p> <div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->curl localhost<span class="hljs-punctuation">:</span><span class="hljs-number">3000</span>/generate \
	-X POST \
	-H 'Content-Type<span class="hljs-punctuation">:</span> application/json' \
	-d '<span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"inputs"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"I saw a puppy a cat and a raccoon during my bike ride in the park"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"parameters"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"repetition_penalty"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1.3</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"grammar"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"json"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"properties"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"location"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span>
	<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"activity"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span>
	<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"animals_seen"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"integer"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"minimum"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"maximum"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">5</span>
	<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"animals"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"array"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"items"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"required"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-string">"location"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"activity"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"animals_seen"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"animals"</span><span class="hljs-punctuation">]</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">}</span>'
	<span class="hljs-comment">// {"generated_text":"{ \n\n\"activity\": \"biking\",\n\"animals\": [\"puppy\",\"cat\",\"raccoon\"],\n\"animals_seen\": 3,\n\"location\": \"park\"\n}"}</span>
	<!-- HTML_TAG_END --></pre></div> <h3 class="relative group"><a id="hugging-face-hub-python-library" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#hugging-face-hub-python-library"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Hugging Face Hub Python Library</span></h3> <p data-svelte-h="svelte-126mt2g">The Hugging Face Hub Python library provides a client that makes it easy to interact with the Messages API. Here’s an example of how to use the client to send a request with a grammar parameter.</p> <div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> huggingface_hub <span class="hljs-keyword">import</span> InferenceClient

	client = InferenceClient(<span class="hljs-string">"http://localhost:3000"</span>)

	schema = {
	<span class="hljs-string">"properties"</span>: {
	<span class="hljs-string">"location"</span>: {<span class="hljs-string">"title"</span>: <span class="hljs-string">"Location"</span>, <span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>},
	<span class="hljs-string">"activity"</span>: {<span class="hljs-string">"title"</span>: <span class="hljs-string">"Activity"</span>, <span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>},
	<span class="hljs-string">"animals_seen"</span>: {
	<span class="hljs-string">"maximum"</span>: <span class="hljs-number">5</span>,
	<span class="hljs-string">"minimum"</span>: <span class="hljs-number">1</span>,
	<span class="hljs-string">"title"</span>: <span class="hljs-string">"Animals Seen"</span>,
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"integer"</span>,
	},
	<span class="hljs-string">"animals"</span>: {<span class="hljs-string">"items"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>}, <span class="hljs-string">"title"</span>: <span class="hljs-string">"Animals"</span>, <span class="hljs-string">"type"</span>: <span class="hljs-string">"array"</span>},
	},
	<span class="hljs-string">"required"</span>: [<span class="hljs-string">"location"</span>, <span class="hljs-string">"activity"</span>, <span class="hljs-string">"animals_seen"</span>, <span class="hljs-string">"animals"</span>],
	<span class="hljs-string">"title"</span>: <span class="hljs-string">"Animals"</span>,
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"object"</span>,
	}

	user_input = <span class="hljs-string">"I saw a puppy a cat and a raccoon during my bike ride in the park"</span>
	resp = client.text_generation(
	<span class="hljs-string">f"convert to JSON: 'f<span class="hljs-subst">{user_input}</span>'. please use the following schema: <span class="hljs-subst">{schema}</span>"</span>,
	max_new_tokens=<span class="hljs-number">100</span>,
	seed=<span class="hljs-number">42</span>,
	grammar={<span class="hljs-string">"type"</span>: <span class="hljs-string">"json"</span>, <span class="hljs-string">"value"</span>: schema},
	)

	<span class="hljs-built_in">print</span>(resp)
	<span class="hljs-comment"># { "activity": "bike ride", "animals": ["puppy", "cat", "raccoon"], "animals_seen": 3, "location": "park" }</span>
	<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-1nlfjb7">A grammar can be defined using Pydantic models, JSON schemas, or regular expressions. The LLM will then generate a response that conforms to the specified grammar.</p> <blockquote data-svelte-h="svelte-cm9i0i"><p>Note: A grammar must compile to an intermediate representation to constrain the output. Grammar compilation is a computationally expensive and may take a few seconds to complete on the first request. Subsequent requests will use the cached grammar and will be much faster.</p></blockquote> <h3 class="relative group"><a id="constrain-with-pydantic" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#constrain-with-pydantic"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Constrain with Pydantic</span></h3> <p data-svelte-h="svelte-3pxjtu">Using Pydantic models we can define a similar grammar as the previous example in a shorter and more readable way.</p> <div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> huggingface_hub <span class="hljs-keyword">import</span> InferenceClient
	<span class="hljs-keyword">from</span> pydantic <span class="hljs-keyword">import</span> BaseModel, conint
	<span class="hljs-keyword">from</span> typing <span class="hljs-keyword">import</span> <span class="hljs-type">List</span>


	<span class="hljs-keyword">class</span> <span class="hljs-title class_">Animals</span>(<span class="hljs-title class_ inherited__">BaseModel</span>):
	location: <span class="hljs-built_in">str</span>
	activity: <span class="hljs-built_in">str</span>
	animals_seen: conint(ge=<span class="hljs-number">1</span>, le=<span class="hljs-number">5</span>) <span class="hljs-comment"># Constrained integer type</span>
	animals: <span class="hljs-type">List</span>[<span class="hljs-built_in">str</span>]


	client = InferenceClient(<span class="hljs-string">"http://localhost:3000"</span>)

	user_input = <span class="hljs-string">"I saw a puppy a cat and a raccoon during my bike ride in the park"</span>
	resp = client.text_generation(
	<span class="hljs-string">f"convert to JSON: 'f<span class="hljs-subst">{user_input}</span>'. please use the following schema: <span class="hljs-subst">{Animals.schema()}</span>"</span>,
	max_new_tokens=<span class="hljs-number">100</span>,
	seed=<span class="hljs-number">42</span>,
	grammar={<span class="hljs-string">"type"</span>: <span class="hljs-string">"json"</span>, <span class="hljs-string">"value"</span>: Animals.schema()},
	)

	<span class="hljs-built_in">print</span>(resp)
	<span class="hljs-comment"># { "activity": "bike ride", "animals": ["puppy", "cat", "raccoon"], "animals_seen": 3, "location": "park" }</span>

	<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-6wpj0x">defining a grammar as regular expressions</p> <div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> huggingface_hub <span class="hljs-keyword">import</span> InferenceClient

	client = InferenceClient(<span class="hljs-string">"http://localhost:3000"</span>)

	section_regex = <span class="hljs-string">"(?:25[0-5]\|2[0-4][0-9]\|[01]?[0-9][0-9]?)"</span>
	regexp = <span class="hljs-string">f"HELLO\.<span class="hljs-subst">{section_regex}</span>\.WORLD\.<span class="hljs-subst">{section_regex}</span>"</span>

	<span class="hljs-comment"># This is a more realistic example of an ip address regex</span>
	<span class="hljs-comment"># regexp = f"{section_regex}\.{section_regex}\.{section_regex}\.{section_regex}"</span>


	resp = client.text_generation(
	<span class="hljs-string">f"Whats Googles DNS? Please use the following regex: <span class="hljs-subst">{regexp}</span>"</span>,
	seed=<span class="hljs-number">42</span>,
	grammar={
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"regex"</span>,
	<span class="hljs-string">"value"</span>: regexp,
	},
	)


	<span class="hljs-built_in">print</span>(resp)
	<span class="hljs-comment"># HELLO.255.WORLD.255</span>
	<!-- HTML_TAG_END --></pre></div> <h2 class="relative group"><a id="tools-and-functions-" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#tools-and-functions-"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Tools and Functions 🛠️</span></h2> <h3 class="relative group"><a id="the-tools-parameter" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#the-tools-parameter"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>The Tools Parameter</span></h3> <p data-svelte-h="svelte-lut42n">In addition to the grammar parameter, we’ve also introduced a set of tools and functions to help you get the most out of the Messages API.</p> <p data-svelte-h="svelte-1a560wn">Tools are a set of user defined functions that can be used in tandem with the chat functionality to enhance the LLM’s capabilities. Functions, similar to grammar are defined as JSON schema and can be passed as part of the parameters to the Messages API.</p> <div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->curl localhost<span class="hljs-punctuation">:</span><span class="hljs-number">3000</span>/v1/chat/completions \
	-X POST \
	-H 'Content-Type<span class="hljs-punctuation">:</span> application/json' \
	-d '<span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"model"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"tgi"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"messages"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
	<span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"role"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"user"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"content"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"What is the weather like in New York?"</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"tools"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
	<span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"function"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"function"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"get_current_weather"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Get the current weather"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"parameters"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"object"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"properties"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"location"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"The city and state, e.g. San Francisco, CA"</span>
	<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"format"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"enum"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-string">"celsius"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"fahrenheit"</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"The temperature unit to use. Infer this from the users location."</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"required"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-string">"location"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"format"</span><span class="hljs-punctuation">]</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">}</span>
	<span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"tool_choice"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"get_current_weather"</span>
	<span class="hljs-punctuation">}</span>'
	<span class="hljs-comment">// {"id":"","object":"text_completion","created":1709051640,"model":"HuggingFaceH4/zephyr-7b-beta","system_fingerprint":"1.4.3-native","choices":[{"index":0,"message":{"role":"assistant","tool_calls":{"id":0,"type":"function","function":{"description":null,"name":"tools","parameters":{"format":"celsius","location":"New York"}}}},"logprobs":null,"finish_reason":"eos_token"}],"usage":{"prompt_tokens":157,"completion_tokens":19,"total_tokens":176}}</span><!-- HTML_TAG_END --></pre></div> <h3 class="relative group"><a id="chat-completion-with-tools" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#chat-completion-with-tools"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Chat Completion with Tools</span></h3> <p data-svelte-h="svelte-13xxzo">Grammars are supported in the <code>/generate</code> endpoint, while tools are supported in the <code>/chat/completions</code> endpoint. Here’s an example of how to use the client to send a request with a tool parameter.</p> <div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> huggingface_hub <span class="hljs-keyword">import</span> InferenceClient

	client = InferenceClient(<span class="hljs-string">"http://localhost:3000"</span>)

	tools = [
	{
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"function"</span>,
	<span class="hljs-string">"function"</span>: {
	<span class="hljs-string">"name"</span>: <span class="hljs-string">"get_current_weather"</span>,
	<span class="hljs-string">"description"</span>: <span class="hljs-string">"Get the current weather"</span>,
	<span class="hljs-string">"parameters"</span>: {
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"object"</span>,
	<span class="hljs-string">"properties"</span>: {
	<span class="hljs-string">"location"</span>: {
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>,
	<span class="hljs-string">"description"</span>: <span class="hljs-string">"The city and state, e.g. San Francisco, CA"</span>,
	},
	<span class="hljs-string">"format"</span>: {
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>,
	<span class="hljs-string">"enum"</span>: [<span class="hljs-string">"celsius"</span>, <span class="hljs-string">"fahrenheit"</span>],
	<span class="hljs-string">"description"</span>: <span class="hljs-string">"The temperature unit to use. Infer this from the users location."</span>,
	},
	},
	<span class="hljs-string">"required"</span>: [<span class="hljs-string">"location"</span>, <span class="hljs-string">"format"</span>],
	},
	},
	},
	{
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"function"</span>,
	<span class="hljs-string">"function"</span>: {
	<span class="hljs-string">"name"</span>: <span class="hljs-string">"get_n_day_weather_forecast"</span>,
	<span class="hljs-string">"description"</span>: <span class="hljs-string">"Get an N-day weather forecast"</span>,
	<span class="hljs-string">"parameters"</span>: {
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"object"</span>,
	<span class="hljs-string">"properties"</span>: {
	<span class="hljs-string">"location"</span>: {
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>,
	<span class="hljs-string">"description"</span>: <span class="hljs-string">"The city and state, e.g. San Francisco, CA"</span>,
	},
	<span class="hljs-string">"format"</span>: {
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>,
	<span class="hljs-string">"enum"</span>: [<span class="hljs-string">"celsius"</span>, <span class="hljs-string">"fahrenheit"</span>],
	<span class="hljs-string">"description"</span>: <span class="hljs-string">"The temperature unit to use. Infer this from the users location."</span>,
	},
	<span class="hljs-string">"num_days"</span>: {
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"integer"</span>,
	<span class="hljs-string">"description"</span>: <span class="hljs-string">"The number of days to forecast"</span>,
	},
	},
	<span class="hljs-string">"required"</span>: [<span class="hljs-string">"location"</span>, <span class="hljs-string">"format"</span>, <span class="hljs-string">"num_days"</span>],
	},
	},
	},
	]

	chat = client.chat_completion(
	messages=[
	{
	<span class="hljs-string">"role"</span>: <span class="hljs-string">"system"</span>,
	<span class="hljs-string">"content"</span>: <span class="hljs-string">"You're a helpful assistant! Answer the users question best you can."</span>,
	},
	{
	<span class="hljs-string">"role"</span>: <span class="hljs-string">"user"</span>,
	<span class="hljs-string">"content"</span>: <span class="hljs-string">"What is the weather like in Brooklyn, New York?"</span>,
	},
	],
	tools=tools,
	seed=<span class="hljs-number">42</span>,
	max_tokens=<span class="hljs-number">100</span>,
	)

	<span class="hljs-built_in">print</span>(chat.choices[<span class="hljs-number">0</span>].message.tool_calls)
	<span class="hljs-comment"># [ChatCompletionOutputToolCall(function=ChatCompletionOutputFunctionDefinition(arguments={'format': 'fahrenheit', 'location': 'Brooklyn, New York', 'num_days': 7}, name='get_n_day_weather_forecast', description=None), id=0, type='function')]</span>
	<!-- HTML_TAG_END --></pre></div> <h3 class="relative group"><a id="openai-integration" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#openai-integration"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>OpenAI integration</span></h3> <p data-svelte-h="svelte-qj1me9">TGI exposes an OpenAI-compatible API, which means you can use OpenAI’s client libraries to interact with TGI’s Messages API and Tool functions.</p> <div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> openai <span class="hljs-keyword">import</span> OpenAI

	<span class="hljs-comment"># Initialize the client, pointing it to one of the available models</span>
	client = OpenAI(
	base_url=<span class="hljs-string">"http://localhost:3000/v1"</span>,
	api_key=<span class="hljs-string">"_"</span>,
	)

	<span class="hljs-comment"># <span class="hljs-doctag">NOTE:</span> tools defined above and removed for brevity</span>

	chat_completion = client.chat.completions.create(
	model=<span class="hljs-string">"tgi"</span>,
	messages=[
	{
	<span class="hljs-string">"role"</span>: <span class="hljs-string">"system"</span>,
	<span class="hljs-string">"content"</span>: <span class="hljs-string">"Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous."</span>,
	},
	{
	<span class="hljs-string">"role"</span>: <span class="hljs-string">"user"</span>,
	<span class="hljs-string">"content"</span>: <span class="hljs-string">"What's the weather like the next 3 days in San Francisco, CA?"</span>,
	},
	],
	tools=tools,
	tool_choice=<span class="hljs-string">"auto"</span>, <span class="hljs-comment"># tool selected by model</span>
	max_tokens=<span class="hljs-number">500</span>,
	)


	called = chat_completion.choices[<span class="hljs-number">0</span>].message.tool_calls
	<span class="hljs-built_in">print</span>(called)
	<span class="hljs-comment"># {</span>
	<span class="hljs-comment"># "id": 0,</span>
	<span class="hljs-comment"># "type": "function",</span>
	<span class="hljs-comment"># "function": {</span>
	<span class="hljs-comment"># "description": None,</span>
	<span class="hljs-comment"># "name": "tools",</span>
	<span class="hljs-comment"># "parameters": {</span>
	<span class="hljs-comment"># "format": "celsius",</span>
	<span class="hljs-comment"># "location": "San Francisco, CA",</span>
	<span class="hljs-comment"># "num_days": 3,</span>
	<span class="hljs-comment"># },</span>
	<span class="hljs-comment"># },</span>
	<span class="hljs-comment"># }</span><!-- HTML_TAG_END --></pre></div> <h3 class="relative group"><a id="tool-choice-configuration" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#tool-choice-configuration"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Tool Choice Configuration</span></h3> <p data-svelte-h="svelte-13rggpe">When configuring how the model interacts with tools during a chat completion, there are several options for determining if or how a tool should be called. These options are controlled by the <code>tool_choice</code> parameter, which specifies the behavior of the model in relation to tool usage. The following modes are supported:</p> <ol><li><p data-svelte-h="svelte-xbr04b"><strong><code>auto</code></strong>:</p> <ul><li data-svelte-h="svelte-kqytsb">The model decides whether to call a tool or generate a response message based on the user’s input.</li> <li data-svelte-h="svelte-1jg6yx2">If tools are provided, this is the default mode.</li> <li>Example usage:
	<div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->tool_choice=<span class="hljs-string">"auto"</span><!-- HTML_TAG_END --></pre></div></li></ul></li> <li><p data-svelte-h="svelte-11bn5m0"><strong><code>none</code></strong>:</p> <ul><li data-svelte-h="svelte-klffq4">The model will never call any tools and will only generate a response message.</li> <li data-svelte-h="svelte-up128b">If no tools are provided, this is the default mode.</li> <li>Example usage:
	<div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->tool_choice=<span class="hljs-string">"none"</span><!-- HTML_TAG_END --></pre></div></li></ul></li> <li><p data-svelte-h="svelte-1u693el"><strong><code>required</code></strong>:</p> <ul><li data-svelte-h="svelte-9fo4bt">The model must call one or more tools and will not generate a response message on its own.</li> <li>Example usage:
	<div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->tool_choice=<span class="hljs-string">"required"</span><!-- HTML_TAG_END --></pre></div></li></ul></li> <li><p data-svelte-h="svelte-gefj73"><strong>Specific Tool Call by Function Name</strong>:</p> <ul><li data-svelte-h="svelte-1o336wz">You can force the model to call a specific tool either by specifying the tool function directly or by using an object definition.</li> <li>Two ways to do this:<ol><li>Provide the function name as a string:
	<div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->tool_choice=<span class="hljs-string">"get_current_weather"</span><!-- HTML_TAG_END --></pre></div></li> <li>Use the function object format:
	<div class="code-block relative"><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->tool_choice={
	<span class="hljs-string">"type"</span>: <span class="hljs-string">"function"</span>,
	<span class="hljs-string">"function"</span>: {
	<span class="hljs-string">"name"</span>: <span class="hljs-string">"get_current_weather"</span>
	}
	}<!-- HTML_TAG_END --></pre></div></li></ol></li></ul></li></ol> <p data-svelte-h="svelte-6l9nzs">These options allow flexibility when integrating tools with the chat completions endpoint. You can configure the model to either rely on tools automatically or force it to follow a predefined behavior, based on the needs of the task at hand.</p> <hr> <table data-svelte-h="svelte-9e6c3b"><thead><tr><th><strong>Tool Choice Option</strong></th> <th><strong>Description</strong></th> <th><strong>When to Use</strong></th></tr></thead> <tbody><tr><td><code>auto</code></td> <td>The model decides whether to call a tool or generate a message. This is the default if tools are provided.</td> <td>Use when you want the model to decide when a tool is necessary.</td></tr> <tr><td><code>none</code></td> <td>The model generates a message without calling any tools. This is the default if no tools are provided.</td> <td>Use when you do not want the model to call any tools.</td></tr> <tr><td><code>required</code></td> <td>The model must call one or more tools and will not generate a message on its own.</td> <td>Use when a tool call is mandatory, and you do not want a regular message generated.</td></tr> <tr><td>Specific Tool Call (<code>name</code> or object)</td> <td>Force the model to call a specific tool either by specifying its name (<code>tool_choice="get_current_weather"</code>) or using an object.</td> <td>Use when you want to restrict the model to calling a particular tool for the response.</td></tr></tbody></table> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/huggingface/text-generation-inference/blob/main/docs/source/basic_tutorials/using_guidance.md" target="_blank"><span data-svelte-h="svelte-1kd6by1"><</span> <span data-svelte-h="svelte-x0xyl0">></span> <span data-svelte-h="svelte-1dajgef"><span class="underline ml-1.5">Update</span> on GitHub</span></a> <p></p>

	<script>
	{
	__sveltekit_1q4976k = {
	assets: "/docs/text-generation-inference/pr_2965/en",
	base: "/docs/text-generation-inference/pr_2965/en",
	env: {}
	};

	const element = document.currentScript.parentElement;

	const data = [null,null];

	Promise.all([
	import("/docs/text-generation-inference/pr_2965/en/_app/immutable/entry/start.6569fc45.js"),
	import("/docs/text-generation-inference/pr_2965/en/_app/immutable/entry/app.98c60904.js")
	]).then(([kit, app]) => {
	kit.start(app, element, {
	node_ids: [0, 12],
	data,
	form: null,
	error: null
	});
	});
	}
	</script>

Xet Storage Details

Size:: 71.1 kB
Xet hash:: db92796b9ce9235daeaf9f87d31faf4da2498d1587cf7e66d7e4b5c26cd44d1f

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.