Skip to content

Commit a5c20e6

Browse files
RobGeadaRobGeada
authored
Merge pull request trustyai-explainability#34 from m-misiura/local-example-hf-detector
CHORE: added examples of how to run the HF detectors locally within the README
2 parents cfbd512 + c8d10f0 commit a5c20e6

File tree

3 files changed

+270
-105
lines changed

3 files changed

+270
-105
lines changed

‎README.md

Lines changed: 3 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -24,112 +24,10 @@ At the moment, the following detectors are supported:
2424
## Running locally
2525
* `builtIn`: podman run -p 8080:8080 $BUILT_IN_IMAGE
2626

27-
### File Type Validation Example
28-
```bash
29-
curl -X POST http://localhost:8080/api/v1/text/contents \
30-
-H "Content-Type: application/json" \
31-
-d '{
32-
"contents": [
33-
"{\"hello\": \"message\"}",
34-
"not valid json"
35-
],
36-
"detector_params": {
37-
"file_type": [
38-
"json"
39-
]
40-
}
41-
}'
42-
```
43-
Response:
44-
```json
45-
[
46-
[],
47-
[
48-
{
49-
"start": 0,
50-
"end": 14,
51-
"text": "not valid json",
52-
"detection": "invalid_json",
53-
"detection_type": "file_type",
54-
"score": 1.0,
55-
"evidences": null
56-
}
57-
]
58-
]
59-
```
27+
## Examples
6028

61-
### PII Validation Example
62-
```bash
63-
curl -X POST http://localhost:8080/api/v1/text/contents \
64-
-H "Content-Type: application/json" \
65-
-d '{
66-
"contents": [
67-
"Hi my email is [email protected]",
68-
"There is a party@my house and you can reach me at 123-456-7890"
69-
],
70-
"detector_params": {
71-
"regex": [
72-
"email", "us-phone-number"
73-
]
74-
}
75-
}' | jq
76-
```
77-
Response:
78-
```json
79-
[
80-
[
81-
{
82-
"start": 15,
83-
"end": 26,
84-
"text": "[email protected]",
85-
"detection": "email_address",
86-
"detection_type": "pii",
87-
"score": 1.0,
88-
"evidences": null
89-
}
90-
],
91-
[
92-
{
93-
"start": 50,
94-
"end": 62,
95-
"text": "123-456-7890",
96-
"detection": "us-phone-number",
97-
"detection_type": "pii",
98-
"score": 1.0,
99-
"evidences": null
100-
}
101-
]
102-
]
103-
```
104-
105-
### Get list of built-in detection algorithms:
106-
```bash
107-
curl http://localhost:8080/registry | jq
108-
```
109-
Response:
110-
```json
111-
{
112-
"regex": {
113-
"credit-card": "Detect credit cards in the text contents (Visa, MasterCard, Amex, Discover, Diners Club, JCB) with Luhn check",
114-
"email": "Detect email addresses in the text contents",
115-
"ipv4": "Detect IPv4 addresses in the text contents",
116-
"ipv6": "Detect IPv6 addresses in the text contents",
117-
"us-phone-number": "Detect US phone numbers in the text contents",
118-
"us-social-security-number": "Detect social security numbers in the text contents",
119-
"uk-post-code": "Detect UK post codes in the text contents",
120-
"$CUSTOM_REGEX": "Replace $CUSTOM_REGEX with a custom regex to define your own regex detector"
121-
},
122-
"file_type": {
123-
"json": "Detect if the text contents is not valid JSON",
124-
"xml": "Detect if the text contents is not valid XML",
125-
"yaml": "Detect if the text contents is not valid YAML",
126-
"json-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided JSON schema. To specify a schema, replace $SCHEMA with a JSON schema.",
127-
"xml-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided XML schema. To specify a schema, replace $SCHEMA with an XML Schema Definition (XSD)",
128-
"yaml-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided schema. To specify a schema, replace $SCHEMA with a JSON schema. That's not a typo, you validate YAML with a JSON schema!"
129-
}
130-
}
131-
132-
```
29+
- Check out [built-in detector examples](docs/builtIn_examples.md) to see how to use the built-in detectors for file type validation and personally identifiable information (PII) detection
30+
- Check out [Hugging Face detector examples](docs/hf_examples.md) to see how to use the Hugging Face detectors for detecting toxic content and prompt injection
13331

13432
## API
13533
See [IBM Detector API](https://foundation-model-stack.github.io/fms-guardrails-orchestrator/?urls.primaryName=Detector+API)

‎docs/builtin_examples.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
## Built-In Detector Examples
2+
3+
### File Type Validation Example
4+
```bash
5+
curl -X POST http://localhost:8080/api/v1/text/contents \
6+
-H "Content-Type: application/json" \
7+
-d '{
8+
"contents": [
9+
"{\"hello\": \"message\"}",
10+
"not valid json"
11+
],
12+
"detector_params": {
13+
"file_type": [
14+
"json"
15+
]
16+
}
17+
}'
18+
```
19+
Response:
20+
```json
21+
[
22+
[],
23+
[
24+
{
25+
"start": 0,
26+
"end": 14,
27+
"text": "not valid json",
28+
"detection": "invalid_json",
29+
"detection_type": "file_type",
30+
"score": 1.0,
31+
"evidences": null
32+
}
33+
]
34+
]
35+
```
36+
37+
### PII Validation Example
38+
```bash
39+
curl -X POST http://localhost:8080/api/v1/text/contents \
40+
-H "Content-Type: application/json" \
41+
-d '{
42+
"contents": [
43+
"Hi my email is [email protected]",
44+
"There is a party@my house and you can reach me at 123-456-7890"
45+
],
46+
"detector_params": {
47+
"regex": [
48+
"email", "us-phone-number"
49+
]
50+
}
51+
}' | jq
52+
```
53+
Response:
54+
```json
55+
[
56+
[
57+
{
58+
"start": 15,
59+
"end": 26,
60+
"text": "[email protected]",
61+
"detection": "email_address",
62+
"detection_type": "pii",
63+
"score": 1.0,
64+
"evidences": null
65+
}
66+
],
67+
[
68+
{
69+
"start": 50,
70+
"end": 62,
71+
"text": "123-456-7890",
72+
"detection": "us-phone-number",
73+
"detection_type": "pii",
74+
"score": 1.0,
75+
"evidences": null
76+
}
77+
]
78+
]
79+
```
80+
81+
### Get list of built-in detection algorithms:
82+
```bash
83+
curl http://localhost:8080/registry | jq
84+
```
85+
Response:
86+
```json
87+
{
88+
"regex": {
89+
"credit-card": "Detect credit cards in the text contents (Visa, MasterCard, Amex, Discover, Diners Club, JCB) with Luhn check",
90+
"email": "Detect email addresses in the text contents",
91+
"ipv4": "Detect IPv4 addresses in the text contents",
92+
"ipv6": "Detect IPv6 addresses in the text contents",
93+
"us-phone-number": "Detect US phone numbers in the text contents",
94+
"us-social-security-number": "Detect social security numbers in the text contents",
95+
"uk-post-code": "Detect UK post codes in the text contents",
96+
"$CUSTOM_REGEX": "Replace $CUSTOM_REGEX with a custom regex to define your own regex detector"
97+
},
98+
"file_type": {
99+
"json": "Detect if the text contents is not valid JSON",
100+
"xml": "Detect if the text contents is not valid XML",
101+
"yaml": "Detect if the text contents is not valid YAML",
102+
"json-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided JSON schema. To specify a schema, replace $SCHEMA with a JSON schema.",
103+
"xml-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided XML schema. To specify a schema, replace $SCHEMA with an XML Schema Definition (XSD)",
104+
"yaml-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided schema. To specify a schema, replace $SCHEMA with a JSON schema. That's not a typo, you validate YAML with a JSON schema!"
105+
}
106+
}
107+
```

‎docs/hf_examples.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
## Hugging Face Detector Examples
2+
3+
### Detecting toxic content using Hugging Face Detectors
4+
5+
1. Set model variables and download the model locally, for example to store the [HAP Detector](https://huggingface.co/ibm-granite/granite-guardian-hap-38m) in a `hf-detectors` directory:
6+
7+
```bash
8+
export HF_MODEL=ibm-granite/granite-guardian-hap-38m
9+
export DETECTOR_STORAGE=hf-detectors
10+
export DETECTOR_NAME=$(basename "$HF_MODEL")
11+
export DETECTOR_DIR=$DETECTOR_STORAGE/$DETECTOR_NAME
12+
13+
huggingface-cli download "$HF_MODEL" --local-dir "$DETECTOR_DIR"
14+
```
15+
16+
the instructions above assume you have [huggingface-cli](https://huggingface.co/docs/huggingface_hub/en/guides/cli) installed, which you can do inside your Python virtual environment:
17+
18+
```bash
19+
pip install "huggingface_hub[cli]"
20+
```
21+
22+
2. Build the image for the Hugging Face Detector:
23+
24+
```bash
25+
export HF_IMAGE=hf-detector:latest
26+
podman build -f detectors/Dockerfile.hf -t $HF_IMAGE detectors
27+
```
28+
29+
3. Run the detector container, mounting the model directory you downloaded in the previous step:
30+
31+
```bash
32+
podman run --rm -p 8000:8000 \
33+
-e MODEL_DIR=/mnt/models/$DETECTOR_NAME \
34+
-v $(pwd)/$DETECTOR_DIR:/mnt/models/$DETECTOR_NAME:Z \
35+
$HF_IMAGE
36+
```
37+
38+
4. Invoke the detector with a POST request; in a separate terminal, run:
39+
40+
```bash
41+
curl -X POST \
42+
http://localhost:8000/api/v1/text/contents \
43+
-H 'accept: application/json' \
44+
-H 'detector-id: hap' \
45+
-H 'Content-Type: application/json' \
46+
-d '{
47+
"contents": ["You dotard, I really hate this stuff", "I simply love this stuff"],
48+
"detector_params": {}
49+
}' | jq
50+
```
51+
52+
5. You should see a response like this:
53+
54+
```json
55+
[
56+
[
57+
{
58+
"start": 0,
59+
"end": 36,
60+
"detection": "sequence_classifier",
61+
"detection_type": "sequence_classification",
62+
"score": 0.9634233713150024,
63+
"sequence_classification": "LABEL_1",
64+
"sequence_probability": 0.9634233713150024,
65+
"token_classifications": null,
66+
"token_probabilities": null,
67+
"text": "You dotard, I really hate this stuff",
68+
"evidences": []
69+
}
70+
],
71+
[
72+
{
73+
"start": 0,
74+
"end": 24,
75+
"detection": "sequence_classifier",
76+
"detection_type": "sequence_classification",
77+
"score": 0.00016677979147061706,
78+
"sequence_classification": "LABEL_0",
79+
"sequence_probability": 0.00016677979147061706,
80+
"token_classifications": null,
81+
"token_probabilities": null,
82+
"text": "I simply love this stuff",
83+
"evidences": []
84+
}
85+
]
86+
]
87+
```
88+
89+
### Detecting prompt injection content using Hugging Face Detectors
90+
91+
- Following the steps above, you can readily use the Hugging Face Detector with a different model, such as the [prompt injection classifier](https://huggingface.co/protectai/deberta-v3-base-prompt-injection-v2)
92+
93+
```bash
94+
export HF_MODEL=protectai/deberta-v3-base-prompt-injection-v2
95+
export DETECTOR_STORAGE=hf-detectors
96+
export DETECTOR_NAME=$(basename "$HF_MODEL")
97+
export DETECTOR_DIR=$DETECTOR_STORAGE/$DETECTOR_NAME
98+
99+
huggingface-cli download "$HF_MODEL" --local-dir "$DETECTOR_DIR"
100+
```
101+
102+
- then spin up the container as before:
103+
104+
```bash
105+
podman run --rm -p 8000:8000 \
106+
-e MODEL_DIR=/mnt/models/$DETECTOR_NAME \
107+
-v $(pwd)/$DETECTOR_DIR:/mnt/models/$DETECTOR_NAME:Z \
108+
$HF_IMAGE
109+
```
110+
111+
- and invoke the detector with a POST request; in a separate terminal, run:
112+
113+
```bash
114+
curl -X POST \
115+
http://localhost:8000/api/v1/text/contents \
116+
-H 'accept: application/json' \
117+
-H 'detector-id: prompt-injection' \
118+
-H 'Content-Type: application/json' \
119+
-d '{
120+
"contents": ["Trolol?", "How to make a delicious espresso?"],
121+
"detector_params": {}
122+
}' | jq
123+
```
124+
125+
which should yield a response like this:
126+
127+
```json
128+
[
129+
[
130+
{
131+
"start": 0,
132+
"end": 48,
133+
"detection": "sequence_classifier",
134+
"detection_type": "sequence_classification",
135+
"score": 0.9998816251754761,
136+
"sequence_classification": "INJECTION",
137+
"sequence_probability": 0.9998816251754761,
138+
"token_classifications": null,
139+
"token_probabilities": null,
140+
"text": "Trolol?",
141+
"evidences": []
142+
}
143+
],
144+
[
145+
{
146+
"start": 0,
147+
"end": 33,
148+
"detection": "sequence_classifier",
149+
"detection_type": "sequence_classification",
150+
"score": 9.671030056779273E-7,
151+
"sequence_classification": "SAFE",
152+
"sequence_probability": 9.671030056779273E-7,
153+
"token_classifications": null,
154+
"token_probabilities": null,
155+
"text": "How to make a delicious espresso?",
156+
"evidences": []
157+
}
158+
]
159+
]
160+
```

0 commit comments

Comments
 (0)