How To Call Hugging Face AI From Within an Oracle Database Using JavaScript

By Jessie Hobb On Jul 5, 2023

In this article, I will show you how to quickly create an entirely free app using a JavaScript program that runs within the free Oracle database and calls Hugging Face AI, the results of which are stored in the database and can then be accessed using SQL, JSON, REST, or any other language. All of the source code is available here.

A common flow of applications in general and AI applications specifically involves an app calling an AI service and then storing the information in the database where it may be retrieved and processed (e.g., using OML) further and/or analyzed and queried later.

By issuing the command from the database itself, the data is stored immediately and is thus also more reliable as it is in process and does not require an extra network call to persist. Further, by having the logic (and even code) reside in the database, the high availability, management, observability, etc. of the power of the Oracle database can be implicitly and inherently leveraged.

This is a unique capability of the Oracle database as it includes Java, and, as we’ll see in this blog, JavaScript runtime engines within the database itself.

Hugging Face develops tools for building applications using machine learning. It is most notable for its transformers library built for natural language processing applications and its platform that allows users to share machine learning models and datasets. It has become extremely popular over the last couple of years.

In short, we will do the following:

Create an account and select a model.
Create the Oracle database and a database user.
Add a wallet with a certificate to allow HTTPS calls.
Create a table.
Run a short JavaScript program in the database to make a call to the Hugging Face AI model and store the results in the table.
Optionally query these results using SQL, JSON, REST, etc.

Setup Hugging Face Account and AI Model

Go to https://huggingface.co and Sign Up. Go to your Profile, and click the Settings button.

Click on Access Tokens, create a token, and copy its value for use later.

Click on Models and select a model. In this case, we will select a model under the Natural Language Processing section for Question Answering.

Select a model (perhaps one of the more popular ones), notice the information in the Model Card on the left, and then select the Deploy drop-down menu on the right.

Select Inference API and then select the JavaScript option in order to see a sample code snippet to call the model.

Setup Oracle Database

We can use any flavor of the Oracle database from version 21c onward. On the cloud, we can use Oracle always free autonomous database (that’s also nice as we can expose it via the Internet and make the game truly available globally/online in a couple of minutes) or we can use the Oracle 23c Free version where we can simply install or use a container image locally. Or of course, we could use the local for dev and cloud for production, etc. and either of these options is very quick to set up.

Always Free Oracle Cloud Database Option

You can go here to set up an Oracle Cloud Always Free Autonomous Database. The prompts are very intuitive. You simply select Autonomous Transaction Processing in the Oracle Database menu screen as shown below and then click the Create Autonomous Database button. You can take all of the defaults and simply provide an admin user password.

Oracle Database Free Option

You can go here to set up the Oracle Database Free 23c.

Using the container image is very simple. You can simply execute the one line below, replacing -e ORACLE_PASSWORD=Welcome12345 with a password of your choice and replacing -v oracle-volume:/somedirectory with a directory location (or omitting it entirely if you only wish to have in-memory database). Notice the --add-host docker.for.mac.host.internal:host-gateway param that allows calls out of the container. This is the setting for Macs and will be different if running on a different OS.

docker pull 
container-registry.oracle.com/database/free:latest; docker run --add-host docker.for.mac.host.internal:host-gateway -e ORACLE_PASSWORD=Welcome12345 -v oracle-volume:/somedirectory container-registry.oracle.com/database/free:latest

Setup SQLcl (or Database Actions) and Connect

If you are using a cloud database, you can work with SQL and JavaScript by clicking Database Actions and then SQL in the OCI console to manage the cloud database.

You can also install SQLcl to manage either of the databases/options mentioned using the following steps:

Download and install from this location. This will provide an [SQLcl_INSTALL_DIR]/bin/sql executable that we will use to administer the database. For convenience, you may add [SQLcl_INSTALL_DIR]/bin to your PATH.
Login replacing [SQLcl_INSTALL_DIR] with the location of your SQLcl and replacing Welcome12345 with the one you provided as ORACLE_PASSWORD when creating the database.

Here is an example when using a local install (e.g., Oracle Database Free container image):

[SQLcl_INSTALL_DIR]/bin/sql  /nolog
SQL> connect sys@//localhost:1521/freepdb1 as sysdba
Password? (**********?) *************
Connected.

And here is an example when using a cloud database (e.g., Oracle Always Free Autonomous):

[SQLcl_INSTALL_DIR]/bin/sql  /nolog
SQL> set cloudconfig /Users/pparkins/Downloads/Wallet_xr.zip 
SQL> connect admin@mydb_tp
Password? (**********?) *************
Connected.

Create a Wallet

Create a wallet to hold the cert for SSL/HTTPS calls made from JavaScript running in the database to Hugging Face.

We are going to create the PEM for the Hugging Face API SSL certificate, store it in a wallet, upload the wallet (specifically the ewallet.p12 file) to the database, and instruct the database to use that for HTTPS calls. Specifically, we will be instructing the UTL_HTTP package mapped/used by JavaScript fetch command in the Oracle database to use that for HTTPS calls.

1. First, obtain the SSL certificate for Hugging Face (api-infeerence.hugging.face.co:443) and save it to a PEM file using the following command.

openssl s_client -connect api-inference.huggingface.co:443 -showcerts > ca_for_huggingface.pem

2. Issue the following commands at the SQLcl prompt to create a wallet, add the PEM to it, and verify by displaying the results. The -cert argument points to the PEM file you just created above.

SQL> orapki wallet create -wallet [A_DIRECTORY_FOR_WALLET] -pwd [YOUR_WALLET_PASSWORD]
SQL> orapki wallet add -wallet [A_DIRECTORY_FOR_WALLET] -pwd [YOUR_WALLET_PASSWORD] -trusted_cert -cert ca_for_huggingface.pem
SQL> orapki wallet display -wallet [A_DIRECTORY_FOR_WALLET] -pwd [YOUR_WALLET_PASSWORD]

3. You now have a wallet directory containing an ewallet.p12 file that contains the Hugging Face API cert (pem). If you haven’t already, open another terminal window, clone or download the src repos (linked at the beginning of this article), cd to the root (huggingface-javascript-oracle) directory, and copy the ewallet.p12 file into the src/main/resources directory. In other words:

cp [A_DIRECTORY_FOR_WALLET]/ewallet.p12 src/main/resources/

4. Return to the SQLcl terminal and run/install the sql/writefile.sql file from the src repos.

5. This will install the write_file stored procedure that we will call from a little Java utility that will upload our ewallet.p12 to the database for use in HTTPS calls. Back in the src repos terminal (again from in the root (huggingface-javascript-oracle) directory), run the following command, replacing the database connection values as appropriate. For example, in the case of Oracle Free container image database:

export SPRING_DATASOURCE_URL="jdbc:oracle:thin:@localhost:1521/FREEPDB1" ; export SPRING_DATASOURCE_USERNAME="sys as sysdba" ; export SPRING_DATASOURCE_PASSWORD="Welcome12345" ; java -jar target/huggingface-from-oracledb-0.0.1-SNAPSHOT.jar

You should see output such as HuggingFaceFromOracleDatabaseApplication ewallet.p12 wallet uploaded to DATA_DUMP_DIR.

6. Return to the SQLcl terminal window and run the following command to get the location of the DATA_DUMP_DIR where the ewallet.p12 file was uploaded.

select DIRECTORY_PATH from dba_directories where directory_name="DATA_PUMP_DIR";

You should see output such as the following.

DIRECTORY_PATH                                                    

/opt/oracle/admin/FREE/dpdump/FB9997ED60890BBDE0536402000AF33F

7. sql/create_aijs_acl.sql will instruct the database (UTL_HTTP package) to use the cert in the ewallet.p12 to make HTTPS calls to the host mentioned for the principal aijs. Replace the two wallet_path values in this file with the one returned from the previous /dba_directories query and replace the [WALLET_PASSWORD] value.

wallet_path => 'file:/opt/oracle/admin/FREE/dpdump/FB9997ED60890BBDE0536402000AF33F',
[...]
'file:/opt/oracle/admin/FREE/dpdump/FB9997ED60890BBDE0536402000AF33F', '[WALLET_PASSWORD]'

8. Now run the following SQL files to create the aijs user, its necessary grants, and ACLs (note that these can be further tightened for better security).

SQL> @sql/create_aijs_user.sql

SQL> @sql/create_aijs_acl.sql

9. Now connect the user and create a table to store the results of the call to Hugging Face.

SQL> connect aijs/Welcome12345;

Connected.

SQL> create table huggingfacejson (id varchar(2048));

Table HUGGINGFACEJSON created.

Now everything is ready to run.

Run the App and Manage the Results

Finally, run the HuggingFace query from the JavaScript code in the database:

SQL> @sql/huggingfacequery.sql

PL/SQL procedure successfully completed.

Then, check the JSON results stored in the table by doing a SQL query.

 
SQL> select * from huggingfacejson;

[

    {

        "score": 0.07432165741920471,

        "token": 2053,

        "token_str": "no",

        "sequence": "{ \" inputs \" : \" the answer to the universe is no. \" }"

    },

    {

        "score": 0.06657009571790695,

        "token": 2673,

        "token_str": "everything",

        "sequence": "{ \" inputs \" : \" the answer to the universe is everything. \" }"

    },

    {

        "score": 0.06470924615859985,

        "token": 4242,

        "token_str": "unknown",

        "sequence": "{ \" inputs \" : \" the answer to the universe is unknown. \" }"

    },

    {

        "score": 0.06314115226268768,

        "token": 2748,

        "token_str": "yes",

        "sequence": "{ \" inputs \" : \" the answer to the universe is yes. \" }"

    },

    {

        "score": 0.041836563497781754,

        "token": 10709,

        "token_str": "infinite",

        "sequence": "{ \" inputs \" : \" the answer to the universe is infinite. \" }"

    }

]

SQL> select * from huggingfacejson;

[

    {

        "score": 0.07432165741920471,

        "token": 2053,

        "token_str": "no",

        "sequence": "{ \" inputs \" : \" the answer to the universe is no. \" }"

    },

    {

        "score": 0.06657009571790695,

        "token": 2673,

        "token_str": "everything",

        "sequence": "{ \" inputs \" : \" the answer to the universe is everything. \" }"

    },

    {

        "score": 0.06470924615859985,

        "token": 4242,

        "token_str": "unknown",

        "sequence": "{ \" inputs \" : \" the answer to the universe is unknown. \" }"

    },

    {

        "score": 0.06314115226268768,

        "token": 2748,

        "token_str": "yes",

        "sequence": "{ \" inputs \" : \" the answer to the universe is yes. \" }"

    },

    {

        "score": 0.041836563497781754,

        "token": 10709,

        "token_str": "infinite",

        "sequence": "{ \" inputs \" : \" the answer to the universe is infinite. \" }"

    }

]

Looking at the code we just executed, we can see the JavaScript snippet:

‘js_mode=module’);
dbms_mle.drop_context(ctx);
end;
/” data-lang=”text/javascript”>

declare
  ctx dbms_mle.context_handle_t;
  SNIPPET CLOB;
begin
  ctx := dbms_mle.create_context();
  SNIPPET := q'~
  (async () => {
   await import('mle-js-fetch');
   const oracledb = require("mle-js-oracledb");
   const payload = "{\"inputs\": \"The answer to the universe is [MASK].\"}" ;
   const modelId = 'bert-base-uncased';
   const apiToken = 'YOURHUGGINGFACEAPITOKEN';
   const headers = { 'Authorization': `Bearer ${apiToken}` };
   const API_URL = `https://api-inference.huggingface.co/models/${modelId}`;
   const answer = await fetch(API_URL, {
                         method: 'POST',
                         headers: headers,
                         body: JSON.stringify(payload),
                         credentials: 'include'
                      }).then(response => response.json());
   const insertJsonSql="INSERT INTO HUGGINGFACEJSON (id) VALUES (:jsonAnswer)";
   const jsonAnswer = JSON.stringify(answer, undefined, 4);
   await  oracledb.defaultConnection().execute(insertJsonSql, {jsonAnswer});
   console.log(JSON.stringify(answer, undefined, 4));
  })();
  ~';
  dbms_mle.eval(ctx, 'JAVASCRIPT', SNIPPET, options =>'js_mode=module');
  dbms_mle.drop_context(ctx);
end;
/

Useful parameters and debug information for Hugging Face can be found in the documentation.

The results can now be queried, analyzed, etc. using SQL or JSON (simultaneously, thanks to the new JSON duality feature), REST, or even the MongoDB API.

Oracle Database is the perfect database for AI for a number of reasons, particularly as it is a vector database with capabilities such as the following already available today:

Native data types for vector representation and storage: RAW, BLOB, JSON
In-memory column store to store and search vector embeddings w/SIMD kernels for amazing performance
Extensible indexing framework to create data-model specific indices (e.g., text, spatial)
Native Oracle machine learning APIs – Modeling, classification, scoring, clustering, etc.
DMLs, parallel loading, partitioning, advanced compression, parallel query, RAC, sharding, etc.

It is also possible to call Oracle OCI AI and other services from within the Oracle database.

Conclusion

The article went into how to call Hugging Face APIs from within the Oracle database using JavaScript, thus demonstrating a powerful combination of features perfectly suited to a broad array of AI solutions and friendly to JavaScript developers.

Some other blogs related to JavaScript in the database, in general, the MultiLingual Engine (MLE) that makes it possible, etc. can be found in Martin Bach’s posts and this post about importing JavaScript ES Modules in 23c.

I look forward to any comments or questions you may have and really appreciate your time reading.