https://github.com/daveminer/bert-serv
FinBERT pre-trained models as a containerized HTTP service.
https://github.com/daveminer/bert-serv
celery django docker-compose finbert pytorch
Last synced: 4 months ago
JSON representation
FinBERT pre-trained models as a containerized HTTP service.
- Host: GitHub
- URL: https://github.com/daveminer/bert-serv
- Owner: daveminer
- Created: 2022-12-13T05:57:28.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-05-15T04:12:16.000Z (about 1 year ago)
- Last Synced: 2025-06-25T22:45:04.831Z (12 months ago)
- Topics: celery, django, docker-compose, finbert, pytorch
- Language: Python
- Homepage:
- Size: 125 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
_______ _______ ______ _______ _______ _______ ______ __ __
| _ || || _ | | | | || || _ | | | | |
| |_| || ___|| | || |_ _| ____ | _____|| ___|| | || | |_| |
| || |___ | |_||_ | | |____| | |_____ | |___ | |_||_ | |
| _ | | ___|| __ | | | |_____ || ___|| __ || |
| |_| || |___ | | | | | | _____| || |___ | | | | | |
|_______||_______||___| |_| |___| |_______||_______||___| |_| |___|
[](https://github.com/daveminer/BERT-serv/actions/workflows/ci.yml)
[](https://codecov.io/gh/daveminer/BERT-serv)
**BERT-serv** provides [FinBERT](https://github.com/ProsusAI/finBERT) sentiment as a service. Send financial text via HTTP and get sentiment analysis back from [these pretrained models](https://github.com/yya518/FinBERT).
:exclamation: Only [this sentiment model](https://huggingface.co/yiyanghkust/finbert-tone) is implemented at this time.
## Why
- FinBERT analysis made available on-demand to HTTP clients (no Python required!)
- Avoid adding [PyTorch](https://pytorch.org/) dependencies to other parts of your system
- Results are saved and can be queried
- Analysis requests are handled asynchronously
## Run the Local Demo
Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) if needed.
```
git clone https://github.com/daveminer/BERT-serv.git
cd BERT-serv
cp .env.dist .env
docker-compose up
```
BERT-serv is now running on local port 8000!
## How to Use
### Request sentiment analysis on text
Send a POST request to the `/sentiment/new/` path. A `callback_url` may be specified in
the query parameters for asynchrous use cases and long-running sentiment analyses. This callback
will have a JSON object in the body with an array of the new sentiment record ids: `{"ids": [95, 96]}`
The body of the POST request must be a list of objects, each of which containes these fields:
- `article_id`: An identifier for the text; this ends up on the database record as well as in the callback payload.
- `tags`: The tags to be associated with the sentiment record;
useful for filtering on existing sentiment records.
- `text`: The text to analyze
```
curl --request POST \
--url 'http://localhost:8000/sentiment/new?callback_url=http://web:8000/callback/sentiment/new/' \
--header 'Content-Type: application/json' \
--data '[{"article_id": 1, "tags": ["stock"], "text": "year over year growth is increasing"}, {"article_id": 2, "tags": ["stock"], "text": "there is a shortage of capital, and we need extra financing"}]'
```
##### Callback
If a callback is specified, the following payload will be sent to the callback URL:
```
{
"results": [
{
"article_id": 1,
"sentiment": {
"label": "Positive",
"score": 0.9999837875366211
"tags": ["stock"]
}
}
]
}
```
### Look up sentiment results
Response defaults to HTML unless `application/json` is specified in the `Accept` header.
##### Get last 100 sentiments
Make a GET request to the `/sentiment/` path.
```
curl --request GET \
--url http://localhost:8000/sentiment/ \
--header 'Accept: application/json'
```
The output will look like this:
```
[
{
"created_at": "2024-08-23T02:19:45.657",
"label": "Negative",
"score": 0.9966173768043518,
"tags": ["stock"],
"text": "there is a shortage of capital, and we need extra financing"
},
{
"created_at": "2024-08-23T02:19:45.657",
"label": "Positive",
"score": 0.9999837875366211,
"tags": ["stock"],
"text": "year over year growth is increasing"
}
]
```
##### Get a specific sentiment by index
Add the index of the sentiment resource to the `sentiment` path:
```
curl --request GET \
--url http://localhost:8000/sentiment/1/ \
--header 'Accept: application/json'
```
### Filter sentiments
##### By Tag
A comma-separated list of tags may be specified in the `tags` query parameter.
##### By Age
The `period` query parameter accepts an integer that specifies how many days back to look for sentiments.
### Pagination
The sentiment index controller uses Django's built in [pagination](https://docs.djangoproject.com/en/5.0/topics/pagination/).
The `/sentiment/` path accepts `page_size` and a `page` query parameters.
## Development Environment Setup
The `make dev-services` command will start all of the services besides the app. This allows for the app to be started and stopped (with `make app`) in the terminal for convenience during development. Note that `make dev-services` requires the Postgres database to be running. A database
can be started with `make db` if one isn't running already.
### Setting up the environment
Local development requires that the local environment is set up alongside the containerized services.
#### (If needed) Install Python (Ubuntu)
```
sudo apt install python3
```
#### (If needed) Install pip3 (Ubuntu)
```
sudo apt install python3-pip -y
```
#### (If needed) Install virtualenv
```
sudo apt-get update
sudo apt install python3.12-venv
```
##### Create the virtualenv
```
python3 -m virtualenv env
```
##### Load
```
python3 -m venv .venv
```
##### Activate
```
source .venv/bin/activate
```
Notes:
- `make services` requires [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- `make deps` will install dependencies via pip3 and must be run before `make app`. This can take a few minutes as the PyTorch dependencies are sizable.
## Service setup
The `docker-compose-services.yml` is intended to stand this service and dependencies up against an external Postgres instance.
```
# To run:
docker-compose -f docker-compose-service.yml up
```